# ishant-kb/codewithishant architecture

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

## Overview

1. **Project shape**
   - This is a **Next.js App Router** site written in **TypeScript**.
   - The architecture is predominantly **content-driven and file-system based**: most user-facing pages are generated from MDX content stored under `src/content`, with helper functions in `src/lib` turning that content into page data.

2. **Primary rendering boundary**
   - `src/app` defines the route tree and page composition.
   - `src/components` holds reusable UI and feature components used across routes.
   - `src/lib` contains the data-access and transformation layer that reads content, builds indexes, computes metadata, and supplies navigation structures.

3. **Content sources**
   - The repository separates authored content by domain:
     - `src/content/blog/*` for blog posts
     - `src/content/notes/*` for notes
     - `src/content/learn/*` for learning material, currently present but not clearly wired to a top-level route in the tree
   - Content is mostly `.mdx`, which means articles can mix prose with React components.

4. **Blog subsystem**
   - Blog routes live under `src/app/blog`, including category pages and nested post pages.
   - Supporting logic is in `src/lib/blog`:
     - fetching all posts
     - fetching a single post
     - filtering by category
     - computing adjacent posts, related posts, and series posts
   - This indicates the blog is not just a flat list; it supports **taxonomy, sequencing, and related-content navigation**.

5. **Notes subsystem**
   - Notes mirror the blog architecture under `src/app/notes`, with category and slug-based detail pages.
   - `src/lib/notes` provides the same kind of content lookup and relationship logic as blog, which suggests notes are another structured content corpus rather than a separate app.
   - The symmetry implies a shared presentation model but distinct content sets and routes.

6. **MDX/article rendering pipeline**
   - `src/components/features/article` contains the article-specific rendering stack:
     - `mdx-components.tsx`
     - `mdx-options.ts`
     - `CodeBlock.tsx`
     - `TableOfContents.tsx`
   - `src/lib/content` supports article enrichment:
     - heading extraction
     - table-of-contents generation
     - reading-time calculation
     - metadata handling
     - tag extraction
   - The flow is: **MDX content → parsing/enrichment in `lib/content` → rendered article UI with custom MDX components**.

7. **Search architecture**
   - Search is a dedicated subsystem, not just a UI widget.
   - `src/lib/search` contains:
     - text extraction from MDX
     - normalization
     - search logic
     - index generation/building
   - A generated `public/search-index.json` suggests search is **precomputed at build time** and consumed client-side.
   - UI entry points are `src/app/search`, `src/components/features/search/Search.tsx`, and `CommandPalette.tsx`, indicating both a full search page and an in-app quick-search experience.

8. **Navigation and site structure**
   - `src/components/features/navigation` provides shared chrome:
     - `Navbar`
     - `Sidebar`
     - `Breadcrumbs`
   - `src/lib/navigation/getSidebar.ts` likely derives sidebar structure from the content tree.
   - This means global navigation is **content-aware**, not hand-maintained in each page.

9. **Visualizers subsystem**
   - `src/app/visualizers` exposes a separate browsing area for visual tools or demos.
   - `src/lib/visual/visualizer.ts` suggests a registry or descriptor layer for visualizer pages.
   - `public/visualizers/bubbleSort/bubbleSort.html` shows at least one visualizer is a **static HTML asset**, implying this area mixes Next.js pages with standalone static demo files.

10. **Global layout and shared UI**
   - `src/app/layout.tsx` and `src/app/globals.css` define the site-wide shell and base styling.
   - Feature routes such as `about`, `contact`, `explore`, `search`, and the content sections likely compose within this shared shell.
   - Styling is a mix of **global CSS** and **CSS modules** for page-specific areas like about and contact.

11. **SEO and static metadata**
   - `src/app/sitemap.ts` indicates automatic sitemap generation.
   - `public/robots.txt` and `public/site.webmanifest` show the site is prepared for crawlability and installability.
   - This is consistent with a content site optimized for search discovery rather than a highly dynamic app.

12. **Build/runtime characteristics**
   - There is no obvious backend, database, or API layer in the tree.
   - The architecture appears to be **static or hybrid-rendered content served by Next.js**, with most data sourced from the repository at build time or request time from local files.
   - Deployment is likely optimized for Vercel, matching the Next.js defaults in the README.

13. **Reusable type and utility layer**
   - `src/types/content.ts` centralizes content-shaped types.
   - The utility libraries under `src/lib` appear to be the main contract between raw MDX content and route components.
   - This reduces coupling: route pages stay thin while content logic remains in shared helpers.

14. **Overall data flow**
   - Authored MDX and static assets live in `src/content` and `public`.
   - Helper modules in `src/lib` parse, index, and enrich that content.
   - Route files in `src/app` request those helpers and render pages.
   - Shared feature components in `src/components` handle article display, navigation, search, and UI affordances.

Main entry points: [`src/app/layout.tsx`](https://github.com/ishant-kb/codewithishant/blob/main/src/app/layout.tsx) (Site shell), [`src/lib/search`](https://github.com/ishant-kb/codewithishant/tree/main/src/lib/search) (Search index), [`src/lib/blog`](https://github.com/ishant-kb/codewithishant/tree/main/src/lib/blog) (Blog data), [`src/lib/notes`](https://github.com/ishant-kb/codewithishant/tree/main/src/lib/notes) (Notes data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routes["App routes"]
  node_app_root["Site shell<br/>next-layout<br/>[layout.tsx]"]
  node_home_page["Home<br/>route<br/>[page.tsx]"]
  node_blog_index["Blog index<br/>route<br/>[page.tsx]"]
  node_blog_category["Blog category<br/>route<br/>[page.tsx]"]
  node_blog_post["Blog post<br/>route<br/>[page.tsx]"]
  node_notes_index["Notes index<br/>route<br/>[page.tsx]"]
  node_notes_category["Notes category<br/>route<br/>[page.tsx]"]
  node_notes_note["Note detail<br/>route<br/>[page.tsx]"]
  node_search_page["Search<br/>route<br/>[page.tsx]"]
  node_visualizers_page["Visualizers<br/>route<br/>[page.tsx]"]
  node_visualizer_detail["Visualizer<br/>route<br/>[page.tsx]"]
end

subgraph group_content["Content sources"]
  node_blog_content["Blog MDX<br/>mdx-corpus"]
  node_notes_content["Notes MDX<br/>mdx-corpus"]
  node_learn_content["Learn MDX<br/>mdx-corpus"]
end

subgraph group_data["Lib layer"]
  node_blog_lib[("Blog data<br/>content-service")]
  node_notes_lib[("Notes data<br/>content-service")]
  node_content_lib[("Content enrich<br/>content-transform")]
  node_search_lib[("Search index<br/>search-pipeline")]
  node_nav_lib[("Sidebar data<br/>nav-builder<br/>[getSidebar.ts]")]
  node_visual_lib[("Visualizer registry<br/>[visualizer.ts]")]
end

subgraph group_ui["Components"]
  node_article_ui["Article UI<br/>mdx-rendering"]
  node_nav_ui["Navigation UI<br/>shell-ui"]
  node_search_ui["Search UI<br/>search-ui"]
  node_shared_ui["Shared UI<br/>ui-kit"]
end

subgraph group_assets["Public assets"]
  node_search_index["Search index<br/>generated-asset<br/>[search-index.json]"]
  node_visual_html["Bubble sort demo<br/>static-demo<br/>[bubbleSort.html]"]
end

node_blog_content -->|"read posts"| node_blog_lib
node_notes_content -->|"read notes"| node_notes_lib
node_learn_content -->|"enrich mdx"| node_content_lib
node_blog_lib -->|"feed list"| node_blog_index
node_blog_lib -->|"filter category"| node_blog_category
node_blog_lib -->|"resolve post"| node_blog_post
node_notes_lib -->|"feed list"| node_notes_index
node_notes_lib -->|"filter category"| node_notes_category
node_notes_lib -->|"resolve note"| node_notes_note
node_content_lib -->|"render mdx"| node_article_ui
node_content_lib -->|"article data"| node_blog_post
node_content_lib -->|"article data"| node_notes_note
node_search_lib -->|"build index"| node_search_index
node_search_lib -->|"query data"| node_search_ui
node_search_lib -->|"index text"| node_blog_content
node_search_lib -->|"index text"| node_notes_content
node_nav_lib -->|"structure nav"| node_nav_ui
node_visual_lib -->|"list demos"| node_visualizers_page
node_visual_lib -->|"resolve demo"| node_visualizer_detail
node_visual_html -->|"static asset"| node_visualizer_detail
node_app_root -->|"shell"| node_home_page
node_app_root -->|"shell"| node_blog_index
node_app_root -->|"shell"| node_notes_index
node_app_root -->|"shell"| node_search_page
node_app_root -->|"shell"| node_visualizers_page
node_nav_ui -->|"site chrome"| node_blog_post
node_nav_ui -->|"site chrome"| node_notes_note
node_search_ui -->|"page ui"| node_search_page
node_shared_ui -->|"support"| node_search_ui

click node_app_root "https://github.com/ishant-kb/codewithishant/blob/main/src/app/layout.tsx"
click node_home_page "https://github.com/ishant-kb/codewithishant/blob/main/src/app/page.tsx"
click node_blog_index "https://github.com/ishant-kb/codewithishant/blob/main/src/app/blog/page.tsx"
click node_blog_category "https://github.com/ishant-kb/codewithishant/blob/main/src/app/blog/[category]/page.tsx"
click node_blog_post "https://github.com/ishant-kb/codewithishant/blob/main/src/app/blog/[category]/[slug]/page.tsx"
click node_notes_index "https://github.com/ishant-kb/codewithishant/blob/main/src/app/notes/page.tsx"
click node_notes_category "https://github.com/ishant-kb/codewithishant/blob/main/src/app/notes/[category]/page.tsx"
click node_notes_note "https://github.com/ishant-kb/codewithishant/blob/main/src/app/notes/[category]/[slug]/page.tsx"
click node_search_page "https://github.com/ishant-kb/codewithishant/blob/main/src/app/search/page.tsx"
click node_visualizers_page "https://github.com/ishant-kb/codewithishant/blob/main/src/app/visualizers/page.tsx"
click node_visualizer_detail "https://github.com/ishant-kb/codewithishant/blob/main/src/app/visualizers/[slug]/page.tsx"
click node_blog_content "https://github.com/ishant-kb/codewithishant/tree/main/src/content/blog"
click node_notes_content "https://github.com/ishant-kb/codewithishant/tree/main/src/content/notes"
click node_learn_content "https://github.com/ishant-kb/codewithishant/tree/main/src/content/learn"
click node_blog_lib "https://github.com/ishant-kb/codewithishant/tree/main/src/lib/blog"
click node_notes_lib "https://github.com/ishant-kb/codewithishant/tree/main/src/lib/notes"
click node_content_lib "https://github.com/ishant-kb/codewithishant/tree/main/src/lib/content"
click node_search_lib "https://github.com/ishant-kb/codewithishant/tree/main/src/lib/search"
click node_nav_lib "https://github.com/ishant-kb/codewithishant/blob/main/src/lib/navigation/getSidebar.ts"
click node_visual_lib "https://github.com/ishant-kb/codewithishant/blob/main/src/lib/visual/visualizer.ts"
click node_article_ui "https://github.com/ishant-kb/codewithishant/tree/main/src/components/features/article"
click node_nav_ui "https://github.com/ishant-kb/codewithishant/tree/main/src/components/features/navigation"
click node_search_ui "https://github.com/ishant-kb/codewithishant/tree/main/src/components/features/search"
click node_shared_ui "https://github.com/ishant-kb/codewithishant/tree/main/src/components/ui"
click node_search_index "https://github.com/ishant-kb/codewithishant/blob/main/public/search-index.json"
click node_visual_html "https://github.com/ishant-kb/codewithishant/blob/main/public/visualizers/bubbleSort/bubbleSort.html"

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_app_root,node_home_page,node_blog_index,node_blog_category,node_blog_post,node_notes_index,node_notes_category,node_notes_note,node_search_page,node_visualizers_page,node_visualizer_detail toneBlue
class node_blog_content,node_notes_content,node_learn_content toneAmber
class node_blog_lib,node_notes_lib,node_content_lib,node_search_lib,node_nav_lib,node_visual_lib toneMint
class node_article_ui,node_nav_ui,node_search_ui,node_shared_ui toneRose
class node_search_index,node_visual_html toneIndigo
```

## Components

### App routes

Next.js App Router pages and route segments.

- [Site shell](https://github.com/ishant-kb/codewithishant/blob/main/src/app/layout.tsx): next-layout · Global app layout and base styles. · `src/app/layout.tsx`
- [Home](https://github.com/ishant-kb/codewithishant/blob/main/src/app/page.tsx): route · Top-level landing page. · `src/app/page.tsx`
- [Blog index](https://github.com/ishant-kb/codewithishant/blob/main/src/app/blog/page.tsx): route · Blog listing route. · `src/app/blog/page.tsx`
- [Blog category](https://github.com/ishant-kb/codewithishant/blob/main/src/app/blog/[category]/page.tsx): route · Category listing for blog posts. · `src/app/blog/[category]/page.tsx`
- [Blog post](https://github.com/ishant-kb/codewithishant/blob/main/src/app/blog/[category]/[slug]/page.tsx): route · Nested blog post detail page. · `src/app/blog/[category]/[slug]/page.tsx`
- [Notes index](https://github.com/ishant-kb/codewithishant/blob/main/src/app/notes/page.tsx): route · Notes listing route. · `src/app/notes/page.tsx`
- [Notes category](https://github.com/ishant-kb/codewithishant/blob/main/src/app/notes/[category]/page.tsx): route · Category listing for notes. · `src/app/notes/[category]/page.tsx`
- [Note detail](https://github.com/ishant-kb/codewithishant/blob/main/src/app/notes/[category]/[slug]/page.tsx): route · Nested note detail page. · `src/app/notes/[category]/[slug]/page.tsx`
- [Search](https://github.com/ishant-kb/codewithishant/blob/main/src/app/search/page.tsx): route · Dedicated search page. · `src/app/search/page.tsx`
- [Visualizers](https://github.com/ishant-kb/codewithishant/blob/main/src/app/visualizers/page.tsx): route · Browse visual demo pages. · `src/app/visualizers/page.tsx`
- [Visualizer](https://github.com/ishant-kb/codewithishant/blob/main/src/app/visualizers/[slug]/page.tsx): route · Single visualizer detail page. · `src/app/visualizers/[slug]/page.tsx`

### Content sources

MDX content organized by domain.

- [Blog MDX](https://github.com/ishant-kb/codewithishant/tree/main/src/content/blog): mdx-corpus · Authored blog posts organized by category. · `src/content/blog`
- [Notes MDX](https://github.com/ishant-kb/codewithishant/tree/main/src/content/notes): mdx-corpus · Authored notes organized by category. · `src/content/notes`
- [Learn MDX](https://github.com/ishant-kb/codewithishant/tree/main/src/content/learn): mdx-corpus · Learning material corpus for future or partial routing. · `src/content/learn`

### Lib layer

Content access, indexing, and transformation helpers.

- [Blog data](https://github.com/ishant-kb/codewithishant/tree/main/src/lib/blog): content-service · Fetches blog posts and relationships. · `src/lib/blog`
- [Notes data](https://github.com/ishant-kb/codewithishant/tree/main/src/lib/notes): content-service · Fetches notes and relationships. · `src/lib/notes`
- [Content enrich](https://github.com/ishant-kb/codewithishant/tree/main/src/lib/content): content-transform · Shared article enrichment helpers for MDX content. · `src/lib/content`
- [Search index](https://github.com/ishant-kb/codewithishant/tree/main/src/lib/search): search-pipeline · Extracts text, normalizes it, and builds search indexes. · `src/lib/search`
- [Sidebar data](https://github.com/ishant-kb/codewithishant/blob/main/src/lib/navigation/getSidebar.ts): nav-builder · Derives navigation structure from content. · `src/lib/navigation/getSidebar.ts`
- [Visualizer registry](https://github.com/ishant-kb/codewithishant/blob/main/src/lib/visual/visualizer.ts): registry · Descriptor layer for visualizer pages. · `src/lib/visual/visualizer.ts`

### Components

Reusable feature and shared UI components.

- [Article UI](https://github.com/ishant-kb/codewithishant/tree/main/src/components/features/article): mdx-rendering · Custom MDX components, code blocks, and table of contents. · `src/components/features/article`
- [Navigation UI](https://github.com/ishant-kb/codewithishant/tree/main/src/components/features/navigation): shell-ui · Navbar, sidebar, and breadcrumbs. · `src/components/features/navigation`
- [Search UI](https://github.com/ishant-kb/codewithishant/tree/main/src/components/features/search): search-ui · Search page and command palette experiences. · `src/components/features/search`
- [Shared UI](https://github.com/ishant-kb/codewithishant/tree/main/src/components/ui): ui-kit · General reusable UI and status components. · `src/components/ui`

### Public assets

Static files and generated artifacts served from public.

- [Search index](https://github.com/ishant-kb/codewithishant/blob/main/public/search-index.json): generated-asset · Precomputed client-consumable search data. · `public/search-index.json`
- [Bubble sort demo](https://github.com/ishant-kb/codewithishant/blob/main/public/visualizers/bubbleSort/bubbleSort.html): static-demo · Standalone visualizer HTML asset. · `public/visualizers/bubbleSort/bubbleSort.html`

## Connections

- Blog MDX → Blog data: read posts · Blog content is read and structured by blog helpers.
- Notes MDX → Notes data: read notes · Notes content is read and structured by notes helpers.
- Learn MDX → Content enrich: enrich mdx · Shared content utilities can process learning MDX as well.
- Blog data → Blog index: feed list · Blog listing pages consume post collections.
- Blog data → Blog category: filter category · Category pages are built from category-filtered posts.
- Blog data → Blog post: resolve post · Detail pages load a single post and related navigation data.
- Notes data → Notes index: feed list · Notes listing pages consume note collections.
- Notes data → Notes category: filter category · Category pages are built from category-filtered notes.
- Notes data → Note detail: resolve note · Detail pages load a single note and related navigation data.
- Content enrich → Article UI: render mdx · MDX enrichment powers article presentation.
- Content enrich → Blog post: article data · Post pages use headings, metadata, reading time, and tags.
- Content enrich → Note detail: article data · Note pages use the same enrichment pipeline.
- Search index → Search index: build index · Search data is precomputed into a static JSON artifact.
- Search index → Search UI: query data · Search interfaces consume normalized search helpers.
- Search index → Blog MDX: index text · Search indexes authored blog content.
- Search index → Notes MDX: index text · Search indexes authored notes content.
- Sidebar data → Navigation UI: structure nav · Sidebar and breadcrumb structure is content-aware.
- Visualizer registry → Visualizers: list demos · Visualizer registry drives the browse page.
- Visualizer registry → Visualizer: resolve demo · Detail pages resolve a specific visualizer descriptor.
- Bubble sort demo → Visualizer: static asset · At least one visualizer is served as standalone HTML.
- Site shell → Home: shell · All routes render within the global app shell.
- Site shell → Blog index: shell · All routes render within the global app shell.
- Site shell → Notes index: shell · All routes render within the global app shell.
- Site shell → Search: shell · All routes render within the global app shell.
- Site shell → Visualizers: shell · All routes render within the global app shell.
- Navigation UI → Blog post: site chrome · Shared navigation appears across content pages.
- Navigation UI → Note detail: site chrome · Shared navigation appears across content pages.
- Search UI → Search: page ui · Search route renders dedicated search components.
- Shared UI → Search UI: support · General UI primitives support search interactions.
