How ishant-kb/codewithishant-v2 works
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: main.py API entry · (public) Public app · auth.py Auth API · db DB layer
Components 23
Backend
FastAPI API with auth, content services, ORM persistence, and startup wiring.
- API entry · Wires CORS, routes, and startup table creation.
backend/app/main.py - API deps · Shared request dependencies for bearer-token protection.
backend/app/api/deps.py - Auth API · Admin login and token issuance endpoints.
backend/app/api/v1/auth.py - Topic API · Topic CRUD and topic detail endpoints.
backend/app/api/v1/topic.py - Note API · Note CRUD endpoints.
backend/app/api/v1/note.py - Topic service · Validates topic hierarchy, slugs, and topic workflows.
backend/app/services/topic.py - Note service · Encapsulates note creation, update, and lookup rules.
backend/app/services/note.py - ORM models · Admin, topic, and note persistence models.
backend/app/models - Schemas · Request and response shapes for admin, topic, note, and topic detail payloads.
backend/app/schemas - Core utils · JWT, bcrypt, and shared backend utility functions.
backend/app/core - DB layer · SQLAlchemy session and declarative base used by the API and services.
backend/app/db - PostgreSQL · Primary database for content and admin users.
Frontend
Next.js app split into public content, admin workflows, and visualizer experiences.
- Public app · Public-facing site for topic and note discovery.
frontend/app/(public) - Admin app · Authenticated content management area.
frontend/app/(admin) - Visualizer · Standalone algorithm visualization section implemented client-side.
frontend/app/visualizer - API client · Browser-side client for backend auth, topic, and note requests.
frontend/lib/api - Auth store · Stores and reuses admin auth state and JWT token.
frontend/store/auth.ts - Content UI · Topic and note presentation components for public pages.
frontend/components/features - Shared UI · Reusable shells, primitives, and landing-page sections.
frontend/components - Markdown 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 · One-off script for creating the initial admin account.
scripts/create_admin.py - Check notes · Local integrity check for note content and API assumptions.
scripts/check_notes.py - API test · Local script for exercising backend endpoints.
scripts/test_api.py
Connections 29
- 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.