How ishant-kb/codewithishant-version2 works
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: app Next app · main.py FastAPI app · services Services · (public) Public site
Components 19
Frontend
Next.js app with public, admin, and visualizer surfaces.
- Next app · App Router shell for the UI surfaces.
frontend/app - Public site · Public topics, notes, blogs, and cheatsheets browsing.
frontend/app/(public) - Admin area · JWT-protected content management UI.
frontend/app/(admin) - Visualizer · Algorithm visualizer pages and components, largely independent of the backend.
frontend/app/visualizer - API client · Centralized browser-to-backend calls for auth and content domains.
frontend/lib/api - UI components · Reusable cards, shells, markdown rendering, and page sections.
frontend/components - State stores · Small auth and UI state stores for the frontend.
frontend/store - Middleware · Frontend route protection and request gating.
frontend/middleware.ts
Backend
FastAPI API, auth, content services, and persistence layers.
- FastAPI app · Application startup and router registration entrypoint.
backend/app/main.py - Auth API · Login and JWT/token management endpoints.
backend/app/api/v1/auth.py - Content APIs · Topic, note, blog, and cheatsheet endpoints.
backend/app/api/v1 - Services · CRUD, validation, and domain rules for content and auth flows.
backend/app/services - Models · SQLAlchemy persistence models for admin, content, and token blacklist.
backend/app/models - Schemas · Pydantic request/response contracts for API boundaries.
backend/app/schemas - Security core · JWT, CSRF, sanitization, and token blacklist support.
backend/app/core - DB layer · SQLAlchemy session and declarative base wiring.
backend/app/db
Data & Ops
Database, migrations, and bootstrap entrypoints.
- PostgreSQL · Single persistent store for content and authentication state.
- Migrations · Alembic migration support for database changes.
backend/alembic - Admin seed · One-off script to create the initial admin account.
scripts/create_admin.py
Connections 21
- 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.