# FastAPI Demo App Plan

## 1. Define the Scope

Build a small task-management API that demonstrates:

- FastAPI routing
- Request and response validation with Pydantic
- CRUD operations
- Dependency injection
- Database integration
- Authentication
- Error handling
- Automated tests
- Interactive API documentation
- Containerized local development

## 2. Suggested Technology Stack

- **API framework:** FastAPI
- **Server:** Uvicorn
- **Database:** SQLite for the demo
- **ORM:** SQLAlchemy
- **Validation:** Pydantic
- **Authentication:** JWT bearer tokens
- **Testing:** pytest and FastAPI `TestClient`
- **Migrations:** Alembic
- **Packaging:** `pyproject.toml`
- **Containerization:** Docker

## 3. Core Features

### Health Check

- `GET /health`
- Return application and database status

### Authentication

- `POST /auth/register`
- `POST /auth/login`
- Hash passwords securely
- Issue JWT access tokens
- Protect task endpoints

### Task Management

- `POST /tasks`
- `GET /tasks`
- `GET /tasks/{task_id}`
- `PATCH /tasks/{task_id}`
- `DELETE /tasks/{task_id}`
- Allow users to access only their own tasks
- Support pagination and status filtering

## 4. Data Models

### User

- `id`
- `email`
- `hashed_password`
- `created_at`

### Task

- `id`
- `title`
- `description`
- `completed`
- `owner_id`
- `created_at`
- `updated_at`

## 5. Project Structure

```text
fastapi-demo/
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── config.py
│   ├── database.py
│   ├── dependencies.py
│   ├── models/
│   │   ├── __init__.py
│   │   ├── task.py
│   │   └── user.py
│   ├── schemas/
│   │   ├── __init__.py
│   │   ├── auth.py
│   │   ├── task.py
│   │   └── user.py
│   ├── routers/
│   │   ├── __init__.py
│   │   ├── auth.py
│   │   ├── health.py
│   │   └── tasks.py
│   └── services/
│       ├── __init__.py
│       ├── auth.py
│       └── tasks.py
├── migrations/
├── tests/
│   ├── conftest.py
│   ├── test_auth.py
│   ├── test_health.py
│   └── test_tasks.py
├── .env.example
├── .gitignore
├── alembic.ini
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
└── README.md
```

## 6. Implementation Phases

### Phase 1: Bootstrap

- [ ] Create the project and virtual environment
- [ ] Add FastAPI, Uvicorn, and development dependencies
- [ ] Create `app/main.py`
- [ ] Add the `/health` endpoint
- [ ] Verify `/docs`, `/redoc`, and `/openapi.json`

### Phase 2: Configuration and Database

- [ ] Load settings from environment variables
- [ ] Configure SQLite and SQLAlchemy
- [ ] Create database session dependencies
- [ ] Define `User` and `Task` models
- [ ] Initialize Alembic
- [ ] Generate and apply the first migration

### Phase 3: Schemas and CRUD

- [ ] Define request and response schemas
- [ ] Implement task creation
- [ ] Implement task listing and retrieval
- [ ] Implement partial updates
- [ ] Implement deletion
- [ ] Add pagination and filtering
- [ ] Return appropriate HTTP status codes

### Phase 4: Authentication

- [ ] Implement user registration
- [ ] Hash passwords using a maintained password-hashing library
- [ ] Implement login
- [ ] Generate and validate JWTs
- [ ] Add a current-user dependency
- [ ] Enforce task ownership

### Phase 5: Error Handling and Observability

- [ ] Add consistent error responses
- [ ] Handle missing and unauthorized resources
- [ ] Add structured request logging
- [ ] Add request or correlation IDs
- [ ] Avoid exposing secrets and internal exceptions

### Phase 6: Testing

- [ ] Configure an isolated test database
- [ ] Test health checks
- [ ] Test registration and login
- [ ] Test authenticated CRUD operations
- [ ] Test validation failures
- [ ] Test unauthorized access
- [ ] Test ownership boundaries
- [ ] Add coverage reporting

### Phase 7: Packaging and Documentation

- [ ] Add a production-oriented `Dockerfile`
- [ ] Add `docker-compose.yml` for local use
- [ ] Document setup and run commands
- [ ] Include example API requests
- [ ] Document environment variables
- [ ] Add linting and formatting commands

## 7. API Conventions

- Use an `/api/v1` prefix for versioned endpoints
- Use plural resource names such as `/tasks`
- Use Pydantic response models
- Return `201 Created` after successful creation
- Return `204 No Content` after successful deletion
- Return `404 Not Found` for inaccessible or missing tasks
- Use ISO 8601 timestamps in UTC
- Never return password hashes

## 8. Example Acceptance Criteria

- [ ] The app starts with one documented command
- [ ] `GET /health` returns `200 OK`
- [ ] A user can register and log in
- [ ] An authenticated user can create, read, update, and delete tasks
- [ ] Users cannot access each other’s tasks
- [ ] Invalid requests produce useful validation errors
- [ ] Database schema changes are managed through migrations
- [ ] The test suite passes in a clean environment
- [ ] Swagger UI supports authenticated endpoint testing
- [ ] The app runs locally and in Docker

## 9. Optional Enhancements

- [ ] PostgreSQL support
- [ ] Async SQLAlchemy sessions
- [ ] Refresh tokens
- [ ] Role-based authorization
- [ ] Rate limiting
- [ ] CORS configuration
- [ ] Metrics and tracing
- [ ] CI workflow for linting and tests
- [ ] Deployment to a cloud platform
- [ ] A small frontend consuming the API

## 10. Demo Flow

1. Start the application.
2. Open `/docs`.
3. Call the health endpoint.
4. Register a user.
5. Log in and authorize Swagger UI with the token.
6. Create several tasks.
7. List and filter tasks.
8. Update a task as completed.
9. Demonstrate validation and authorization errors.
10. Delete a task and run the automated tests.