# narainkarthikv/portfolio architecture

> Architecture diagram of the GitHub repository narainkarthikv/portfolio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/narainkarthikv/portfolio
- Repository: https://github.com/narainkarthikv/portfolio

## Overview

##### What this project is (type + purpose)
This repo is a **personal portfolio website** that is primarily a **static site**:

- **Primary (modern) implementation:** **Astro** site in `src/` (with components, pages, layouts, scripts) + Tailwind + TypeScript.
- **Legacy implementation:** a standalone static site in `legacy/` (`index.html`, `styles.css`, `app.js`, `cv.json`) that the README explicitly calls out as the **GitHub Pages source**.

- **Build-time architecture** (Astro SSG + asset pipeline + CI),
- **Runtime architecture** (browser fetching static assets from a CDN/Pages),
- **External embeds/integrations** (e.g., Spotify component, sitemap/robots generation).

##### Runtime-facing (what ships to users)
- `public/` — static assets (PDF, mp3, webmanifest).
- `src/pages/` — route entrypoints:
- `index.astro` (home)
- `blog.astro` (blog page)
- `robots.txt.ts` and `sitemap.xml.ts` (**generated at build time** but served as static endpoints)
- `src/components/` + `src/components/sections/` — UI building blocks (Hero/About/Projects/etc.)
- `src/layouts/Layout.astro` — global shell
- `src/scripts/` — client-side JS (navigation/search/main)
- `src/globals.css` + `tailwind.config.mjs` — styling system

##### Data/content inputs
- `cv.json` at repo root (and `legacy/cv.json`) — content source for CV/resume sections (likely loaded at build time or bundled).
- `public/narainkarthik-cv.pdf` and `legacy/narainkarthik-cv.pdf` — downloadable artifact.

##### “Library” / reusable logic
- `src/lib/contextCursor/**` — custom cursor/context interaction logic (a mini internal library with chunks/modes/types).

##### Build/deploy plumbing
- `package.json`, lockfiles — Node toolchain.
- `astro.config.mjs`, `tsconfig.json` — build configuration.
- `.github/workflows/static.yml` — CI/CD for GitHub Pages.
- `netlify.toml`, `vercel.json`, `astro.config.vercel.mjs` — alternative deployment adapters/targets.

- `legacy/` — classic static HTML/CSS/JS site, and README says GH Pages serves from `./legacy/`.

Shows how code becomes static assets and where they get published.

Shows browser requests to a static host/CDN + any third-party embeds.

##### Architectural patterns/design principles evident here
- **Static Site Generation (SSG)** via Astro (`src/pages/*.astro`)
- **Componentized UI** (`src/components/**`, `src/components/sections/**`)
- **Separation of concerns**
- Layouts (`src/layouts`)
- Content/data (`cv.json`)
- Client scripts (`src/scripts`)
- Reusable internal lib (`src/lib/contextCursor`)
- **Multi-environment deployment readiness**
- GitHub Pages (workflow)
- Netlify + Vercel configs present

##### Build & Repo (GitHub + Actions + Astro toolchain)
And a separate boundary for **Legacy Site** vs **Astro Site** (this repo has both—don’t merge them mentally).

##### Step 3: Populate with concrete nodes named after repo artifacts
- “Astro Pages: `src/pages/index.astro`, `src/pages/blog.astro`”
- “Generated endpoints: `src/pages/sitemap.xml.ts`, `src/pages/robots.txt.ts`”
- “UI Sections: `src/components/sections/*`”
- “Client Scripts: `src/scripts/{main,navigation,search}.ts`”
- “Internal lib: `src/lib/contextCursor/*`”
- “Legacy site: `legacy/index.html`, `legacy/app.js`, `legacy/styles.css`”

Examples:
- Browser → Static Host: “GET /index.html, /assets/*”
- Browser → Static Host: “GET /sitemap.xml, /robots.txt”
- Browser → Spotify: “Embed/requests (iframe/api)”
- GitHub → Actions: “push triggers workflow”
- Actions → Pages: “deploy artifact”

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =======================
  %% Runtime lane (top)
  %% =======================
  subgraph "Runtime (User requests & execution)"
    direction TB

    Browser["User Browser\n(HTML/CSS/JS runtime)"]:::runtime

    subgraph "Static Hosting / CDN (serves static files)"
      direction TB
      GHP["GitHub Pages\n(primary per README)"]:::host
      NET["Netlify\n(optional target)"]:::hostAlt
      VER["Vercel\n(optional target)"]:::hostAlt
    end

    subgraph "Published Static Artifacts"
      direction TB

      subgraph "Legacy Publish Artifact (direct static)"
        direction TB
        LegacySite["Legacy Static Site\n(legacy/index.html + styles.css + app.js)"]:::legacy
        LegacyCV["Legacy CV Data & PDF\n(legacy/cv.json + legacy/narainkarthik-cv.pdf)"]:::legacy
      end

      subgraph "Astro Publish Artifact (SSG output)"
        direction TB
        AstroHTML["Astro-generated HTML routes\n(/, /blog)"]:::artifact
        AstroGen["Generated endpoints\n(/robots.txt, /sitemap.xml)"]:::artifact
        AstroAssets["Static assets\n(PDF/MP3/manifest)"]:::artifact
      end
    end

    Spotify["Spotify Service\n(embed/requests)"]:::external
  end

  %% Runtime flows
  Browser -->|"GET_/,_/blog,_/assets/*"| GHP
  Browser -->|"GET_/robots.txt,_/sitemap.xml"| GHP
  Browser -->|"GET_/narainkarthik-cv.pdf,_/site.webmanifest"| GHP
  Browser -.->|"optional:_GET_static_site"| NET
  Browser -.->|"optional:_GET_static_site"| VER
  Browser -->|"embed/requests"| Spotify

  GHP -->|"serves"| LegacySite
  GHP -->|"serves"| LegacyCV
  GHP -.->|"if_Astro_deployed:_serves"| AstroHTML
  GHP -.->|"if_Astro_deployed:_serves"| AstroGen
  GHP -.->|"if_Astro_deployed:_serves"| AstroAssets

  NET -.->|"optional:_serves"| AstroHTML
  NET -.->|"optional:_serves"| AstroGen
  NET -.->|"optional:_serves"| AstroAssets

  VER -.->|"optional:_serves"| AstroHTML
  VER -.->|"optional:_serves"| AstroGen
  VER -.->|"optional:_serves"| AstroAssets

  %% =======================
  %% Build & Deploy lane (bottom)
  %% =======================
  subgraph "Build & Deployment (Repo → CI → Static host)"
    direction TB

    Dev["Developer Machine"]:::build

    subgraph "Repository (source inputs)"
      direction TB
      Repo["GitHub Repository"]:::build

      subgraph "Astro Site Source (src/)"
        direction TB
        Pages["Pages & Routes\nsrc/pages/"]:::code
        Robots["robots endpoint\nsrc/pages/robots.txt.ts"]:::code
        Sitemap["sitemap endpoint\nsrc/pages/sitemap.xml.ts"]:::code
        Layout["Global Layout\nsrc/layouts/Layout.astro"]:::code
        Components["UI Components\nsrc/components/"]:::code
        Sections["UI Sections\nsrc/components/sections/"]:::code
        Scripts["Client Scripts\nsrc/scripts/"]:::code
        CursorLib["Internal Lib\nsrc/lib/contextCursor/"]:::code
        Styling["Styling System\n(src/globals.css + tailwind.config.mjs)"]:::code
      end

      PublicDir["Astro Public Assets\npublic/"]:::code
      CVRoot["CV/Resume Data\ncv.json"]:::code

      LegacyDir["Legacy Site Source\nlegacy/"]:::legacy

      Toolchain["Node Toolchain\npackage.json"]:::build
      TSConfig["TypeScript Config\ntsconfig.json"]:::build
      AstroCfg["Astro Config\nastro.config.mjs"]:::build
      NetlifyCfg["Netlify Config\nnetlify.toml"]:::build
      VercelCfg["Vercel Config\n(vercel.json + astro.config.vercel.mjs)"]:::build
    end

    subgraph "CI/CD"
      direction TB
      GHA["GitHub Actions\n(static.yml)"]:::cicd
      BuildLegacy["Publish legacy/ directly\n(no build)"]:::cicd
      BuildAstro["Astro SSG Build (Node.js)\n+ Tailwind pipeline"]:::cicd
      Dist["Static Output\n(dist/ equivalent)"]:::artifact
    end
  end

  %% Build flows
  Dev -->|"commit/push"| Repo
  Repo -->|"push/PR_triggers"| GHA

  %% Two possible publish artifacts (migration/parallel)
  GHA -->|"deploy_path_A"| BuildLegacy
  BuildLegacy -->|"artifact:_legacy/"| GHP

  GHA -->|"deploy_path_B"| BuildAstro
  BuildAstro -->|"inputs:_src/,_public/,_cv.json"| Dist
  Dist -.->|"deploy_to"| GHP
  Dist -.->|"deploy_to_(optional)"| NET
  Dist -.->|"deploy_to_(optional)"| VER

  %% Internal build dependencies (kept vertical)
  BuildAstro -->|"reads"| Pages
  BuildAstro -->|"executes"| Robots
  BuildAstro -->|"executes"| Sitemap
  BuildAstro -->|"uses"| Layout
  BuildAstro -->|"uses"| Components
  BuildAstro -->|"uses"| Sections
  BuildAstro -->|"bundles"| Scripts
  BuildAstro -->|"uses"| CursorLib
  BuildAstro -->|"tailwind_from"| Styling
  BuildAstro -->|"copies"| PublicDir
  BuildAstro -->|"loads_content"| CVRoot
  BuildAstro -->|"config"| AstroCfg
  BuildAstro -->|"ts_config"| TSConfig
  BuildAstro -->|"toolchain"| Toolchain

  %% Notes as relationships (avoid long horizontal)
  LegacyDir -->|"is_source_for"| BuildLegacy

  %% =======================
  %% Click events (from component_mapping)
  %% =======================
  click Pages "https://github.com/narainkarthikv/portfolio/tree/develop/src/pages/"
  click Robots "https://github.com/narainkarthikv/portfolio/blob/develop/src/pages/robots.txt.ts"
  click Sitemap "https://github.com/narainkarthikv/portfolio/blob/develop/src/pages/sitemap.xml.ts"
  click Layout "https://github.com/narainkarthikv/portfolio/blob/develop/src/layouts/Layout.astro"
  click Components "https://github.com/narainkarthikv/portfolio/tree/develop/src/components/"
  click Sections "https://github.com/narainkarthikv/portfolio/tree/develop/src/components/sections/"
  click Scripts "https://github.com/narainkarthikv/portfolio/tree/develop/src/scripts/"
  click CursorLib "https://github.com/narainkarthikv/portfolio/tree/develop/src/lib/contextCursor/"
  click Styling "https://github.com/narainkarthikv/portfolio/blob/develop/src/globals.css"
  click PublicDir "https://github.com/narainkarthikv/portfolio/tree/develop/public/"
  click CVRoot "https://github.com/narainkarthikv/portfolio/blob/develop/cv.json"
  click LegacyDir "https://github.com/narainkarthikv/portfolio/tree/develop/legacy/"
  click GHA "https://github.com/narainkarthikv/portfolio/blob/develop/.github/workflows/static.yml"
  click AstroCfg "https://github.com/narainkarthikv/portfolio/blob/develop/astro.config.mjs"
  click VercelCfg "https://github.com/narainkarthikv/portfolio/blob/develop/vercel.json"
  click NetlifyCfg "https://github.com/narainkarthikv/portfolio/blob/develop/netlify.toml"
  click Toolchain "https://github.com/narainkarthikv/portfolio/blob/develop/package.json"
  click TSConfig "https://github.com/narainkarthikv/portfolio/blob/develop/tsconfig.json"
  click LegacyCV "https://github.com/narainkarthikv/portfolio/blob/develop/legacy/cv.json"
  click LegacySite "https://github.com/narainkarthikv/portfolio/blob/develop/legacy/index.html"

  %% Spotify component mapping
  click Spotify "https://github.com/narainkarthikv/portfolio/blob/develop/src/components/Spotify.astro"

  %% Extra component mapping clicks (examples mentioned)
  click Components "https://github.com/narainkarthikv/portfolio/tree/develop/src/components/"
  click Sections "https://github.com/narainkarthikv/portfolio/tree/develop/src/components/sections/"

  %% =======================
  %% Styles (color critical)
  %% =======================
  classDef runtime fill:#D6ECFF,stroke:#1D4ED8,stroke-width:1.5px,color:#0B1B3A
  classDef host fill:#BFDBFE,stroke:#1E40AF,stroke-width:1.5px,color:#0B1B3A
  classDef hostAlt fill:#E0E7FF,stroke:#4338CA,stroke-width:1.2px,color:#111827,stroke-dasharray: 4 3
  classDef external fill:#D1FAE5,stroke:#047857,stroke-width:1.5px,color:#052E2B
  classDef build fill:#E9D5FF,stroke:#7C3AED,stroke-width:1.2px,color:#1F1235
  classDef cicd fill:#F5D0FE,stroke:#A21CAF,stroke-width:1.2px,color:#2A0A2A
  classDef code fill:#F3F4F6,stroke:#374151,stroke-width:1px,color:#111827
  classDef legacy fill:#E5E7EB,stroke:#4B5563,stroke-width:1.2px,color:#111827
  classDef artifact fill:#FEF3C7,stroke:#B45309,stroke-width:1.2px,color:#3A2200
```
