# CLAUDE.md - Kebuu Project Context

> **Last Updated**: 2026-01-19

<!-- CLAUDE CODE INSTRUCTION:
When implementing new features, adding routes, models, or dependencies:
1. Update the relevant sections in this file (Routes, Models, Directory Structure, etc.)
2. Move completed items from Roadmap to a "Completed" section or remove them
3. Update the "Last Updated" date above
This keeps the project context accurate for future sessions.
-->

## Overview
Kebuu is a spending tracker web app built with Flask. Currently in early development with user authentication complete.

## Tech Stack
- **Backend**: Flask 3.0, SQLAlchemy, Flask-Login
- **Auth**: bcrypt password hashing, Altcha CAPTCHA (self-hosted)
- **Forms**: Flask-WTF with CSRF protection
- **Server**: Gunicorn (production), Flask dev server (local)
- **Database**: SQLite (dev), PostgreSQL (prod)

## Directory Structure
```
src/
├── app.py              # Entry point, Flask factory pattern
├── config.py           # Environment-based configuration
├── models.py           # SQLAlchemy models (User)
├── routes.py           # Blueprint routes (main)
├── forms.py            # WTForms with validators
├── altcha_utils.py     # Self-hosted CAPTCHA implementation
├── requirements.txt    # Python dependencies
├── templates/          # Jinja2 templates
└── static/css/         # Stylesheets
```

## Key Patterns
- **Flask Factory**: `create_app()` in app.py
- **Blueprints**: Routes organized in `main` blueprint
- **Singleton**: Altcha instance cached per HMAC key
- **Strong passwords**: 8+ chars, upper/lower/number/special required

## Commands

### Local Development
```bash
cd src
pip install -r requirements.txt
python app.py
```

### Docker
```bash
docker build -t kebuu .
docker run -p 5000:5000 --env-file .env.prod kebuu
```

### Testing
```bash
cd src
python -m unittest discover
```

## Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| SECRET_KEY | Flask session secret | dev-secret-key |
| DATABASE_URL | SQLAlchemy URI | sqlite:///kebuu.db |
| ALTCHA_HMAC_KEY | CAPTCHA signing key | default-hmac-key |

## Routes
| Route | Method | Auth | Description |
|-------|--------|------|-------------|
| `/` | GET | No | Redirects to signup/dashboard |
| `/signup` | GET/POST | No | User registration |
| `/dashboard` | GET | Yes | User dashboard |
| `/altcha/challenge` | GET | No | CAPTCHA challenge endpoint |

## Database Models
**User**: id, email (unique), password_hash, created_at
- `set_password()`: bcrypt hash with salt
- `check_password()`: timing-safe comparison

## Security Notes
- CSRF enabled on all forms
- Passwords hashed with bcrypt + salt
- HMAC-SHA256 for Altcha signatures
- Docker runs as non-root user (appuser)
- Timing-safe comparisons for secrets

## Roadmap / TODOs
- [ ] Spending tracker core features (transactions, categories)
- [ ] Login page (currently only signup exists)
- [ ] Password reset functionality
- [ ] User profile/settings page
- [ ] Export spending data
- [ ] Dashboard with spending analytics