# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**Spendly** — A Flask-based personal expense tracker web application structured as an educational project for students to build incrementally. Built with Flask 3.1.3, SQLite, Jinja2 templates, and custom CSS/JS.

**Tagline:** "Track every rupee. Own your finances."

## Commands

### Development
```bash
# Create virtual environment
uv venv .venv

# Activate environment
source .venv/bin/activate

# Install dependencies
uv pip install -r requirements.txt

# Run the Flask app (port 5001)
uv run app.py
# or: python app.py
```

### Testing
```bash
# Run all tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=.
```

### Linting/Quality
No linting tools configured yet. Uses standard Python style.

## Architecture

### Project Structure
```
expense-tracker/
├── app.py                 # Main Flask application with routes
├── requirements.txt       # Python dependencies
├── database/
│   ├── __init__.py
│   └── db.py             # SQLite database layer (TO BE IMPLEMENTED)
├── templates/
│   ├── base.html         # Base layout with navbar, footer, branding
│   ├── landing.html      # Marketing landing page
│   ├── login.html        # Sign in form
│   └── register.html     # Account creation form
└── static/
    ├── css/style.css     # Complete design system (CSS variables, components)
    └── js/main.js        # Empty - students add JS as features are built
```

### Key Files

**app.py** — Main Flask app with these routes:
- `GET /` — Landing page (`landing.html`)
- `GET /register` — Registration form (`register.html`)
- `GET /login` — Login form (`login.html`)
- **Placeholders** (students implement in steps):
  - `GET /logout` — Step 3
  - `GET /profile` — Step 4
  - `GET /expenses/add` — Step 7
  - `GET /expenses/<int:id>/edit` — Step 8
  - `GET /expenses/<int:id>/delete` — Step 9

**database/db.py** — Currently empty placeholder. Students must implement:
- `get_db()` — Returns SQLite connection with `row_factory` and foreign keys enabled
- `init_db()` — Creates tables using `CREATE TABLE IF NOT EXISTS`
- `seed_db()` — Inserts sample data for development

**templates/base.html** — Base layout with:
- Navbar (Spendly branding, Sign in/Get started links)
- Main content block
- Footer
- Links to `static/css/style.css` and `static/js/main.js`

**static/css/style.css** — Complete design system using CSS custom properties:
- Colors: `--ink`, `--accent` (green #1a472a), `--accent-2` (gold #c17f24), `--danger`, `--paper` variants
- Fonts: DM Serif Display (headings), DM Sans (body)
- Components: buttons (primary/ghost), forms, cards, auth layouts, hero section, feature grid
- Responsive breakpoints at 900px and 600px

## Database Schema (Expected)

Based on the project structure, the SQLite database (`expense_tracker.db`, gitignored) will likely need tables for:
- **users** — id, name, email, password_hash
- **expenses** — id, user_id, amount, category, description, date
- **categories** — id, name (optional, for predefined categories)

## Development Notes

- **Environment:** Python 3.12+ (uses CPython 3.12.13)
- **Port:** App runs on port 5001 (set in `app.py`)
- **Database file:** `expense_tracker.db` (created at runtime, gitignored)
- **Virtual env:** `.venv/` (gitignored)
- **No existing tests** — pytest is installed but no test files exist yet

## Next Steps for Implementation

1. Implement `database/db.py` with SQLite connection, schema creation, and seeding
2. Add authentication logic to `/register` and `/login` routes (POST handling, password hashing, sessions)
3. Implement `/logout` route
4. Build `/profile` page
5. Implement expense CRUD routes (`/expenses/add`, `/edit`, `/delete`)
6. Create corresponding templates for expense views
7. Add JavaScript interactions in `static/js/main.js`
8. Write tests using pytest