# shaheeii/shaheem-portfolio architecture

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

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

## Overview

##### Project type & purpose (from file tree + README)
This is a **Next.js (App Router) TypeScript** application, likely an **AI Studio “Gemini” demo/app**. The README focuses on running locally and requires `GEMINI_API_KEY`, which strongly implies:
- The UI is served by Next.js pages/components under `app/`.
- Server-side functionality exists via **Route Handlers** under `app/api/**/route.ts`.
- The app integrates with **Google Gemini API** (external service) using the API key in `.env.local`.

This is not a separate “frontend + backend repo”; it’s a **single Next.js full-stack app** (React UI + server routes in one codebase).

Key directories/files and what they represent architecturally:

##### Server / Backend (inside Next.js)
- `app/api/contact/route.ts` – server endpoint for contact form submission (likely POST)
- `app/api/webhook/route.ts` – server endpoint to receive external callbacks (webhooks)

##### Shared utilities / platform glue
- `lib/utils.ts` – shared helper functions (formatting, validation, fetch wrappers, etc.)
- `hooks/use-mobile.ts` – client hook (responsive behavior)
- `next.config.ts`, `tsconfig.json`, ESLint configs – build/runtime configuration

##### Environment / Secrets
- `.env.example` – documents needed env vars
- README: `.env.local` + `GEMINI_API_KEY` – secret used by server route handlers to call Gemini

##### Next.js Application (Node.js runtime)
- **App Router UI** (React server/client components: `app/*`, `components/*`)
- **API Route Handlers** (`app/api/contact`, `app/api/webhook`)
##### External Services
- **Google Gemini API** (called using `GEMINI_API_KEY`)

##### Architectural pattern to highlight
- **“Full-stack Next.js App Router”**: UI and server endpoints live together.
- **API routes as the boundary for secrets**: `GEMINI_API_KEY` should only be used server-side in `app/api/**`.
- **Componentized UI**: The UI is broken into section components (Hero, Portfolio, Philosophy, Contact, etc.).
- **No explicit database layer shown**: Important to reflect that the architecture is currently stateless *unless the API routes persist somewhere (not visible in the tree).*

##### Concrete labeling: what to name nodes (map to files)
Use labels that tie directly back to the repo to keep it “accurate”:

**UI**
- `app/page.tsx (Home Page)`
- `app/layout.tsx (Root Layout)`
- `components/Contact.tsx (Contact Form UI)`
- `components/Hero.tsx`, `components/Navbar.tsx`, etc. (Landing sections)
- `hooks/use-mobile.ts (Responsive Hook)`

**Backend**
- `app/api/contact/route.ts (Contact API)`
- `app/api/webhook/route.ts (Webhook API)`
- `lib/utils.ts (Shared Utilities)`

**External**
- `Google Gemini API`
- `External Webhook Provider (unknown)`

##### Diagramming conventions to make it “best and most accurate”
Elements explicitly:

##### Clear labels
- **route paths** on API nodes:
- `POST /api/contact`
- `POST /api/webhook`
- **runtime boundary** labels: “Browser”, “Next.js (Server)”, “External”.

- `HTTPS GET (HTML/JS/CSS)` Browser → Next.js
- `HTTPS POST (form JSON)` Browser → `/api/contact`
- `HTTPS POST (event JSON)` Webhook Provider → `/api/webhook`
- `HTTPS POST (prompt/messages)` Next.js API → Gemini
- `HTTPS response (completion JSON)` Gemini → Next.js API

##### Trust boundaries (important here)
- **Public Internet** (Browser + External webhook provider)
- **Your Server (Next.js runtime)**
That:
- `GEMINI_API_KEY` stays inside server boundary (never in browser)

Deliver these artifacts:

That combination will be both detailed and faithful to this repo’s structure, while making the Gemini integration and Next.js full-stack nature immediately clear.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% C4 L1 — System Context
  %% =========================
  subgraph "C4 L1 — System Context"
    direction TB

    User["End User (Browser)"]:::external
    WebhookSender["External Webhook Provider (Unknown)"]:::external
    Gemini["Google Gemini API"]:::external
    EmailCRM["(Optional) Email/CRM Provider"]:::external

    subgraph "AI Studio Next.js App (Full-stack)"
      direction TB
      AppContext["Next.js Application (App Router + Route Handlers)"]:::system
    end

    User -->|"HTTPS GET (HTML/JS/CSS)"| AppContext
    User -->|"HTTPS POST (/api/contact)"| AppContext
    WebhookSender -->|"HTTPS POST (/api/webhook)"| AppContext
    AppContext -->|"HTTPS POST (LLM prompt/messages)"| Gemini
    AppContext -->|"HTTPS POST (message forwarding)"| EmailCRM
  end

  %% =========================
  %% C4 L2 — Container Diagram
  %% =========================
  subgraph "C4 L2 — Containers (Inside Next.js Runtime)"
    direction TB

    subgraph "Presentation (App Router UI)"
      direction TB
      Layout["Root Layout (app/layout.tsx)"]:::ui
      Home["Home Page (app/page.tsx)"]:::ui
      Globals["Global CSS (app/globals.css)"]:::config
      Assets["Static Assets (public/*)"]:::storage

      subgraph "Reusable UI Components (components/*)"
        direction TB
        Navbar["Navbar (components/Navbar.tsx)"]:::ui
        Hero["Hero (components/Hero.tsx)"]:::ui
        Portfolio["Portfolio (components/Portfolio.tsx)"]:::ui
        Philosophy["Philosophy (components/Philosophy.tsx)"]:::ui
        Experience["Experience (components/Experience.tsx)"]:::ui
        ContactUI["Contact Form UI (components/Contact.tsx)"]:::ui
        CTA["Cinematic CTA (components/CinematicCTA.tsx)"]:::ui
        ClickFX["Click Effect (components/ClickEffect.tsx)"]:::ui
        Footer["Footer (components/Footer.tsx)"]:::ui
      end

      MobileHook["Responsive Hook (hooks/use-mobile.ts)"]:::util
    end

    subgraph "Server (Next.js Route Handlers)"
      direction TB
      ContactAPI["POST /api/contact (app/api/contact/route.ts)"]:::api
      WebhookAPI["POST /api/webhook (app/api/webhook/route.ts)"]:::api
      Utils["Shared Utilities (lib/utils.ts)"]:::util

      Env["Server Env: GEMINI_API_KEY (.env.local)"]:::secret
      EnvTemplate["Env Template (.env.example)"]:::config
    end

    subgraph "Build & Tooling"
      direction TB
      NextCfg["Next.js Config (next.config.ts)"]:::config
      TSCfg["TypeScript Config (tsconfig.json)"]:::config
      ESLintCfg["ESLint Config (.eslintrc.json + eslint.config.mjs)"]:::config
      PostCSSCfg["PostCSS Config (postcss.config.mjs)"]:::config
    end

    %% Composition / dependencies (UI)
    Layout -->|"wraps"| Home
    Home -->|"composes"| Navbar
    Home -->|"composes"| Hero
    Home -->|"composes"| Portfolio
    Home -->|"composes"| Philosophy
    Home -->|"composes"| Experience
    Home -->|"composes"| ContactUI
    Home -->|"composes"| CTA
    Home -->|"composes"| ClickFX
    Home -->|"composes"| Footer
    Home -->|"uses"| MobileHook
    Layout -->|"loads"| Globals
    Home -->|"serves"| Assets

    %% UI -> API calls
    ContactUI -->|"HTTPS POST (form JSON)"| ContactAPI

    %% API internal usage
    ContactAPI -->|"uses"| Utils
    WebhookAPI -->|"uses"| Utils
    EnvTemplate -->|"documents"| Env
    Env -->|"provides_secret"| ContactAPI
    Env -->|"provides_secret"| WebhookAPI

    %% External interactions
    ContactAPI -->|"HTTPS POST (prompt/messages)"| Gemini
    WebhookAPI -->|"HTTPS POST (event->prompt?)"| Gemini
    ContactAPI -->|"HTTPS POST (message forwarding?)"| EmailCRM
  end

  %% =========================
  %% C4 L3 — API Component View
  %% =========================
  subgraph "C4 L3 — API Components (Route Handler Internals)"
    direction TB

    subgraph "POST /api/contact"
      direction TB
      C_In["Request Parse"]:::step
      C_Validate["Validate Input"]:::step
      C_Prompt["Build Prompt / Payload"]:::step
      C_CallGemini["Call Gemini API"]:::step
      C_Shape["Shape Response (JSON)"]:::step
      C_Error["Error Handling / Logging"]:::step

      C_In --> C_Validate --> C_Prompt --> C_CallGemini --> C_Shape
      C_In -->|"on_error"| C_Error
      C_Validate -->|"on_error"| C_Error
      C_CallGemini -->|"on_error"| C_Error
    end

    subgraph "POST /api/webhook"
      direction TB
      W_In["Request Parse"]:::step
      W_Verify["Verify Signature / Auth (if present)"]:::step
      W_Validate["Validate Event"]:::step
      W_Process["Process Event"]:::step
      W_CallGemini["Call Gemini API (optional)"]:::step
      W_Ack["Acknowledge (2xx JSON)"]:::step
      W_Error["Error Handling / Logging"]:::step

      W_In --> W_Verify --> W_Validate --> W_Process --> W_Ack
      W_Process -->|"if_AI_processing"| W_CallGemini --> W_Ack
      W_In -->|"on_error"| W_Error
      W_Verify -->|"on_error"| W_Error
      W_Validate -->|"on_error"| W_Error
      W_CallGemini -->|"on_error"| W_Error
    end

    %% Tie to shared utils + secrets + externals
    Utils2["Shared Utilities (lib/utils.ts)"]:::util
    Env2["GEMINI_API_KEY (server-only)"]:::secret

    C_Validate -->|"uses"| Utils2
    C_Prompt -->|"uses"| Utils2
    C_CallGemini -->|"auth_via"| Env2
    C_CallGemini -->|"HTTPS"| Gemini

    W_Verify -->|"uses"| Utils2
    W_Validate -->|"uses"| Utils2
    W_CallGemini -->|"auth_via"| Env2
    W_CallGemini -->|"HTTPS"| Gemini
  end

  %% =========================
  %% Click Events (from mapping)
  %% =========================
  click Layout "https://github.com/shaheeii/shaheem-portfolio/blob/main/app/layout.tsx"
  click Home "https://github.com/shaheeii/shaheem-portfolio/blob/main/app/page.tsx"
  click Globals "https://github.com/shaheeii/shaheem-portfolio/blob/main/app/globals.css"
  click Assets "https://github.com/shaheeii/shaheem-portfolio/tree/main/public/"
  click Navbar "https://github.com/shaheeii/shaheem-portfolio/blob/main/components/Navbar.tsx"
  click Hero "https://github.com/shaheeii/shaheem-portfolio/blob/main/components/Hero.tsx"
  click Portfolio "https://github.com/shaheeii/shaheem-portfolio/blob/main/components/Portfolio.tsx"
  click Philosophy "https://github.com/shaheeii/shaheem-portfolio/blob/main/components/Philosophy.tsx"
  click Experience "https://github.com/shaheeii/shaheem-portfolio/blob/main/components/Experience.tsx"
  click ContactUI "https://github.com/shaheeii/shaheem-portfolio/blob/main/components/Contact.tsx"
  click CTA "https://github.com/shaheeii/shaheem-portfolio/blob/main/components/CinematicCTA.tsx"
  click ClickFX "https://github.com/shaheeii/shaheem-portfolio/blob/main/components/ClickEffect.tsx"
  click Footer "https://github.com/shaheeii/shaheem-portfolio/blob/main/components/Footer.tsx"
  click ContactAPI "https://github.com/shaheeii/shaheem-portfolio/blob/main/app/api/contact/route.ts"
  click WebhookAPI "https://github.com/shaheeii/shaheem-portfolio/blob/main/app/api/webhook/route.ts"
  click Utils "https://github.com/shaheeii/shaheem-portfolio/blob/main/lib/utils.ts"
  click Utils2 "https://github.com/shaheeii/shaheem-portfolio/blob/main/lib/utils.ts"
  click MobileHook "https://github.com/shaheeii/shaheem-portfolio/blob/main/hooks/use-mobile.ts"
  click EnvTemplate "https://github.com/shaheeii/shaheem-portfolio/blob/main/.env.example"
  click NextCfg "https://github.com/shaheeii/shaheem-portfolio/blob/main/next.config.ts"
  click TSCfg "https://github.com/shaheeii/shaheem-portfolio/blob/main/tsconfig.json"
  click ESLintCfg "https://github.com/shaheeii/shaheem-portfolio/blob/main/.eslintrc.json"
  click PostCSSCfg "https://github.com/shaheeii/shaheem-portfolio/blob/main/postcss.config.mjs"
  click AppContext "https://github.com/shaheeii/shaheem-portfolio/tree/main/app/"

  %% =========================
  %% Styles
  %% =========================
  classDef system fill:#1f2937,stroke:#0b1220,color:#ffffff,stroke-width:2px
  classDef ui fill:#2563eb,stroke:#1e40af,color:#ffffff,stroke-width:1.5px
  classDef api fill:#16a34a,stroke:#14532d,color:#ffffff,stroke-width:1.5px
  classDef external fill:#f59e0b,stroke:#92400e,color:#111827,stroke-width:1.5px
  classDef secret fill:#ef4444,stroke:#7f1d1d,color:#ffffff,stroke-width:1.5px
  classDef util fill:#06b6d4,stroke:#155e75,color:#0b1220,stroke-width:1.5px
  classDef config fill:#a855f7,stroke:#5b21b6,color:#ffffff,stroke-width:1.5px
  classDef storage fill:#94a3b8,stroke:#475569,color:#0b1220,stroke-width:1.5px
  classDef step fill:#10b981,stroke:#064e3b,color:#0b1220,stroke-width:1px
```
