# ishant-kb/codewithishant-v2 architecture

> Architecture diagram of the GitHub repository ishant-kb/codewithishant-v2, 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/codewithishant-v2
- Repository: https://github.com/ishant-kb/codewithishant-v2

## Overview

1. **Repository shape**
   - This is a monorepo with two runtime applications: a **FastAPI backend** and a **Next.js frontend**. The backend owns persistence and business rules; the frontend owns public content delivery, admin UI, and algorithm visualizations.
   - PostgreSQL is the single system of record for content and admin users.

2. **Backend boundary**
   - `backend/app/main.py` is the API entrypoint. It wires CORS, mounts versioned routers, and creates database tables at startup via SQLAlchemy metadata.
   - The backend is split into **API routes**, **services**, **models**, **schemas**, and **core utilities**, which cleanly separates HTTP concerns from domain logic and persistence.

3. **Backend domain model**
   - The core domain is small: **admins**, **topics**, and **notes**.
   - Topics appear to support hierarchical nesting through parent-topic validation, and topic slugs are auto-generated.
   - Notes are associated with topics and are exposed both independently and as topic-scoped content.

4. **Backend request flow**
   - HTTP requests hit route modules under `backend/app/api/v1/`:
     - `auth.py` for admin login
     - `topic.py` for topic CRUD and topic detail endpoints
     - `note.py` for note CRUD
   - Routes delegate to `services/`, which encapsulate business rules before calling SQLAlchemy models/session code.

5. **Backend auth and security**
   - Admin authentication uses **JWT bearer tokens**.
   - Password handling uses **bcrypt** and token creation/validation uses **python-jose**.
   - Protected admin routes require `Authorization: Bearer <token>`, and dependency helpers in `backend/app/api/deps.py` likely enforce that boundary.

6. **Backend data access**
   - `backend/app/db/session.py` and `backend/app/db/base.py` define the database session and model base.
   - `backend/app/models/` holds SQLAlchemy tables; `backend/app/schemas/` holds Pydantic request/response contracts.
   - This means the API is type-checked at the edge, while persistence stays ORM-based behind the service layer.

7. **Frontend application split**
   - The frontend is a **Next.js App Router** app with two major shells:
     - `app/(public)` for the public site
     - `app/(admin)` for the authenticated admin area
   - There is also a separate `app/visualizer` section for interactive algorithm demos that do not appear to depend on the backend.

8. **Public content flow**
   - Public pages render topic and note content from the backend through `frontend/lib/api/`.
   - The main public experience is:
     - home page
     - topics listing
     - topic detail pages by slug
     - note detail pages by ID
   - Components under `components/features/topics` and `components/features/notes` render backend-driven content, while `components/common/MarkdownRenderer.tsx` indicates note body content is likely stored as Markdown.

9. **Admin UI flow**
   - The admin area has dedicated pages for login, topics, notes, blogs, and cheatsheets, but only topics/notes are described as implemented backend-backed features.
   - `frontend/store/auth.ts` and the API client modules suggest the token is stored client-side and reused for authenticated API calls.
   - This admin boundary is separate from the public shell and is responsible for content management workflows rather than content consumption.

10. **Frontend state and composition**
   - Shared UI is composed from reusable layers:
     - `components/layout` for shell elements like navbar/sidebar/footer
     - `components/ui` for small primitives
     - `components/sections` for landing-page presentation blocks
   - `hooks/` and `store/` handle client-side interaction state, while `lib/utils.ts` and `constants/` centralize shared frontend logic.

11. **Algorithm visualizer subsystem**
   - `app/visualizer/` contains standalone algorithm visualizations for sorting and searching, including bubble sort, insertion sort, merge sort, topological sort, and binary search.
   - These pages are implemented as interactive client-side components and look architecturally separate from the content platform backend.

12. **Operational scripts and bootstrap**
   - `backend/scripts/create_admin.py` is a one-off bootstrap path to create the first admin account.
   - `scripts/check_notes.py` and `scripts/test_api.py` indicate local validation/testing helpers around API behavior and content integrity.

13. **Key integration points for a diagram**
   - The main external flow is: **browser → Next.js frontend → FastAPI API → PostgreSQL**.
   - Admin login adds a JWT issue/verify step between frontend and protected backend routes.
   - The visualizer subsystem is mostly self-contained on the frontend side and does not sit on the critical backend data path.

14. **Architectural caveats**
   - Tables are auto-created on startup rather than migrated, so schema lifecycle is tightly coupled to app startup.
   - CORS is currently permissive, and some frontend pages hardcode backend URLs instead of using only shared env config.
   - Those details matter because they affect deployment boundaries and how safely the two apps can be separated in production.

Main entry points: [`backend/app/main.py`](https://github.com/ishant-kb/codewithishant-v2/blob/main/backend/app/main.py) (API entry), [`frontend/app/(public)`](https://github.com/ishant-kb/codewithishant-v2/tree/main/frontend/app/(public)) (Public app), [`backend/app/api/v1/auth.py`](https://github.com/ishant-kb/codewithishant-v2/blob/main/backend/app/api/v1/auth.py) (Auth API), [`backend/app/db`](https://github.com/ishant-kb/codewithishant-v2/tree/main/backend/app/db) (DB layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_main["API entry<br/>FastAPI app<br/>[main.py]"]
  node_backend_api_deps["API deps<br/>auth deps<br/>[deps.py]"]
  node_backend_auth_route["Auth API<br/>route module<br/>[auth.py]"]
  node_backend_topic_route["Topic API<br/>route module<br/>[topic.py]"]
  node_backend_note_route["Note API<br/>route module<br/>[note.py]"]
  node_backend_topic_service["Topic service<br/>domain logic<br/>[topic.py]"]
  node_backend_note_service["Note service<br/>domain logic<br/>[note.py]"]
  node_backend_models[("ORM models<br/>SQLAlchemy tables")]
  node_backend_schemas["Schemas<br/>Pydantic contracts"]
  node_backend_core["Core utils<br/>security helpers"]
  node_backend_db[("DB layer<br/>session/base")]
  node_postgres[("PostgreSQL<br/>system of record")]
end

subgraph group_frontend["Frontend"]
  node_frontend_public["Public app<br/>Next.js shell"]
  node_frontend_admin["Admin app<br/>Next.js shell"]
  node_frontend_visualizer["Visualizer<br/>interactive demos"]
  node_frontend_api["API client<br/>frontend data access"]
  node_frontend_auth_store["Auth store<br/>client state<br/>[auth.ts]"]
  node_frontend_content["Content UI<br/>components"]
  node_frontend_shared_ui["Shared UI<br/>layout/ui"]
  node_frontend_markdown["Markdown renderer<br/>content renderer"]
end

subgraph group_ops["Ops"]
  node_scripts_create_admin["Create admin<br/>bootstrap script<br/>[create_admin.py]"]
  node_scripts_check_notes["Check notes<br/>validation script<br/>[check_notes.py]"]
  node_scripts_test_api["API test<br/>validation script<br/>[test_api.py]"]
end

node_backend_main -->|"mounts"| node_backend_auth_route
node_backend_main -->|"mounts"| node_backend_topic_route
node_backend_main -->|"mounts"| node_backend_note_route
node_backend_main -->|"initializes"| node_backend_db
node_backend_auth_route -->|"uses"| node_backend_core
node_backend_auth_route -->|"protects"| node_backend_api_deps
node_backend_topic_route -->|"delegates"| node_backend_topic_service
node_backend_note_route -->|"delegates"| node_backend_note_service
node_backend_topic_service -->|"persists via"| node_backend_models
node_backend_note_service -->|"persists via"| node_backend_models
node_backend_topic_service -->|"returns"| node_backend_schemas
node_backend_note_service -->|"returns"| node_backend_schemas
node_backend_models -->|"built on"| node_backend_db
node_backend_db -->|"stores"| node_postgres
node_backend_api_deps -->|"verifies"| node_backend_core
node_frontend_public -->|"fetches"| node_frontend_api
node_frontend_admin -->|"mutates"| node_frontend_api
node_frontend_admin -->|"reads"| node_frontend_auth_store
node_frontend_public -->|"renders"| node_frontend_content
node_frontend_public -->|"renders"| node_frontend_markdown
node_frontend_public -->|"composes"| node_frontend_shared_ui
node_frontend_admin -->|"composes"| node_frontend_shared_ui
node_frontend_visualizer -->|"composes"| node_frontend_shared_ui
node_frontend_visualizer -.->|"does not depend on"| node_frontend_api
node_frontend_api -->|"calls"| node_backend_main
node_frontend_auth_store -->|"stores token from"| node_backend_auth_route
node_scripts_create_admin -->|"bootstraps"| node_backend_db
node_scripts_test_api -->|"exercises"| node_backend_main
node_scripts_check_notes -->|"checks content for"| node_frontend_public

click node_backend_main "https://github.com/ishant-kb/codewithishant-v2/blob/main/backend/app/main.py"
click node_backend_api_deps "https://github.com/ishant-kb/codewithishant-v2/blob/main/backend/app/api/deps.py"
click node_backend_auth_route "https://github.com/ishant-kb/codewithishant-v2/blob/main/backend/app/api/v1/auth.py"
click node_backend_topic_route "https://github.com/ishant-kb/codewithishant-v2/blob/main/backend/app/api/v1/topic.py"
click node_backend_note_route "https://github.com/ishant-kb/codewithishant-v2/blob/main/backend/app/api/v1/note.py"
click node_backend_topic_service "https://github.com/ishant-kb/codewithishant-v2/blob/main/backend/app/services/topic.py"
click node_backend_note_service "https://github.com/ishant-kb/codewithishant-v2/blob/main/backend/app/services/note.py"
click node_backend_models "https://github.com/ishant-kb/codewithishant-v2/tree/main/backend/app/models"
click node_backend_schemas "https://github.com/ishant-kb/codewithishant-v2/tree/main/backend/app/schemas"
click node_backend_core "https://github.com/ishant-kb/codewithishant-v2/tree/main/backend/app/core"
click node_backend_db "https://github.com/ishant-kb/codewithishant-v2/tree/main/backend/app/db"
click node_frontend_public "https://github.com/ishant-kb/codewithishant-v2/tree/main/frontend/app/(public)"
click node_frontend_admin "https://github.com/ishant-kb/codewithishant-v2/tree/main/frontend/app/(admin)"
click node_frontend_visualizer "https://github.com/ishant-kb/codewithishant-v2/tree/main/frontend/app/visualizer"
click node_frontend_api "https://github.com/ishant-kb/codewithishant-v2/tree/main/frontend/lib/api"
click node_frontend_auth_store "https://github.com/ishant-kb/codewithishant-v2/blob/main/frontend/store/auth.ts"
click node_frontend_content "https://github.com/ishant-kb/codewithishant-v2/tree/main/frontend/components/features"
click node_frontend_shared_ui "https://github.com/ishant-kb/codewithishant-v2/tree/main/frontend/components"
click node_frontend_markdown "https://github.com/ishant-kb/codewithishant-v2/blob/main/frontend/components/common/MarkdownRenderer.tsx"
click node_scripts_create_admin "https://github.com/ishant-kb/codewithishant-v2/blob/main/scripts/create_admin.py"
click node_scripts_check_notes "https://github.com/ishant-kb/codewithishant-v2/blob/main/scripts/check_notes.py"
click node_scripts_test_api "https://github.com/ishant-kb/codewithishant-v2/blob/main/scripts/test_api.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_backend_main,node_backend_api_deps,node_backend_auth_route,node_backend_topic_route,node_backend_note_route,node_backend_topic_service,node_backend_note_service,node_backend_models,node_backend_schemas,node_backend_core,node_backend_db,node_postgres toneBlue
class node_frontend_public,node_frontend_admin,node_frontend_visualizer,node_frontend_api,node_frontend_auth_store,node_frontend_content,node_frontend_shared_ui,node_frontend_markdown toneAmber
class node_scripts_create_admin,node_scripts_check_notes,node_scripts_test_api toneMint
```

## Components

### Backend

FastAPI API with auth, content services, ORM persistence, and startup wiring.

- [API entry](https://github.com/ishant-kb/codewithishant-v2/blob/main/backend/app/main.py): FastAPI app · Wires CORS, routes, and startup table creation. · `backend/app/main.py`
- [API deps](https://github.com/ishant-kb/codewithishant-v2/blob/main/backend/app/api/deps.py): auth deps · Shared request dependencies for bearer-token protection. · `backend/app/api/deps.py`
- [Auth API](https://github.com/ishant-kb/codewithishant-v2/blob/main/backend/app/api/v1/auth.py): route module · Admin login and token issuance endpoints. · `backend/app/api/v1/auth.py`
- [Topic API](https://github.com/ishant-kb/codewithishant-v2/blob/main/backend/app/api/v1/topic.py): route module · Topic CRUD and topic detail endpoints. · `backend/app/api/v1/topic.py`
- [Note API](https://github.com/ishant-kb/codewithishant-v2/blob/main/backend/app/api/v1/note.py): route module · Note CRUD endpoints. · `backend/app/api/v1/note.py`
- [Topic service](https://github.com/ishant-kb/codewithishant-v2/blob/main/backend/app/services/topic.py): domain logic · Validates topic hierarchy, slugs, and topic workflows. · `backend/app/services/topic.py`
- [Note service](https://github.com/ishant-kb/codewithishant-v2/blob/main/backend/app/services/note.py): domain logic · Encapsulates note creation, update, and lookup rules. · `backend/app/services/note.py`
- [ORM models](https://github.com/ishant-kb/codewithishant-v2/tree/main/backend/app/models): SQLAlchemy tables · Admin, topic, and note persistence models. · `backend/app/models`
- [Schemas](https://github.com/ishant-kb/codewithishant-v2/tree/main/backend/app/schemas): Pydantic contracts · Request and response shapes for admin, topic, note, and topic detail payloads. · `backend/app/schemas`
- [Core utils](https://github.com/ishant-kb/codewithishant-v2/tree/main/backend/app/core): security helpers · JWT, bcrypt, and shared backend utility functions. · `backend/app/core`
- [DB layer](https://github.com/ishant-kb/codewithishant-v2/tree/main/backend/app/db): session/base · SQLAlchemy session and declarative base used by the API and services. · `backend/app/db`
- **PostgreSQL**: system of record · Primary database for content and admin users.

### Frontend

Next.js app split into public content, admin workflows, and visualizer experiences.

- [Public app](https://github.com/ishant-kb/codewithishant-v2/tree/main/frontend/app/(public)): Next.js shell · Public-facing site for topic and note discovery. · `frontend/app/(public)`
- [Admin app](https://github.com/ishant-kb/codewithishant-v2/tree/main/frontend/app/(admin)): Next.js shell · Authenticated content management area. · `frontend/app/(admin)`
- [Visualizer](https://github.com/ishant-kb/codewithishant-v2/tree/main/frontend/app/visualizer): interactive demos · Standalone algorithm visualization section implemented client-side. · `frontend/app/visualizer`
- [API client](https://github.com/ishant-kb/codewithishant-v2/tree/main/frontend/lib/api): frontend data access · Browser-side client for backend auth, topic, and note requests. · `frontend/lib/api`
- [Auth store](https://github.com/ishant-kb/codewithishant-v2/blob/main/frontend/store/auth.ts): client state · Stores and reuses admin auth state and JWT token. · `frontend/store/auth.ts`
- [Content UI](https://github.com/ishant-kb/codewithishant-v2/tree/main/frontend/components/features): components · Topic and note presentation components for public pages. · `frontend/components/features`
- [Shared UI](https://github.com/ishant-kb/codewithishant-v2/tree/main/frontend/components): layout/ui · Reusable shells, primitives, and landing-page sections. · `frontend/components`
- [Markdown renderer](https://github.com/ishant-kb/codewithishant-v2/blob/main/frontend/components/common/MarkdownRenderer.tsx): content renderer · Renders note body content as Markdown. · `frontend/components/common/MarkdownRenderer.tsx`

### Ops

Bootstrap and validation scripts for local administration and API checks.

- [Create admin](https://github.com/ishant-kb/codewithishant-v2/blob/main/scripts/create_admin.py): bootstrap script · One-off script for creating the initial admin account. · `scripts/create_admin.py`
- [Check notes](https://github.com/ishant-kb/codewithishant-v2/blob/main/scripts/check_notes.py): validation script · Local integrity check for note content and API assumptions. · `scripts/check_notes.py`
- [API test](https://github.com/ishant-kb/codewithishant-v2/blob/main/scripts/test_api.py): validation script · Local script for exercising backend endpoints. · `scripts/test_api.py`

## Connections

- API entry → Auth API: mounts · Registers versioned auth routes.
- API entry → Topic API: mounts · Registers versioned topic routes.
- API entry → Note API: mounts · Registers versioned note routes.
- API entry → DB layer: initializes · Creates tables from metadata at startup.
- Auth API → Core utils: uses · Hashes passwords and signs or verifies JWTs.
- Auth API → API deps: protects · Uses auth dependencies for bearer-token protection.
- Topic API → Topic service: delegates · Passes topic requests into domain logic.
- Note API → Note service: delegates · Passes note requests into domain logic.
- Topic service → ORM models: persists via · Reads and writes topic records.
- Note service → ORM models: persists via · Reads and writes note records.
- Topic service → Schemas: returns · Uses typed contracts for topic payloads.
- Note service → Schemas: returns · Uses typed contracts for note payloads.
- ORM models → DB layer: built on · ORM tables depend on the declarative base and session setup.
- DB layer → PostgreSQL: stores · Persists all content and admin data.
- API deps → Core utils: verifies · Resolves and validates bearer tokens.
- Public app → API client: fetches · Loads topics and notes from the backend API.
- Admin app → API client: mutates · Uses authenticated API calls for content management.
- Admin app → Auth store: reads · Reuses client-side admin auth state.
- Public app → Content UI: renders · Composes topic and note views.
- Public app → Markdown renderer: renders · Displays note bodies as Markdown.
- Public app → Shared UI: composes · Uses layout and reusable UI layers.
- Admin app → Shared UI: composes · Uses shared UI layers for admin screens.
- Visualizer → Shared UI: composes · Uses shared cards and layout elements.
- Visualizer → API client: does not depend on · Operates as a mostly self-contained client-side subsystem.
- API client → API entry: calls · Browser requests go to the FastAPI backend.
- Auth store → Auth API: stores token from · Persists JWTs received from login.
- Create admin → DB layer: bootstraps · Creates the first admin account through backend persistence.
- API test → API entry: exercises · Validates API behavior end to end.
- Check notes → Public app: checks content for · Validates note-related content assumptions.
