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)

1. Create account at https://neon.tech
2. Create a new project
3. 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

User Story 2: User Login ✅

• 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 Se