Todo Evolution - Hackathon II

Multi-user todo application with authentication, built for Panaversity Evolution of Todo Hackathon.

Project Overview

Phase II: Full-stack web application with user authentication

Frontend: Next.js 16 with App Router, TypeScript, Tailwind CSS
Backend: FastAPI with async operations
Database: Neon Serverless PostgreSQL
ORM: SQLModel with Alembic migrations
Authentication: Better Auth with JWT tokens (7-day expiration)
Password Hashing: Argon2id via pwdlib

Project Structure

todo_correct/
├── backend/                 # FastAPI backend
│   ├── src/
│   │   ├── api/            # API endpoints
│   │   ├── core/           # Config, database, security
│   │   ├── models/         # SQLModel entities
│   │   └── services/       # Business logic
│   ├── tests/              # Unit and integration tests
│   ├── alembic/            # Database migrations
│   ├── main.py             # Application entry point
│   └── pyproject.toml      # Python dependencies
├── frontend/               # Next.js 16 frontend
│   ├── src/
│   │   ├── app/            # App Router pages
│   │   ├── components/     # React components
│   │   ├── lib/            # Utilities (auth, validation)
│   │   └── types/          # TypeScript types
│   ├── package.json        # Node dependencies
│   └── tsconfig.json       # TypeScript config
└── specs/                  # Spec-driven development artifacts
    └── 001-setup-auth-foundation/
        ├── spec.md         # Feature specification
        ├── plan.md         # Architecture plan
        ├── tasks.md        # Implementation tasks
        ├── data-model.md   # Database schema
        └── contracts/      # API contracts

Prerequisites

Python: 3.11+
Node.js: 18+
PostgreSQL: Neon Serverless account (or local PostgreSQL)
Git: For version control

Windows Users

WSL 2 (Windows Subsystem for Linux) is required
Follow setup instructions: https://learn.microsoft.com/en-us/windows/wsl/install

Quick Start

1. Clone Repository

git clone <repository-url>
cd todo_correct

2. Database Setup (Neon)

Create account at https://neon.tech
Create a new project
Copy the connection string

3. Backend Setup

cd backend

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .
pip install -e ".[dev]"  # Development dependencies

# Create .env file
cp .env.example .env

# Edit .env with your settings:
# DATABASE_URL=postgresql+asyncpg://user:password@host/database
# BETTER_AUTH_SECRET=<generate-32-char-secret>
# CORS_ORIGINS=http://localhost:3000

# Run database migrations
alembic upgrade head

# Start development server
python main.py

Backend will run on http://localhost:8000

API Documentation: http://localhost:8000/docs

4. Frontend Setup

cd frontend

# Install dependencies
npm install

# Create .env.local file
cp .env.example .env.local

# Edit .env.local with your settings:
# DATABASE_URL=postgresql://user:password@host/database
# BETTER_AUTH_SECRET=<same-as-backend-secret>
# NEXT_PUBLIC_APP_URL=http://localhost:3000
# NEXT_PUBLIC_BACKEND_API_URL=http://localhost:8000

# Start development server
npm run dev

Frontend will run on http://localhost:3000

Features Implemented (Phase II)

User Story 1: User Registration ✅

Create new account with email, password, and name
Email format validation
Password minimum 8 characters
Duplicate email prevention
Argon2id password hashing
JWT token generation
Automatic login after registration

Authenticate with email and password
JWT token with 7-day expiration
Consistent error messages (prevents user enumeration)
Redirect to dashboard on success

User Story 3: User Logout ✅

Secure logout with Better Auth
Session cleanup
Redirect to login page
Protected route enforcement

API Endpoints

Backend (FastAPI)

Endpoint	Method	Auth	Description
`/health`	GET	No	Health check
`/api/auth/register`	POST	No	User registration
`/api/auth/login`	POST	No	User login
`/api/auth/logout`	POST	Yes	User logout
`/api/auth/me`	GET	Yes	Get current user

Frontend (Better Auth)

Endpoint	Method	Auth	Description
`/api/auth/sign-up`	POST	No	Better Auth registration
`/api/auth/sign-in/email`	POST	No	Better Auth login
`/api/auth/sign-out`	POST	Yes	Better Auth logout
`/api/auth/session`	GET	Yes	Get session

Development Workflow

Running Tests

# Backend tests
cd backend
pytest --cov=src

# Frontend tests
cd frontend
npm test

Code Quality

# Backend linting
cd backend
ruff check src/

# Frontend linting
cd frontend
npm run lint

Database Migrations

cd backend

# Create new migration
alembic revision --autogenerate -m "description"

# Apply migrations
alembic upgrade head

# Rollback one migration
alembic downgrade -1

# View migration history
alembic history

Technology Stack

Backend

Framework: FastAPI 0.115+
ORM: SQLModel 0.0.22+
Database Driver: asyncpg 0.30+
Validation: Pydantic 2.10+
Password Hashing: pwdlib with Argon2
JWT: PyJWT 2.9+
Migrations: Alembic 1.14+
Rate Limiting: slowapi 0.1.9+
Server: Uvicorn

Frontend

Framework: Next.js 16
UI Library: React 19
Language: TypeScript 5.7+
Authentication: Better Auth 1.2+
Validation: Zod 3.24+
HTTP Client: Axios 1.7+
Styling: Tailwind CSS 3.4+
Testing: Playwright 1.49+

Database

Provider: Neon Serverless PostgreSQL
Connection Pooling: Configured (5-10 connections)
Migrations: Alembic

Security Features

✅ Argon2id password hashing (PHC 2015 winner)
✅ JWT tokens with HS256 signature
✅ HTTP-only cookies (Better Auth)
✅ CSRF protection (Better Auth)
✅ CORS configuration
✅ Rate limiting (prevent brute force)
✅ SQL injection prevention (ORM parameterized queries)
✅ Input validation (Pydantic + Zod)
✅ Consistent error messages (prevent user enumeration)
✅ Environment-based secrets (never committed)

Performance Targets

Metric	Target	Status
Login Response	< 500ms	✅
Registration Flow	< 30s	✅
Logout Response	< 2s	✅
JWT Validation	< 100ms	✅
Concurrent Users	100/instance	⏳ (to be tested)

Troubleshooting

Backend won't start

Check DATABASE_URL is correct
Verify PostgreSQL is accessible
Run alembic upgrade head to apply migrations
Check logs in console

Frontend won't start

Run npm install to ensure dependencies are installed
Check .env.local has all required variables
Verify NEXT_PUBLIC_BACKEND_API_URL points to running backend
Clear .next cache: rm -rf .next

Authentication not working

Ensure BETTER_AUTH_SECRET matches between frontend and backend
Check browser cookies are enabled
Verify database connection (Better Auth stores sessions)
Check browser console for errors

Database connection errors

Verify DATABASE_URL format is correct
Check Neon database is active
Test connection with psql or database client
Review firewall/network settings

Next Steps (Phase III)

AI-powered chatbot with OpenAI Agents SDK
MCP server for task management
Conversation history persistence
Natural language task creation
OpenAI ChatKit integration

Deployment

Environment Variables

Backend (.env)

# Database (required)
DATABASE_URL=postgresql+asyncpg://user:password@host:5432/database

# Better Auth JWT Configuration (required)
BETTER_AUTH_SECRET=<generate-32-char-secret>  # Generate with: openssl rand -hex 32
BETTER_AUTH_JWKS_URL=http://localhost:3000/.well-known/jwks.json
BETTER_AUTH_ISSUER=http://localhost:3000

# CORS Configuration (required)
FRONTEND_URL=http://localhost:3000  # Update for production
CORS_ORIGINS=http://localhost:3000  # Comma-separated list for multiple origins

# Server Configuration (optional)
HOST=0.0.0.0
PORT=8000
LOG_LEVEL=INFO

# Phase V (deferred)
# SENTRY_DSN=<your-sentry-dsn>  # External monitoring
# DATADOG_API_KEY=<your-datadog-key>

Frontend (.env.local)

# Database (required - same as backend)
DATABASE_URL=postgresql://user:password@host:5432/database

# Better Auth (required - same secret as backend)
BETTER_AUTH_SECRET=<same-as-backend-secret>

# Application URLs (required)
NEXT_PUBLIC_APP_URL=http://localhost:3000  # Frontend URL
NEXT_PUBLIC_BACKEND_URL=http://localhost:8000/api/v1  # Backend API URL

# Production: Update URLs
# NEXT_PUBLIC_APP_URL=https://yourdomain.com
# NEXT_PUBLIC_BACKEND_URL=https://api.yourdomain.com/api/v1

CORS Configuration

The backend uses a strict CORS policy for security:

Development (backend/.env):

FRONTEND_URL=http://localhost:3000

Production (backend/.env):

FRONTEND_URL=https://yourdomain.com  # Your production frontend URL

Multiple origins (staging + production):

FRONTEND_URL=https://yourdomain.com,https://staging.yourdomain.com

The CORS middleware (in backend/src/main.py) is configured to:

Allow credentials (cookies for JWT)
Expose X-Correlation-ID header for debugging
Only allow specific origins (no wildcards in production)

Better Auth Setup

Better Auth is configured with JWT plugin for stateless authentication:

Backend JWT Configuration

Generate secret key:
```
openssl rand -hex 32
```

Set environment variables in backend/.env:

BETTER_AUTH_SECRET=<generated-secret>
BETTER_AUTH_JWKS_URL=http://localhost:3000/.well-known/jwks.json
BETTER_AUTH_ISSUER=http://localhost:3000

JWT verification is handled by backend/src/services/jwks.py:
- Fetches public keys from JWKS endpoint
- Caches keys for 1 hour (TTL)
- Verifies EdDSA/Ed25519 signatures
- Validates issuer and expiration

Frontend Better Auth Configuration

The frontend is configured in frontend/src/lib/auth.ts:

import { betterAuth } from "better-auth";
import { jwt } from "better-auth/plugins";

export const auth = betterAuth({
  database: { ... },
  plugins: [
    jwt({
      algorithm: "EdDSA",  // Ed25519 for fast verification
      issuer: process.env.NEXT_PUBLIC_APP_URL,
      expiresIn: "1h",
      jwks: { enabled: true },  // Enable JWKS endpoint
    }),
  ],
});

Key features:

EdDSA/Ed25519 algorithm (10-20x faster than RS256)
JWT stored in httpOnly cookies (secure by default)
1-hour token expiration
JWKS endpoint at /.well-known/jwks.json

Production Deployment

Vercel (Frontend)

Connect repository to Vercel
Set environment variables:
- DATABASE_URL
- BETTER_AUTH_SECRET
- NEXT_PUBLIC_APP_URL=https://yourdomain.com
- NEXT_PUBLIC_BACKEND_URL=https://api.yourdomain.com/api/v1
Deploy: Automatic on git push

Backend Hosting Options

Option 1: Railway / Render

Auto-deploy from GitHub
Set environment variables in dashboard
Add PostgreSQL addon or use Neon

Option 2: Docker + Cloud Run / AWS ECS

# backend/Dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Option 3: VM (DigitalOcean, AWS EC2)

# Install dependencies
sudo apt update && sudo apt install python3.11 python3-pip postgresql-client

# Setup application
git clone <repo>
cd backend
pip install -e .

# Setup systemd service
sudo nano /etc/systemd/system/todo-backend.service

# Start service
sudo systemctl enable todo-backend
sudo systemctl start todo-backend

Security Checklist

Before deploying to production:

[ ] Generate new BETTER_AUTH_SECRET (don't reuse dev secret)
[ ] Update FRONTEND_URL to production domain
[ ] Enable HTTPS (required for httpOnly cookies)
[ ] Set LOG_LEVEL=WARNING or ERROR in production
[ ] Verify CORS allows only production origins
[ ] Configure database connection pooling
[ ] Enable database SSL (Neon provides this by default)
[ ] Set up monitoring (Sentry/DataDog in Phase V)

Monitoring & Debugging

Correlation IDs: Every request has a unique X-Correlation-ID header:

Generated by frontend (UUID v4)
Propagated to backend
Included in all logs
Shown in error toasts (first 8 chars)

Structured Logging: All logs are JSON-formatted per FR-029:

{
  "timestamp": "2025-12-29T10:30:00Z",
  "level": "INFO",
  "correlation_id": "abc123...",
  "user_id": "user_123",
  "endpoint": "/api/v1/user_123/tasks",
  "http_method": "GET",
  "status_code": 200,
  "duration_ms": 45
}

Log Files:

Backend: backend/logs/app.log (rotates at 10MB, keeps 5 backups)
Frontend: Browser console (development) / Vercel logs (production)

Contributing

This project follows Spec-Driven Development:

Feature specifications in /specs
Architecture planning in plan.md
Task breakdown in tasks.md
Implementation via Claude Code

License

MIT License - Panaversity Evolution of Todo Hackathon II

Resources

Hackathon Details: https://docs.google.com/document/d/1pZ-3-l-k...
Next.js Docs: https://nextjs.org/docs
FastAPI Docs: https://fastapi.tiangolo.com
Better Auth Docs: https://better-auth.com
SQLModel Docs: https://sqlmodel.tiangolo.com
Neon Docs: https://neon.tech/docs

Built with Claude Code using Spec-Driven Development methodology.