# adolph97/portfolio architecture

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

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

## Overview

##### What this project is (type + purpose)
This is a **static, client-rendered personal portfolio web app** built with **React + TypeScript** and bundled by **Vite**. It’s primarily a **front-end SPA** that renders multiple “sections” (Hero, Portfolio, Services, etc.) and includes interactive elements (custom cursor, 3D scene via Three.js).

There is also an `api/` folder containing `api/contact.ts`, which strongly suggests **one serverless API endpoint** (e.g., Vercel/Netlify-style function) for contact form submissions. So architecturally it’s “mostly static frontend” + “optional backend function”.

##### Frontend entry + composition
- `index.html` — Vite entry HTML shell (loads the JS bundle).
- `index.tsx` — React bootstrap (mounts the app into DOM).
- `App.tsx` — top-level composition and routing (likely single-page sections).
- `index.css` — global styling.

##### UI/components structure
- `components/Navigation.tsx` — top navigation, anchors to sections.
- `components/CustomCursor.tsx` — global cursor behavior, event listeners.
- `components/ThreeScene.tsx` — Three.js canvas/scene management (renderer, camera, animation loop).
- `components/UI/*` — smaller widgets:
- `RotatingGlobe.tsx` (likely Three/Canvas or SVG)
- `ScrollToTop.tsx`
- `SocialLinks.tsx`
- `SystemStatus.tsx` (could call an external status API or just render a status indicator)

##### Page sections (feature modules)
- `components/Sections/*`:
- `Hero.tsx`, `Portfolio.tsx`, `Services.tsx`, `Process.tsx`, `TechStack.tsx`, `Testimonials.tsx`, `GlobalPresence.tsx`, `Contact.tsx`

##### Backend/API (optional but important)
- `api/contact.ts` — one API endpoint/function. Typically:
- receives POST from `Contact` section
- validates payload
- sends email / writes somewhere / calls third-party service

##### Build output + hosting
- `dist/` — built artifacts (bundled JS/CSS, optimized assets, `dist/index.html`).
- `public/` — static assets copied as-is (images, logos).
- `vite.config.ts`, `tsconfig.json`, `package.json` — build/toolchain boundary.

##### What the README adds (stack + key features to highlight)
From README:
- Interactive UI, 3D elements → highlight **Three.js rendering loop** and **browser GPU/canvas** boundary.
- Modular sections → highlight internal component modularity.
- React+TS+Vite → highlight toolchain and artifact pipeline.

The README’s “src/” in the example doesn’t match your tree (you have top-level `components/`, `App.tsx`, etc.), but functionally it’s the same: a React app with modular components.

##### System Context (C4 L1)
Who uses it, where it runs, what external dependencies exist.

Browser SPA, Static hosting/CDN, optional serverless API, external email/service.

App composition: App.tsx → Navigation/Sections/ThreeScene/UI widgets; Contact section → API call.

##### Browser → Static Host/CDN
- GET `/` → `index.html`
- GET `assets/index-*.js`, `assets/index-*.css`, images/logos
##### React SPA internal flows
- `index.tsx` mounts `App.tsx`
- `App.tsx` renders `Navigation`, `CustomCursor`, `ThreeScene`, and each `Sections/*`
- `Navigation` scrolls to anchors / section refs
- `ScrollToTop` listens to scroll, triggers window scroll
- `CustomCursor` listens to pointer events and updates UI
- `ThreeScene` creates WebGL context and runs animation loop (requestAnimationFrame)
##### Contact flow
- User submits in `Sections/Contact.tsx`
- `Contact.tsx` → HTTP POST `/api/contact` (or similar)
- `api/contact.ts` → (optional) Email provider / storage
- Response → UI success/failure state

##### Build/deploy (non-runtime but essential)
- `git push` → CI (optional) → `pnpm install` → `pnpm build` (Vite) → upload `dist/` to hosting

##### Architectural patterns/design principles present
- **Component-driven UI** (React): composition of independent UI modules.
- **Separation of concerns by folder**:
- `components/Sections/*` = feature/section modules
- `components/UI/*` = reusable UI primitives/widgets
- **Static-first architecture**:
- Most content served from CDN, minimal backend footprint.
- **Optional serverless backend**:
- A single-purpose function for contact (keeps site fast and secure vs embedding secrets client-side).
- **3D rendering boundary**:
- React manages DOM; Three.js manages canvas/WebGL. This is a key architectural seam worth drawing.

##### “As many components as possible” without overthinking it
- primary responsibility (1 line)
- key dependencies (e.g., ThreeScene → Three.js; Contact → fetch/api)
- key assets (images/logos)
- where it runs (Browser vs Serverless)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% System Context + Containers (Vertical)
  %% =========================
  U["User"]:::external

  subgraph HOST["Static Hosting / CDN"]
    CDN["Static Host + CDN<br/>(serves built artifacts)"]:::hosting
    DIST["dist/ (deployable build output)"]:::artifact
    DISTHTML["dist/index.html (built entry)"]:::artifact
    DISTASSETS["dist/assets/ (bundled JS/CSS)"]:::artifact
    PUB["public/ (static assets copied as-is)"]:::artifact
    PUBIMG["public/images (images)"]:::artifact
    PUBLOGO["public/Logos (logos)"]:::artifact
  end

  subgraph BROWSER["User Browser Runtime"]
    B["Browser<br/>(React SPA + Three.js/WebGL)"]:::client

    subgraph SPA["Client SPA (React + TypeScript)"]
      HTMLSHELL["Vite HTML Shell<br/>(index.html)"]:::client
      BOOT["React Bootstrap<br/>(index.tsx)"]:::client
      APP["App Root Composition<br/>(App.tsx)"]:::client
      CSS["Global Styles<br/>(index.css)"]:::client

      subgraph CORE["Core Components"]
        NAV["Navigation<br/>(anchors/scroll)"]:::client
        CURSOR["Custom Cursor<br/>(pointer events)"]:::client
        THREE["ThreeScene<br/>(WebGL canvas + RAF loop)"]:::client
      end

      subgraph UI["UI Widgets / Utilities"]
        GLOBE["RotatingGlobe"]:::client
        TOP["ScrollToTop"]:::client
        SOCIAL["SocialLinks"]:::client
        STATUS["SystemStatus"]:::client
      end

      subgraph SECTIONS["Page Sections (vertical slices)"]
        HERO["Hero"]:::client
        PORT["Portfolio"]:::client
        SERV["Services"]:::client
        PROC["Process"]:::client
        TECH["TechStack"]:::client
        TESTI["Testimonials"]:::client
        GLOBAL["GlobalPresence"]:::client
        CONTACTUI["Contact<br/>(form UI)"]:::client
      end
    end
  end

  subgraph BACKEND["Optional Backend (Serverless)"]
    API["Serverless Function<br/>api/contact"]:::backend
  end

  subgraph THIRD["Third-party Services (Optional)"]
    EMAIL[("Email Provider<br/>(SendGrid/Mailgun/SMTP)")]:::thirdparty
    STATUSAPI[("Status Provider API<br/>(optional)")]:::thirdparty
  end

  %% =========================
  %% Build / Tooling / Deploy Pipeline (Vertical)
  %% =========================
  subgraph PIPE["Build & Deploy Pipeline"]
    DEV["Developer / CI Runner"]:::pipeline
    PKG["package.json<br/>(scripts/deps)"]:::pipeline
    LOCK["pnpm-lock.yaml"]:::pipeline
    ENV[".env<br/>(env config)"]:::pipeline
    VITE["vite.config.ts"]:::pipeline
    TSC["tsconfig.json"]:::pipeline
    BUILD["Vite Build<br/>(pnpm build)"]:::pipeline
    DEPLOY["Deploy Upload<br/>(publish dist/)"]:::pipeline
  end

  %% =========================
  %% Runtime Relationships
  %% =========================
  U -->|"uses"| B
  B -->|"HTTP GET / (index.html)"| CDN
  CDN -->|"serves HTML/CSS/JS/images"| B

  B -->|"loads (built) index.html"| DISTHTML
  B -->|"loads bundles (JS/CSS)"| DISTASSETS
  B -->|"loads static assets"| PUB

  HTMLSHELL -->|"boots bundle"| BOOT
  BOOT -->|"mounts"| APP
  APP -->|"applies"| CSS

  APP -->|"renders"| NAV
  APP -->|"renders"| CURSOR
  APP -->|"renders"| THREE
  APP -->|"renders"| UI
  APP -->|"renders"| SECTIONS

  NAV -->|"scroll to anchors/refs"| SECTIONS
  CURSOR -->|"listens pointermove/click"| B
  TOP -->|"listens scroll"| B
  TOP -->|"window.scrollTo(0,0)"| B

  THREE -->|"creates WebGL context"| B
  THREE -->|"requestAnimationFrame loop"| B
  GLOBE -->|"visual widget"| B

  CONTACTUI -->|"POST /api/contact"| API
  API -->|"send message (optional)"| EMAIL
  STATUS -->|"fetch status (optional)"| STATUSAPI

  %% =========================
  %% Build/Deploy Relationships
  %% =========================
  DEV -->|"pnpm install"| PKG
  PKG -->|"resolves"| LOCK
  DEV -->|"reads"| ENV
  DEV -->|"uses config"| VITE
  DEV -->|"uses types"| TSC
  DEV -->|"runs"| BUILD
  VITE -->|"drives bundling"| BUILD
  TSC -->|"typecheck"| BUILD
  BUILD -->|"outputs"| DIST
  DIST -->|"contains"| DISTHTML
  DIST -->|"contains"| DISTASSETS
  BUILD -->|"copies from"| PUB
  BUILD -->|"copy includes"| PUBIMG
  BUILD -->|"copy includes"| PUBLOGO
  BUILD -->|"artifact ready"| DEPLOY
  DEPLOY -->|"publishes"| CDN

  %% =========================
  %% Click Events (paths only; not shown to user)
  %% =========================
  click HTMLSHELL "https://github.com/adolph97/portfolio/blob/main/index.html"
  click BOOT "https://github.com/adolph97/portfolio/blob/main/index.tsx"
  click APP "https://github.com/adolph97/portfolio/blob/main/App.tsx"
  click CSS "https://github.com/adolph97/portfolio/blob/main/index.css"
  click NAV "https://github.com/adolph97/portfolio/blob/main/components/Navigation.tsx"
  click CURSOR "https://github.com/adolph97/portfolio/blob/main/components/CustomCursor.tsx"
  click THREE "https://github.com/adolph97/portfolio/blob/main/components/ThreeScene.tsx"
  click GLOBE "https://github.com/adolph97/portfolio/blob/main/components/UI/RotatingGlobe.tsx"
  click TOP "https://github.com/adolph97/portfolio/blob/main/components/UI/ScrollToTop.tsx"
  click SOCIAL "https://github.com/adolph97/portfolio/blob/main/components/UI/SocialLinks.tsx"
  click STATUS "https://github.com/adolph97/portfolio/blob/main/components/UI/SystemStatus.tsx"
  click HERO "https://github.com/adolph97/portfolio/blob/main/components/Sections/Hero.tsx"
  click PORT "https://github.com/adolph97/portfolio/blob/main/components/Sections/Portfolio.tsx"
  click SERV "https://github.com/adolph97/portfolio/blob/main/components/Sections/Services.tsx"
  click PROC "https://github.com/adolph97/portfolio/blob/main/components/Sections/Process.tsx"
  click TECH "https://github.com/adolph97/portfolio/blob/main/components/Sections/TechStack.tsx"
  click TESTI "https://github.com/adolph97/portfolio/blob/main/components/Sections/Testimonials.tsx"
  click GLOBAL "https://github.com/adolph97/portfolio/blob/main/components/Sections/GlobalPresence.tsx"
  click CONTACTUI "https://github.com/adolph97/portfolio/blob/main/components/Sections/Contact.tsx"
  click API "https://github.com/adolph97/portfolio/blob/main/api/contact.ts"
  click DIST "https://github.com/adolph97/portfolio/tree/main/dist/"
  click DISTHTML "https://github.com/adolph97/portfolio/blob/main/dist/index.html"
  click DISTASSETS "https://github.com/adolph97/portfolio/tree/main/dist/assets/"
  click PUB "https://github.com/adolph97/portfolio/tree/main/public/"
  click PUBIMG "https://github.com/adolph97/portfolio/tree/main/public/images"
  click PUBLOGO "https://github.com/adolph97/portfolio/tree/main/public/Logos"
  click VITE "https://github.com/adolph97/portfolio/blob/main/vite.config.ts"
  click TSC "https://github.com/adolph97/portfolio/blob/main/tsconfig.json"
  click PKG "https://github.com/adolph97/portfolio/blob/main/package.json"
  click LOCK "https://github.com/adolph97/portfolio/blob/main/pnpm-lock.yaml"
  click ENV "https://github.com/adolph97/portfolio/blob/main/.env"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#F3F4F6,stroke:#6B7280,stroke-width:1px,color:#111827
  classDef hosting fill:#DCFCE7,stroke:#16A34A,stroke-width:1px,color:#052e16
  classDef artifact fill:#ECFDF5,stroke:#22C55E,stroke-width:1px,color:#052e16
  classDef client fill:#DBEAFE,stroke:#2563EB,stroke-width:1px,color:#0B1B4A
  classDef backend fill:#FFEDD5,stroke:#F97316,stroke-width:1px,color:#431407
  classDef thirdparty fill:#E5E7EB,stroke:#6B7280,stroke-width:1px,color:#111827
  classDef pipeline fill:#EDE9FE,stroke:#7C3AED,stroke-width:1px,color:#2E1065
```
