wallet/.vibecoder/plan.md

Wallet App — MVP Plan

What We're Building

A personal finance wallet app where you can log income transactions, view your total balance on a dashboard, and see a complete history of all entries. The app requires login (so each user has their own data) and persists everything to SQLite.

For the user: Sign up or log in → see your total balance at a glance → add new income entries → review all transactions in a table.

How It Works

1. Auth Pages (Sign Up / Log In)

   • User creates an account or logs in with email + password
   • Session token stored in browser; backend validates on each request
   • Redirects to dashboard on success

2. Dashboard

   • Shows Total Balance (sum of all income entries for this user)
   • Quick link to add a new entry
   • Link to view full transaction history

3. Wallet Entry Page

   • Form to add a new income entry: amount, description, date
   • Submit creates the entry and returns to dashboard

4. Transaction Table

   • Lists all income entries (newest first)
   • Columns: Date, Description, Amount, Running Balance
   • Shows overall savings (total balance) at the top

Key Decisions & Why

• React frontend (you chose it): modern, component-based, easy to extend
• FastAPI backend: lightweight, fast, great for JSON APIs
• SQLite database: no external DB needed, data lives in ./data/app.db
• Session-based auth: simple, stateful; user logs in once per browser
• Income only (you chose it): simpler schema, no expense tracking yet
• Total balance metric (you chose it): single number, easy to understand

Assumptions & Defaults

• Email + password auth (no OAuth, no 2FA)
• One user per session (no multi-user dashboard)
• Amounts are decimal (e.g., 1234.56)
• Dates default to today when adding an entry
• No edit/delete of past entries (read-only history)
• No categories or tags

Out of Scope

• Expense tracking (only income)
• Recurring transactions
• Budget alerts
• Export to CSV
• Mobile app (web only)
• Dark mode

---

Technical Detail

Frontend (React)

Screens:

1. Login (/login) — email, password, submit, link to sign up
2. Sign Up (/signup) — email, password, confirm password, submit, link to login
3. Dashboard (/) — total balance card, "Add Entry" button, link to history
4. Add Entry (/add) — form (amount, description, date), submit button, cancel
5. History (/history) — table of all entries, total balance header

State & Flow:

• React Context or simple state for auth token + current user
• Redirect to /login if not authenticated
• Fetch dashboard data on mount
• Form submission posts to backend, then redirects

Backend (FastAPI)

Data Model:

User
  - id (int, PK)
  - email (str, unique)
  - password_hash (str)
  - created_at (datetime)

Entry
  - id (int, PK)
  - user_id (int, FK → User)
  - amount (Decimal)
  - description (str)
  - date (date)
  - created_at (datetime)

Endpoints:

• POST /auth/signup — create user, return token
• POST /auth/login — validate email/password, return token
• POST /auth/logout — clear session (optional, browser can just delete token)
• GET /dashboard — return total balance for logged-in user
• POST /entries — create new income entry
• GET /entries — list all entries for logged-in user (paginated or all)

Auth:

• Password hashed with bcrypt
• Session token (JWT or simple session ID) in cookie or Authorization header
• Middleware checks token on protected routes

Database:

• SQLite at ./data/app.db
• Migrations run on startup (SQLAlchemy ORM)

Data Source

• User input only (no external APIs)
• All data stored locally in SQLite

Stack

• Frontend: React 18, React Router, Fetch API
• Backend: FastAPI, SQLAlchemy ORM, Pydantic, bcrypt
• Database: SQLite
• Template: fastapi-react (pinned dependencies, known to build)

Scope

Depth: MVP. Something they could actually use: the core flow end to end, real persisted data, auth ONLY if the app is meaningless without it, sensible empty and error states. No test suite, no roles, no CI.