Quaestor Lite

A habit-tracking app for logging daily events and building streaks.

Tech Stack

• Frontend: Next.js 16 (App Router), React 19, TypeScript, Tailwind CSS + shadcn/ui
• Backend: FastAPI (Python 3.12), SQLAlchemy, Alembic
• Database / Auth: PostgreSQL via Supabase, JWT auth with Row-Level Security
• Infra: Docker, GCP Cloud Run, Vercel, GitHub Actions CI/CD

Quick Start

Uses Task and uv.

# 1. Configure environment
cp apps/backend/env.example apps/backend/.env.local       # add Supabase credentials
cp apps/frontend/env.example apps/frontend/.env.local     # add Supabase credentials

# 2. Start local Supabase
task up

# 3. Run services
task be-local   # backend  → http://localhost:8000
task fe-local   # frontend → http://localhost:3000

API docs are served at http://localhost:8000/docs (Swagger) and /redoc.

Common Tasks

task up / task down      # start / stop local Supabase
task be-local            # backend dev server (ENV=local)
task fe-local            # frontend dev server
task fe-types            # regenerate frontend types from OpenAPI (backend must be running)
task tf-plan ENV=staging # terraform plan  (staging|production)
task tf-apply ENV=staging# terraform apply (staging|production)

Backend commands (run from apps/backend/):

uv run pytest              # tests
uv run mypy .              # type check
uv run ruff check .        # lint
uv run alembic upgrade head            # apply migrations
uv run alembic revision -m "message"   # create migration

Project Structure

quaestor-lite/
├── apps/
│   ├── backend/    # FastAPI app, tests, Alembic migrations
│   └── frontend/   # Next.js App Router pages, components, lib
├── infra/          # Terraform (GCP) and deployment config
├── supabase/       # Local Supabase config
└── Taskfile.yml    # Task runner

Documentation

• docs/for_agent/ — architecture, codebase map, data models, API reference
• apps/backend/docs/ — backend (database, testing, load testing)
• apps/frontend/docs/ — frontend (implementation notes, security)

Security

• JWT authentication via Supabase, validated with JWKS
• Row-Level Security enforced on all tables
• Input validation with Pydantic; SQL injection protection via SQLAlchemy ORM
• CORS and SSL/TLS required for all connections

Contributing

1. Branch from main and make your changes.
2. Add tests for new features (every feature ships with backend API tests).
3. Run uv run pytest, uv run ruff check ., and uv run mypy ..
4. Open a pull request. Conventional commits preferred.