# ishant-kb/todo-app architecture

> Architecture diagram of the GitHub repository ishant-kb/todo-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ishant-kb/todo-app
- Repository: https://github.com/ishant-kb/todo-app

## Overview

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: [`backend/main.py`](https://github.com/ishant-kb/todo-app/blob/main/backend/main.py) (Todo routes), [`frontend/app/page.tsx`](https://github.com/ishant-kb/todo-app/blob/main/frontend/app/page.tsx) (Todo page), [`backend/models.py`](https://github.com/ishant-kb/todo-app/blob/main/backend/models.py) (Todo model), [`backend/database.py`](https://github.com/ishant-kb/todo-app/blob/main/backend/database.py) (DB setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_layout["App shell<br/>Next.js layout<br/>[layout.tsx]"]
  node_page["Todo page<br/>Next.js page<br/>[page.tsx]"]
  node_styles["Global CSS<br/>styling<br/>[globals.css]"]
end

subgraph group_backend["Backend"]
  node_api_backend["FastAPI API<br/>FastAPI app<br/>[main.py]"]
  node_config["Settings<br/>config<br/>[config.py]"]
  node_database[("DB setup<br/>SQLAlchemy setup<br/>[database.py]")]
  node_models["Todo model<br/>ORM model<br/>[models.py]"]
  node_schemas["API schemas<br/>Pydantic models<br/>[schemas.py]"]
  node_docs["API docs<br/>[main.py]"]
  node_cors["CORS<br/>browser policy<br/>[main.py]"]
  node_todos_api["Todo routes<br/>REST endpoints<br/>[main.py]"]
end

subgraph group_data["Data"]
  node_todo_db[("Todos table<br/>relational table")]
end

node_browser(("Browser<br/>client"))
node_http(("HTTP API<br/>network boundary"))

node_browser -->|"use UI"| node_page
node_page -->|"renders in"| node_layout
node_page -->|"styled by"| node_styles
node_page -->|"calls API"| node_http
node_http -->|"allowed by"| node_cors
node_cors -->|"guards"| node_todos_api
node_api_backend -->|"registers"| node_todos_api
node_api_backend -->|"serves"| node_docs
node_api_backend -->|"uses"| node_database
node_api_backend -->|"reads"| node_config
node_todos_api -->|"validates"| node_schemas
node_todos_api -->|"maps to"| node_models
node_database -->|"initializes"| node_models
node_models -->|"persists in"| node_todo_db
node_schemas -->|"contracts"| node_todos_api

click node_layout "https://github.com/ishant-kb/todo-app/blob/main/frontend/app/layout.tsx"
click node_page "https://github.com/ishant-kb/todo-app/blob/main/frontend/app/page.tsx"
click node_styles "https://github.com/ishant-kb/todo-app/blob/main/frontend/app/globals.css"
click node_api_backend "https://github.com/ishant-kb/todo-app/blob/main/backend/main.py"
click node_config "https://github.com/ishant-kb/todo-app/blob/main/backend/config.py"
click node_database "https://github.com/ishant-kb/todo-app/blob/main/backend/database.py"
click node_models "https://github.com/ishant-kb/todo-app/blob/main/backend/models.py"
click node_schemas "https://github.com/ishant-kb/todo-app/blob/main/backend/schemas.py"
click node_docs "https://github.com/ishant-kb/todo-app/blob/main/backend/main.py"
click node_cors "https://github.com/ishant-kb/todo-app/blob/main/backend/main.py"
click node_todos_api "https://github.com/ishant-kb/todo-app/blob/main/backend/main.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_layout,node_page,node_styles toneBlue
class node_api_backend,node_config,node_database,node_models,node_schemas,node_docs,node_cors,node_todos_api toneAmber
class node_todo_db toneMint
class node_browser,node_http toneNeutral
```

## Components

### Frontend

Next.js client app

- [App shell](https://github.com/ishant-kb/todo-app/blob/main/frontend/app/layout.tsx): Next.js layout · Top-level app layout and shared document structure · `frontend/app/layout.tsx`
- [Todo page](https://github.com/ishant-kb/todo-app/blob/main/frontend/app/page.tsx): Next.js page · Main UI for viewing and editing todos · `frontend/app/page.tsx`
- [Global CSS](https://github.com/ishant-kb/todo-app/blob/main/frontend/app/globals.css): styling · Application-wide styling for the frontend · `frontend/app/globals.css`

### Backend

FastAPI service

- [FastAPI API](https://github.com/ishant-kb/todo-app/blob/main/backend/main.py): FastAPI app · Backend entrypoint and route composition · `backend/main.py`
- [Settings](https://github.com/ishant-kb/todo-app/blob/main/backend/config.py): config · Environment-driven backend configuration · `backend/config.py`
- [DB setup](https://github.com/ishant-kb/todo-app/blob/main/backend/database.py): SQLAlchemy setup · Engine, session, and startup table initialization · `backend/database.py`
- [Todo model](https://github.com/ishant-kb/todo-app/blob/main/backend/models.py): ORM model · SQLAlchemy model for stored todos · `backend/models.py`
- [API schemas](https://github.com/ishant-kb/todo-app/blob/main/backend/schemas.py): Pydantic models · Request and response contracts for the REST API · `backend/schemas.py`
- [API docs](https://github.com/ishant-kb/todo-app/blob/main/backend/main.py): OpenAPI docs · Auto-generated interactive API documentation · `backend/main.py`
- [CORS](https://github.com/ishant-kb/todo-app/blob/main/backend/main.py): browser policy · Allows the Next.js dev origin to call the API · `backend/main.py`
- [Todo routes](https://github.com/ishant-kb/todo-app/blob/main/backend/main.py): REST endpoints · CRUD endpoints for listing, creating, updating, and deleting todos · `backend/main.py`

### Data

Database boundary

- **Todos table**: relational table · Persistent storage for todo records

### Other components

- **Browser**: client · User interacts with the app UI in the browser
- **HTTP API**: network boundary · Browser-to-backend requests over localhost origins

## Connections

- 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
