From 49ef87ea50e7fbd36d60e114c5b243cb40a88f31e6360ebab7c8949da9d975e8 Mon Sep 17 00:00:00 2001
From: Timothy Kim <timothykim@fastmail.fm>
Date: Mon, 19 Jan 2026 20:38:09 -0500
Subject: [PATCH] Add CLAUDE.md for project context

Includes project structure, commands, patterns, and auto-update
instructions for Claude Code sessions.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 CLAUDE.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..a45e717
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,97 @@
+# 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