Todo App

A showcase of my skills and abilities to create production ready generative engineering pipelines.

📄 Read the full Technical Showcase → — deep dive into architecture, design decisions, and engineering patterns used in this project.

📐 Read the full Agentic Production Workflow Review → — how a multi-agent pipeline produced this entire application in ~25 minutes.

---

Screenshots

Login	Task List

Why This Project

I believe agentic architectures and generative engineering are the future of software development, and that the current SDLC is a model which deserves review.

This app serves as a reference implementation of how I build production software — layered architecture, typed contracts, security-first auth, structured observability, and deployment-ready infrastructure. Built in ~25 minutes using a multi-agent specification-to-code pipeline that I also hand crafted.

Is it overkill for a ToDo App? Absolutely! But that's the point.

I would deploy code of this quality to production.

Feedback?

I welcome feedback on the process and procedures leveraged here. Please drop an issue or discussion topic.

Architecture at a Glance

NiceGUI UI (server-side Python, WebSocket)
    ↓
FastAPI Routers (auto-discovered via pkgutil)
    ↓
Services (business logic, orchestration)
    ↓
Repositories (async SQLAlchemy queries, user isolation)
    ↓
PostgreSQL 16 (UUID PKs, native enums, composite indexes)

Key patterns: Repository → Service → Router layering · Auto-router discovery · Typed exception hierarchy · Structured JSON logging with request ID propagation · OAuth 2.0 with JWKS caching and stale fallback · JWT in HTTP-only cookies with transparent refresh · Partial updates via sentinel values · 85%+ test coverage enforced in CI

Tech Stack

Layer	Technology
Language	Python 3.12+
API	FastAPI (async)
ORM	SQLAlchemy 2.x + asyncpg
Frontend	NiceGUI (server-rendered, no JS build step)
Database	PostgreSQL 16
Auth	Google OAuth 2.0 → JWT (HTTP-only cookies)
Migrations	Alembic (async)
Package Manager	uv
Linting	ruff + mypy (strict)
CI/CD	GitHub Actions (lint → test → build)
Deploy	Docker Compose (local) · Helm + GKE (production)

Quick Start

git clone https://github.com/codeninja/todo-app.git
cd todo-app
make setup

cp .env.example .env
# Edit .env with Google OAuth creds, or set DEV_AUTH_BYPASS=true for local dev

make up        # Start PostgreSQL
make migrate   # Run migrations
make seed      # Seed sample data (dev mode)
make dev       # Start dev server → http://localhost:8000

Development

make test                      # Run tests with coverage (≥85%)
make lint                      # ruff check + mypy strict
make format                    # Auto-format
make migration MSG="add field" # Create Alembic migration

Project Structure

app/
├── main.py              # App factory, auto-router discovery, NiceGUI mount
├── config.py            # Pydantic BaseSettings (26 fields, validated)
├── database.py          # Async engine + session lifecycle
├── exceptions.py        # Typed exception hierarchy (12 error classes)
├── auth/                # OAuth flow, JWT, JWKS caching, auth dependencies
├── models/              # SQLAlchemy models (User, Task)
├── schemas/             # Pydantic request/response with sentinel-based PATCH
├── repositories/        # Query layer (user-scoped, no business logic)
├── services/            # Business logic (no SQL, no HTTP)
├── routers/             # REST API (auto-discovered)
├── middleware/           # JSON logging, error handlers, request ID propagation
└── ui/                  # NiceGUI pages (login, task list, task form)
tests/                   # 3,600 lines across 31 test files
deploy/
├── docker/              # Multi-stage Dockerfile, Compose, entrypoint
└── helm/                # Full Helm chart (deployment, service, ingress, migration job)
.github/workflows/       # CI: lint → test (w/ Postgres) → Docker build → commit lint

Documentation

Document	Description
Technical Showcase	Architecture deep dive, design decisions, engineering patterns
Agentic Architecture Review	Multi-agent pipeline: spec → adversarial review → task decomposition → implementation
Technical Specification	Full spec (1,382 lines) — domain model, state machines, behavioral contracts
Problem Statement	Goals, anti-goals, scope boundaries
Implementation Plan	Phased delivery plan
Task Breakdown	27 ordered tasks with acceptance criteria

Metrics

Metric	Value
Application code	~2,400 lines
Test code	~3,600 lines
Test files	31
Coverage target	≥85%
Commits	42 (conventional)
GitHub Issues	27 (1:1 with tasks)
Spec to working app	~25 minutes