kebuu.com/CLAUDE.md

CLAUDE.md - Kebuu Project Context

Last Updated: 2026-01-19

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

cd src
pip install -r requirements.txt
python app.py

Docker

docker build -t kebuu .
docker run -p 5000:5000 --env-file .env.prod kebuu

Testing

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