Todo FastAPI API

A learning-focused backend project built to consolidate a modern Python API stack using FastAPI, PostgreSQL, SQLAlchemy 2.0, Alembic, and Docker.

The goal is not just to "make a CRUD work", but to build a small backend with a clean structure, incremental architecture, and predictable development workflow, while avoiding unnecessary complexity.

---

Project goals

This project reinforces backend fundamentals through a complete but intentionally small full-stack setup.

It covers:

• FastAPI backend design
• PostgreSQL integration via Docker
• SQLAlchemy 2.0 ORM modeling
• Alembic migrations workflow
• Service-layer architecture (without overengineering)
• Vue frontend consumption of a real API
• Reverse proxy routing with Nginx

---

Scope

Main entity: Task

Fields:

• id
• title
• description (optional)
• is_done
• created_at
• updated_at

---

API endpoints

Tasks:

• POST /tasks
• GET /tasks
• GET /tasks/{id}
• PATCH /tasks/{id}
• DELETE /tasks/{id}

---

Tech stack

• Python
• FastAPI
• Uvicorn
• PostgreSQL
• SQLAlchemy 2.0
• Alembic
• Pydantic
• Vue 3
• Vite
• Nginx
• Docker
• Docker Compose

---

Architecture philosophy

This project is intentionally designed to remain:

• simple
• explicit
• debuggable
• incremental
• close to real-world backend usage without enterprise complexity

---

What it is:

• a minimal full-stack CRUD system
• backend-first with frontend validation
• reverse-proxy integrated deployment setup

---

Project structure

todo-fastapi/

• backend/
• frontend/
• nginx/
• alembic/
• docs/
• docker-compose.yml
• Makefile
• .env
• README.md

---

Backend architecture layers

app/main.py

• FastAPI entry point
• router registration
• middleware (CORS)

app/core/

• config
• database setup

app/models/

• SQLAlchemy ORM models

app/schemas/

• Pydantic request/response schemas

app/services/

• CRUD logic
• filtering
• pagination
• business rules (minimal)

app/api/routes/

• HTTP layer
• dependency injection
• endpoint definitions

---

Frontend (Vue)

A minimal SPA that:

• lists tasks
• creates tasks
• updates tasks
• deletes tasks
• toggles completion
• supports filtering

No advanced architecture is used intentionally.

---

Nginx reverse proxy

Nginx is the single entry point:

Routing rules:

• / → Vue SPA
• /api/* → FastAPI backend

Important rule:

SPA fallback must NEVER intercept /api routes.

---

Environment variables

.env

POSTGRES_USER=admin POSTGRES_PASSWORD=secret-password POSTGRES_DB=todo_db

DATABASE_URL=postgresql://admin:secret-password@db:5432/todo_db

---

Running the project

Start everything:

make

---

Access:

• Frontend: http://localhost
• API: http://localhost/api/tasks

---

Makefile workflow

Core commands:

make up make down make

---

Migrations:

make migrations-create M="message" make migrations-up

---

DB utils:

make wait-db make test-db make seed

---

Debug:

make db-clean make query-tables make query-data

---

Maintenance:

make rm-pycache make clean make fclean

---

Development workflow

1. make up
2. develop backend/frontend
3. make migrations-create
4. make migrations-up
5. iterate via /api

---

Key architectural decisions

1. Incremental design (no overengineering)
2. Service layer only for CRUD isolation
3. Nginx as reverse proxy + static host
4. Frontend is intentionally minimal

---

Common pitfalls learned

Trailing slash inconsistency

/ and /tasks/ may behave differently depending on routing and proxy.

Nginx precedence rules

Location matching affects whether requests reach backend or SPA.

SPA fallback conflicts

Vue fallback must not capture API routes.

---

Final MVP status

Backend:

• CRUD complete
• PostgreSQL integrated
• migrations working
• service layer implemented

Frontend:

• Vue SPA working
• full API integration

Infrastructure:

• Docker Compose
• Nginx reverse proxy
• single entry point setup

---

Learning outcome

This project demonstrates:

• real backend structure without overengineering
• full API lifecycle
• containerized workflow
• frontend/backend integration
• reverse proxy behavior in production-like setup