Timothy Kim
f7d010f28d
- Update README and CLAUDE.md with Docker-based dev workflow - Add Dockerfile for containerized deployment - Add gunicorn to requirements.txt - Dev uses volume mount for live code reloading Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
99 lines
3.1 KiB
Markdown
99 lines
3.1 KiB
Markdown
# 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**: Docker + Gunicorn (dev and prod)
|
|
- **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
|
|
|
|
### Build
|
|
```bash
|
|
docker build -t kebuu .
|
|
```
|
|
|
|
### Development
|
|
```bash
|
|
docker run -p 5000:5000 --env-file .env.dev -v $(pwd)/src:/app kebuu
|
|
```
|
|
|
|
### Production
|
|
```bash
|
|
docker run -p 5000:5000 --env-file .env.prod kebuu
|
|
```
|
|
|
|
### Testing
|
|
```bash
|
|
docker run --env-file .env.dev kebuu 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
|