How ishant-kb/todo-app works
1. Repo shape
- This is a two-tier full-stack Todo app with a Next.js frontend and a FastAPI backend.
- The two parts are deployed/run independently during development and communicate over HTTP.
2. Frontend boundary
- The frontend/ folder is a small Next.js 16 app using the App Router (app/layout.tsx, app/page.tsx) and global styling (app/globals.css).
- The UI is likely centered in a single page that performs todo CRUD actions against the backend API.
- There is no separate frontend service layer visible in the tree; API calls are probably made directly from the page/UI code.
3. Backend boundary
- The backend/ folder is a standalone FastAPI service.
- backend/main.py is the application entrypoint and API composition point.
- The backend exposes REST endpoints for todo CRUD and also serves FastAPI’s autogenerated docs.
4. Persistence layer
- backend/database.py likely owns SQLAlchemy engine/session setup and database initialization.
- backend/models.py defines the ORM model for todos.
- The database connection is configured through DATABASE_URL, so the app can target any SQLAlchemy-compatible database, with PostgreSQL suggested in the README.
5. API contract layer
- backend/schemas.py contains Pydantic request/response models.
- This separates external API payloads from internal ORM models, which is important for keeping the HTTP contract stable and validating input.
6. Configuration
- backend/config.py holds environment-driven configuration, especially the database URL.
- The README indicates a local .env file is used in development and ignored by git.
7. Primary data flow
- Browser user action -> Next.js UI -> HTTP request to http://localhost:8000 -> FastAPI route handler -> SQLAlchemy session/model -> database -> JSON response back to the UI.
- The todo list is therefore sourced from the backend database, not from local frontend state alone.
8. CRUD endpoints
- The backend exposes GET /todos, POST /todos, PATCH /todos/{todo_id}, and DELETE /todos/{todo_id}.
- The patch endpoint supports both title changes and completion toggling, so one resource represents the full todo state.
9. Cross-origin and local dev topology
- CORS is enabled only for http://localhost:3000, which matches the Next.js dev server.
- This means the frontend and backend are intentionally separated by origin and connected through browser-based cross-origin API calls.
10. Startup behavior
- SQLAlchemy creates the todos table automatically on backend startup if it does not exist.
- That makes the backend responsible for lightweight schema bootstrapping, so there is no separate migration tool visible in this repo.
11. Runtime/tooling split
- Frontend runtime: Node.js/Next.js/React/TypeScript/Tailwind CSS 4.
- Backend runtime: Python with FastAPI, SQLAlchemy, and Pydantic.
- These are distinct build and execution environments; there is no monorepo shared package layer apparent here.
12. What is not present
- No auth, background jobs, message queue, file storage, or caching layer is indicated.
- The architecture is intentionally simple: a single-page client, a REST API, and a relational database.
Main entry points: main.py Todo routes · page.tsx Todo page · models.py Todo model · database.py DB setup
Components 14
Frontend
Next.js client app
- App shell · Top-level app layout and shared document structure
frontend/app/layout.tsx - Todo page · Main UI for viewing and editing todos
frontend/app/page.tsx - Global CSS · Application-wide styling for the frontend
frontend/app/globals.css
Backend
FastAPI service
- FastAPI API · Backend entrypoint and route composition
backend/main.py - Settings · Environment-driven backend configuration
backend/config.py - DB setup · Engine, session, and startup table initialization
backend/database.py - Todo model · SQLAlchemy model for stored todos
backend/models.py - API schemas · Request and response contracts for the REST API
backend/schemas.py - API docs · Auto-generated interactive API documentation
backend/main.py - CORS · Allows the Next.js dev origin to call the API
backend/main.py - Todo routes · CRUD endpoints for listing, creating, updating, and deleting todos
backend/main.py
Data
Database boundary
- Todos table · Persistent storage for todo records
Other components
- Browser · User interacts with the app UI in the browser
- HTTP API · Browser-to-backend requests over localhost origins
Connections 15
- Browser → Todo page: use UI · User drives the todo interface in the browser
- Todo page → App shell: renders in · The page is mounted within the app shell
- Todo page → Global CSS: styled by · Global CSS provides shared presentation rules
- Todo page → HTTP API: calls API · Client-side requests go to the backend origin
- HTTP API → CORS: allowed by · CORS permits the frontend origin during development
- CORS → Todo routes: guards · Cross-origin browser requests reach the REST handlers
- FastAPI API → Todo routes: registers · Main application wires the todo routes
- FastAPI API → API docs: serves · FastAPI exposes autogenerated docs from the app entrypoint
- FastAPI API → DB setup: uses · Routes use the database session and startup initialization
- FastAPI API → Settings: reads · Configuration is loaded from environment variables
- Todo routes → API schemas: validates · Request and response payloads use Pydantic models
- Todo routes → Todo model: maps to · Handlers translate between API data and ORM objects
- DB setup → Todo model: initializes · Table creation is based on the ORM model metadata
- Todo model → Todos table: persists in · Todo records are stored in the relational table
- API schemas → Todo routes: contracts · Defines the external HTTP contract for CRUD operations