# 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.