betterauth-fastapi-jwt-bridge

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

```

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

```

• 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

1. Clone Repository

```bash

git clone

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

```bash

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=

# 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

```bash

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=

# 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

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)
• Redirec