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)

Frontend (Better Auth)

Development Workflow

Running Tests

# Backend tests
cd backend

...