specs/001-task-crud/quickstart.md

Quickstart Guide: Task CRUD Operations

Feature: Task CRUD Operations Date: 2026-01-08 Status: Complete

Overview

This guide provides step-by-step instructions for setting up and running the Task CRUD feature locally. Follow these instructions to get the backend API and frontend UI running on your development machine.

Prerequisites

Required Software

• Python: 3.11 or higher
• Node.js: 18 or higher
• PostgreSQL: Neon Serverless PostgreSQL account (or local PostgreSQL 14+)
• Git: For version control
• Code Editor: VS Code recommended

Accounts Needed

• Neon Account: Sign up at https://neon.tech for serverless PostgreSQL
• GitHub Account: For version control (optional)

Project Structure

phase-2-full-stack-web-app/
├── backend/          # FastAPI backend
├── frontend/         # Next.js frontend
└── specs/            # Feature specifications

Backend Setup

1. Navigate to Backend Directory

cd backend

2. Create Python Virtual Environment

Windows:

python -m venv venv
venv\Scripts\activate

macOS/Linux:

python3 -m venv venv
source venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

requirements.txt should contain:

fastapi==0.104.1
sqlmodel==0.0.14
pydantic==2.5.0
uvicorn[standard]==0.24.0
alembic==1.13.0
psycopg2-binary==2.9.9
python-dotenv==1.0.0
pytest==7.4.3
httpx==0.25.2

4. Configure Environment Variables

Create .env file in backend/ directory:

cp .env.example .env

Edit .env with your database credentials:

# Database Configuration
DATABASE_URL=postgresql://user:password@host/database

# Neon PostgreSQL Example:
# DATABASE_URL=postgresql://user:password@ep-xxx.us-east-2.aws.neon.tech/neondb?sslmode=require

# Application Settings
APP_NAME=Task CRUD API
DEBUG=True
CORS_ORIGINS=http://localhost:3000

# Authentication (Placeholder for Spec 2)
# JWT_SECRET=your-secret-key-here
# JWT_ALGORITHM=HS256
# JWT_EXPIRATION_MINUTES=1440

5. Set Up Database

Initialize Alembic (if not already done):

alembic init alembic

Create initial migration:

alembic revision --autogenerate -m "Create tasks table"

Apply migrations:

alembic upgrade head

6. Run Backend Server

uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

Verify backend is running:

• Open browser: http://localhost:8000/docs
• You should see the FastAPI Swagger UI with task endpoints

7. Test Backend API

Create a test user (temporary, until Spec 2):

# Using Python shell
python
>>> from src.core.database import engine
>>> from src.models.user import User
>>> from sqlmodel import Session
>>> with Session(engine) as session:
...     user = User(email="test@example.com", name="Test User")
...     session.add(user)
...     session.commit()
...     print(f"Created user with ID: {user.id}")

Test task creation:

curl -X POST http://localhost:8000/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"title": "Test Task", "description": "Testing API"}'

Frontend Setup

1. Navigate to Frontend Directory

cd frontend

2. Install Dependencies

npm install

package.json should contain:

{
  "dependencies": {
    "next": "^16.0.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "typescript": "^5.3.0",
    "tailwindcss": "^3.4.0"
  },
  "devDependencies": {
    "@types/react": "^18.2.0",
    "@types/node": "^20.10.0",
    "autoprefixer": "^10.4.16",
    "postcss": "^8.4.32"
  }
}

3. Configure Environment Variables

Create .env.local file in frontend/ directory:

cp .env.local.example .env.local

Edit .env.local:

# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:8000

# Authentication (Placeholder for Spec 2)
# NEXT_PUBLIC_AUTH_URL=http://localhost:8000/auth

4. Configure Tailwind CSS

tailwind.config.ts:

import type { Config } from 'tailwindcss'

const config: Config = {
  content: [
    './src/pages/**/*.{js,ts,jsx,tsx,mdx}',
    './src/components/**/*.{js,ts,jsx,tsx,mdx}',
    './src/app/**/*.{js,ts,jsx,tsx,mdx}',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}
export default config

5. Run Frontend Development Server

npm run dev

Verify frontend is running:

• Open browser: http://localhost:3000
• You should see the task list page

6. Test Frontend

1. View Tasks: Navigate to http://localhost:3000
2. Create Task: Click "Add Task" button, fill form, submit
3. Edit Task: Click edit icon on a task, modify, save
4. Complete Task: Click checkbox to toggle completion
5. Delete Task: Click delete icon, confirm deletion
6. Filter Tasks: Use filter buttons (All/Active/Completed)

Development Workflow

Running Both Servers Concurrently

Terminal 1 (Backend):

cd backend
source venv/bin/activate  # or venv\Scripts\activate on Windows
uvicorn src.main:app --reload

Terminal 2 (Frontend):

cd frontend
npm run dev

Making Changes

1. Backend Changes:

   • Edit files in backend/src/
   • FastAPI auto-reloads on file changes
   • Check http://localhost:8000/docs for updated API

2. Frontend Changes:

   • Edit files in frontend/src/
   • Next.js auto-reloads on file changes
   • Check browser for updates (hot reload)

3. Database Changes:

   • Modify SQLModel models in backend/src/models/
   • Generate migration: alembic revision --autogenerate -m "description"
   • Apply migration: alembic upgrade head

Testing

Backend Tests

cd backend
pytest

Run specific test file:

pytest tests/test_task_api.py

Run with coverage:

pytest --cov=src tests/

Frontend Tests

cd frontend
npm test

Run specific test:

npm test -- TaskList.test.tsx

Troubleshooting

Backend Issues

Database connection error:

• Verify DATABASE_URL in .env is correct
• Check Neon dashboard for connection string
• Ensure database exists and is accessible

Import errors:

• Verify virtual environment is activated
• Reinstall dependencies: pip install -r requirements.txt

Port already in use:

• Change port: uvicorn src.main:app --reload --port 8001
• Or kill process using port 8000

Frontend Issues

Module not found:

• Delete node_modules/ and .next/
• Reinstall: npm install

API connection error:

• Verify backend is running on http://localhost:8000
• Check NEXT_PUBLIC_API_URL in .env.local
• Check browser console for CORS errors

Port already in use:

• Next.js will automatically try port 3001, 3002, etc.
• Or specify port: npm run dev -- -p 3001

Database Issues

Migration conflicts:

• Check alembic/versions/ for conflicting migrations
• Downgrade: alembic downgrade -1
• Delete conflicting migration file
• Regenerate: alembic revision --autogenerate -m "description"

Data not persisting:

• Check database connection
• Verify migrations applied: alembic current
• Check for transaction rollbacks in logs

API Documentation

Swagger UI (Interactive)

http://localhost:8000/docs

ReDoc (Alternative)

http://localhost:8000/redoc

OpenAPI JSON

http://localhost:8000/openapi.json

Database Management

View Database Contents

Using psql (if local PostgreSQL):

psql -d your_database
\dt  # List tables
SELECT * FROM tasks;

Using Neon Console:

1. Log in to https://console.neon.tech
2. Select your project
3. Go to "SQL Editor"
4. Run queries

Reset Database

Drop all tables and recreate:

alembic downgrade base
alembic upgrade head

Or manually:

DROP TABLE tasks CASCADE;
DROP TABLE users CASCADE;

Then run migrations again.

Environment Variables Reference

Backend (.env)

Variable	Description	Example
DATABASE_URL	PostgreSQL connection string	postgresql://user:pass@host/db
APP_NAME	Application name	Task CRUD API
DEBUG	Enable debug mode	True
CORS_ORIGINS	Allowed CORS origins	http://localhost:3000

Frontend (.env.local)

Variable	Description	Example
NEXT_PUBLIC_API_URL	Backend API URL	http://localhost:8000

Next Steps

1. Implement Authentication (Spec 2):

   • Add Better Auth integration
   • Implement JWT token generation/validation
   • Add user registration and login

2. Add Tests:

   • Write backend API tests
   • Write frontend component tests
   • Add E2E tests with Playwright

3. Deploy to Production:

   • Set up CI/CD pipeline
   • Deploy backend to cloud provider
   • Deploy frontend to Vercel/Netlify
   • Configure production database

Additional Resources

• FastAPI Documentation: https://fastapi.tiangolo.com
• Next.js Documentation: https://nextjs.org/docs
• SQLModel Documentation: https://sqlmodel.tiangolo.com
• Tailwind CSS Documentation: https://tailwindcss.com/docs
• Neon Documentation: https://neon.tech/docs

Support

For issues or questions:

1. Check the troubleshooting section above
2. Review the specification: specs/001-task-crud/spec.md
3. Check API contracts: specs/001-task-crud/contracts/
4. Review data model: specs/001-task-crud/data-model.md

Summary

You should now have:

• ✅ Backend API running on http://localhost:8000
• ✅ Frontend UI running on http://localhost:3000
• ✅ Database configured and migrated
• ✅ Ability to create, view, update, delete, and complete tasks

Ready for: Implementation phase (/sp.tasks to generate task list, then /sp.implement to execute)