# ishant-kb/codewithishant-version2 architecture

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

- Interactive diagram: https://gitdiagram.com/ishant-kb/codewithishant-version2
- Repository: https://github.com/ishant-kb/codewithishant-version2

## Overview

1. **System shape**
   - This is a monorepo with two primary runtime apps: a **Next.js frontend** in `frontend/` and a **FastAPI backend** in `backend/`.
   - The backend owns all persistent content and authentication state; the frontend is mostly a presentation and interaction layer.
   - **PostgreSQL** is the only primary data store.

2. **Frontend boundary**
   - The frontend uses the **Next.js App Router** with clear route groups for **public** and **admin** experiences.
   - Public content lives under `app/(public)/...` and admin tooling under `app/(admin)/...`, each with its own layout.
   - There is also a separate **algorithm visualizer** area under `app/visualizer/...`, which appears self-contained and not dependent on the backend.

3. **Frontend data access**
   - Client-to-API communication is centralized in `frontend/lib/api/*`, with separate modules for topics, notes, blogs, cheatsheets, and auth.
   - The frontend uses typed domain models in `frontend/types/*` and shared UI/components for cards, layouts, markdown rendering, and page sections.
   - State related to auth/UI is kept in small stores under `frontend/store/*`, and route protection likely uses `frontend/middleware.ts`.

4. **Public content flow**
   - Public pages render topic, note, blog, and cheatsheet listings/details by calling the backend API.
   - The most important public flow is **topic listing → topic detail → associated notes**, which matches the repository’s documented product behavior.
   - Shared components such as topic cards, note cards, and markdown rendering are used to present backend content consistently.

5. **Admin flow**
   - The admin area is a separate frontend surface for managing content behind **JWT-based login**.
   - Admin routes include login plus management pages for topics, notes, blogs, and cheatsheets.
   - The frontend stores or attaches the bearer token for authorized requests, while the backend enforces access on admin-only endpoints.

6. **Backend API layering**
   - The backend is structured in standard layers: **API routes → services → models/schemas → database**.
   - Route handlers live in `backend/app/api/v1/*`, business logic in `backend/app/services/*`, persistence models in `backend/app/models/*`, and request/response contracts in `backend/app/schemas/*`.
   - This separation is important: route modules stay thin, while validation and CRUD logic are concentrated in services.

7. **Backend subsystems**
   - **Auth**: `auth.py`, `jwt.py`, `security.py`, and `token_blacklist.py` together implement admin login and token management.
   - **Content domains**: topics, notes, blogs, and cheatsheets each have their own route/service/model/schema sets.
   - **Content integrity**: topic slugs are auto-generated, and parent-topic validation prevents invalid nesting.

8. **Persistence model**
   - SQLAlchemy is used for ORM access, with `backend/app/db/session.py` and `backend/app/db/base.py` providing the database/session foundation.
   - The backend initializes tables on startup via `Base.metadata.create_all(...)`, so schema creation is currently app-driven rather than migration-driven.
   - Alembic is present under `backend/alembic/`, indicating migration support exists in the repo even if startup table creation is still used.

9. **Authentication and security boundary**
   - Authentication is **JWT bearer-token based** for admin actions.
   - The backend includes a token blacklist table, suggesting logout or invalidation support for already-issued JWTs.
   - Utility modules like `sanitize.py` and `csrf.py` indicate the codebase has explicit security handling beyond simple CRUD.

10. **Operational entry points**
   - The backend starts from `backend/app/main.py`, which is the FastAPI application root and router registration point.
   - A one-off admin bootstrap script exists in `backend/scripts/create_admin.py` to seed the first admin account.
   - The frontend is run as a standard Next.js app, with environment-based configuration for the backend URL.

11. **API surface and external contract**
   - The documented API exposes topic and note CRUD plus admin login, with additional blog and cheatsheet endpoints present in the backend tree.
   - The browser is the main external client; no message queue, worker, or third-party service is visible in the architecture.
   - CORS is currently permissive, so the backend is acting as a general API server rather than a tightly locked-down internal service.

12. **Notable asymmetry in the repo**
   - The backend already contains blog and cheatsheet domain code, but the README describes the public product primarily around topics and notes, and the frontend includes some placeholder admin/blog/cheatsheet routes.
   - For an architecture diagram, it is safest to show **topics + notes as the core path**, with **blogs and cheatsheets as adjacent/partially integrated content domains**.

Main entry points: [`frontend/app`](https://github.com/ishant-kb/codewithishant-version2/tree/main/frontend/app) (Next app), [`backend/app/main.py`](https://github.com/ishant-kb/codewithishant-version2/blob/main/backend/app/main.py) (FastAPI app), [`backend/app/services`](https://github.com/ishant-kb/codewithishant-version2/tree/main/backend/app/services) (Services), [`frontend/app/(public)`](https://github.com/ishant-kb/codewithishant-version2/tree/main/frontend/app/(public)) (Public site)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["Next app<br/>nextjs app"]
  node_frontend_public["Public site<br/>route group"]
  node_frontend_admin["Admin area<br/>route group"]
  node_frontend_visualizer["Visualizer<br/>self-contained UI"]
  node_frontend_api["API client<br/>client modules"]
  node_frontend_components["UI components<br/>shared UI"]
  node_frontend_store["State stores<br/>client state"]
  node_frontend_middleware["Middleware<br/>route guard<br/>[middleware.ts]"]
end

subgraph group_backend["Backend"]
  node_backend_main["FastAPI app<br/>api root<br/>[main.py]"]
  node_backend_auth_api["Auth API<br/>route layer<br/>[auth.py]"]
  node_backend_content_api["Content APIs<br/>route layer"]
  node_backend_services["Services<br/>business logic"]
  node_backend_models["Models"]
  node_backend_schemas["Schemas<br/>contracts"]
  node_backend_security["Security core<br/>crypto & safety"]
  node_backend_db["DB layer<br/>session & base"]
end

subgraph group_data["Data & Ops"]
  node_postgres[("PostgreSQL<br/>primary datastore")]
  node_alembic["Migrations"]
  node_admin_seed["Admin seed<br/>bootstrap script<br/>[create_admin.py]"]
end

node_frontend_app -->|"routes"| node_frontend_public
node_frontend_app -->|"routes"| node_frontend_admin
node_frontend_app -->|"routes"| node_frontend_visualizer
node_frontend_public -->|"fetches"| node_frontend_api
node_frontend_admin -->|"mutates"| node_frontend_api
node_frontend_public -->|"renders with"| node_frontend_components
node_frontend_admin -->|"renders with"| node_frontend_components
node_frontend_app -->|"uses"| node_frontend_store
node_frontend_app -->|"protected by"| node_frontend_middleware
node_backend_main -->|"registers"| node_backend_auth_api
node_backend_main -->|"registers"| node_backend_content_api
node_backend_auth_api -->|"delegates"| node_backend_services
node_backend_content_api -->|"delegates"| node_backend_services
node_backend_services -->|"persists via"| node_backend_models
node_backend_services -->|"validates via"| node_backend_schemas
node_backend_services -->|"secures via"| node_backend_security
node_backend_models -->|"mapped on"| node_backend_db
node_backend_db -->|"stores in"| node_postgres
node_backend_main -.->|"compatible with"| node_alembic
node_backend_main -.->|"bootstraps"| node_admin_seed
node_frontend_api -->|"calls"| node_backend_main

click node_frontend_app "https://github.com/ishant-kb/codewithishant-version2/tree/main/frontend/app"
click node_frontend_public "https://github.com/ishant-kb/codewithishant-version2/tree/main/frontend/app/(public)"
click node_frontend_admin "https://github.com/ishant-kb/codewithishant-version2/tree/main/frontend/app/(admin)"
click node_frontend_visualizer "https://github.com/ishant-kb/codewithishant-version2/tree/main/frontend/app/visualizer"
click node_frontend_api "https://github.com/ishant-kb/codewithishant-version2/tree/main/frontend/lib/api"
click node_frontend_components "https://github.com/ishant-kb/codewithishant-version2/tree/main/frontend/components"
click node_frontend_store "https://github.com/ishant-kb/codewithishant-version2/tree/main/frontend/store"
click node_frontend_middleware "https://github.com/ishant-kb/codewithishant-version2/blob/main/frontend/middleware.ts"
click node_backend_main "https://github.com/ishant-kb/codewithishant-version2/blob/main/backend/app/main.py"
click node_backend_auth_api "https://github.com/ishant-kb/codewithishant-version2/blob/main/backend/app/api/v1/auth.py"
click node_backend_content_api "https://github.com/ishant-kb/codewithishant-version2/tree/main/backend/app/api/v1"
click node_backend_services "https://github.com/ishant-kb/codewithishant-version2/tree/main/backend/app/services"
click node_backend_models "https://github.com/ishant-kb/codewithishant-version2/tree/main/backend/app/models"
click node_backend_schemas "https://github.com/ishant-kb/codewithishant-version2/tree/main/backend/app/schemas"
click node_backend_security "https://github.com/ishant-kb/codewithishant-version2/tree/main/backend/app/core"
click node_backend_db "https://github.com/ishant-kb/codewithishant-version2/tree/main/backend/app/db"
click node_alembic "https://github.com/ishant-kb/codewithishant-version2/tree/main/backend/alembic"
click node_admin_seed "https://github.com/ishant-kb/codewithishant-version2/blob/main/scripts/create_admin.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_frontend_app,node_frontend_public,node_frontend_admin,node_frontend_visualizer,node_frontend_api,node_frontend_components,node_frontend_store,node_frontend_middleware toneBlue
class node_backend_main,node_backend_auth_api,node_backend_content_api,node_backend_services,node_backend_models,node_backend_schemas,node_backend_security,node_backend_db toneAmber
class node_postgres,node_alembic,node_admin_seed toneMint
```

## Components

### Frontend

Next.js app with public, admin, and visualizer surfaces.

- [Next app](https://github.com/ishant-kb/codewithishant-version2/tree/main/frontend/app): nextjs app · App Router shell for the UI surfaces. · `frontend/app`
- [Public site](https://github.com/ishant-kb/codewithishant-version2/tree/main/frontend/app/(public)): route group · Public topics, notes, blogs, and cheatsheets browsing. · `frontend/app/(public)`
- [Admin area](https://github.com/ishant-kb/codewithishant-version2/tree/main/frontend/app/(admin)): route group · JWT-protected content management UI. · `frontend/app/(admin)`
- [Visualizer](https://github.com/ishant-kb/codewithishant-version2/tree/main/frontend/app/visualizer): self-contained UI · Algorithm visualizer pages and components, largely independent of the backend. · `frontend/app/visualizer`
- [API client](https://github.com/ishant-kb/codewithishant-version2/tree/main/frontend/lib/api): client modules · Centralized browser-to-backend calls for auth and content domains. · `frontend/lib/api`
- [UI components](https://github.com/ishant-kb/codewithishant-version2/tree/main/frontend/components): shared UI · Reusable cards, shells, markdown rendering, and page sections. · `frontend/components`
- [State stores](https://github.com/ishant-kb/codewithishant-version2/tree/main/frontend/store): client state · Small auth and UI state stores for the frontend. · `frontend/store`
- [Middleware](https://github.com/ishant-kb/codewithishant-version2/blob/main/frontend/middleware.ts): route guard · Frontend route protection and request gating. · `frontend/middleware.ts`

### Backend

FastAPI API, auth, content services, and persistence layers.

- [FastAPI app](https://github.com/ishant-kb/codewithishant-version2/blob/main/backend/app/main.py): api root · Application startup and router registration entrypoint. · `backend/app/main.py`
- [Auth API](https://github.com/ishant-kb/codewithishant-version2/blob/main/backend/app/api/v1/auth.py): route layer · Login and JWT/token management endpoints. · `backend/app/api/v1/auth.py`
- [Content APIs](https://github.com/ishant-kb/codewithishant-version2/tree/main/backend/app/api/v1): route layer · Topic, note, blog, and cheatsheet endpoints. · `backend/app/api/v1`
- [Services](https://github.com/ishant-kb/codewithishant-version2/tree/main/backend/app/services): business logic · CRUD, validation, and domain rules for content and auth flows. · `backend/app/services`
- [Models](https://github.com/ishant-kb/codewithishant-version2/tree/main/backend/app/models): orm models · SQLAlchemy persistence models for admin, content, and token blacklist. · `backend/app/models`
- [Schemas](https://github.com/ishant-kb/codewithishant-version2/tree/main/backend/app/schemas): contracts · Pydantic request/response contracts for API boundaries. · `backend/app/schemas`
- [Security core](https://github.com/ishant-kb/codewithishant-version2/tree/main/backend/app/core): crypto & safety · JWT, CSRF, sanitization, and token blacklist support. · `backend/app/core`
- [DB layer](https://github.com/ishant-kb/codewithishant-version2/tree/main/backend/app/db): session & base · SQLAlchemy session and declarative base wiring. · `backend/app/db`

### Data & Ops

Database, migrations, and bootstrap entrypoints.

- **PostgreSQL**: primary datastore · Single persistent store for content and authentication state.
- [Migrations](https://github.com/ishant-kb/codewithishant-version2/tree/main/backend/alembic): schema migrations · Alembic migration support for database changes. · `backend/alembic`
- [Admin seed](https://github.com/ishant-kb/codewithishant-version2/blob/main/scripts/create_admin.py): bootstrap script · One-off script to create the initial admin account. · `scripts/create_admin.py`

## Connections

- Next app → Public site: routes · Public App Router subtree.
- Next app → Admin area: routes · Admin App Router subtree.
- Next app → Visualizer: routes · Standalone visualizer subtree.
- Public site → API client: fetches · Loads content from the backend API.
- Admin area → API client: mutates · Uses authorized API calls for management actions.
- Public site → UI components: renders with · Shared cards, markdown, and layout pieces.
- Admin area → UI components: renders with · Shared admin and content UI pieces.
- Next app → State stores: uses · Auth and UI state shared across routes.
- Next app → Middleware: protected by · Route protection and redirects.
- FastAPI app → Auth API: registers · Mounts auth routes.
- FastAPI app → Content APIs: registers · Mounts content routes.
- Auth API → Services: delegates · Thin handlers call service logic.
- Content APIs → Services: delegates · Content route handlers call service logic.
- Services → Models: persists via · Domain operations read and write ORM models.
- Services → Schemas: validates via · Uses request and response contracts.
- Services → Security core: secures via · JWT and security helpers support auth flows.
- Models → DB layer: mapped on · ORM models sit on SQLAlchemy base/session plumbing.
- DB layer → PostgreSQL: stores in · All persistent state lives in PostgreSQL.
- FastAPI app → Migrations: compatible with · Repo includes migration support alongside app-driven schema creation.
- FastAPI app → Admin seed: bootstraps · Admin account seeding is handled by a separate script.
- API client → FastAPI app: calls · Browser client communicates with the FastAPI app.