# terristwj/portfolio architecture

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

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

## Overview

##### Project type and purpose
- This is a full-stack, serverless portfolio website built with Next.js (App Router).
- It delivers predominantly static content (homepage, projects pages) plus a dynamic Guestbook feature backed by a cloud database (Vercel Postgres) and an AI-powered filter (OpenAI API).

##### File structure
- Top-level directories:
- app/ – Next.js “app” folder containing UI pages, layouts, components and edge API routes.
- data/ – Static JSON (guestbook entries in development, project metadata).
- public/ – Static assets (project images).
- API routes under app/api/guestbook:
- guest and admin sub-folders each with MessageActions.ts (DB logic) and route.ts (HTTP handlers).
- Configuration and build scripts: next.config.js, tailwind.config.ts, postcss.config.js, tsconfig.json, package.json.

##### README for additional insights
- Confirms use of Next.js, TailwindCSS, Framer Motion, Vercel hosting & analytics, Vercel Postgres, OpenAI API.
- Describes environment variables (.env) for Postgres and OpenAI credentials.
- References @vercel/postgres client usage in API routes.

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Client Layer
  subgraph "Client (Browser)" 
    direction TB
    Browser["Browser / React UI"]:::frontend
    HomepagePage["Homepage Page"]:::frontend
    ProjectsPage["Projects Page"]:::frontend
    GuestbookPage["Guestbook Page"]:::frontend
    AdminPage["Guestbook Admin Page"]:::frontend

    Browser -->|navigates to| HomepagePage
    Browser -->|navigates to| ProjectsPage
    Browser -->|navigates to| GuestbookPage
    Browser -->|navigates to| AdminPage

    subgraph "Homepage Components"
      direction TB
      Hero["Hero"]:::frontend
      FadingText["FadingText"]:::frontend
      KeywordText["KeywordText"]:::frontend
    end
    HomepagePage --> Hero
    HomepagePage --> FadingText
    HomepagePage --> KeywordText

    subgraph "Projects Components"
      direction TB
      ProjectCard["ProjectCard"]:::frontend
      ProjectActions["ProjectActions"]:::frontend
      AnimatedTabs["AnimatedTabs"]:::frontend
      ParallaxText["ParallaxText"]:::frontend
    end
    ProjectsPage --> ProjectCard
    ProjectsPage --> ProjectActions
    ProjectsPage --> AnimatedTabs
    ProjectsPage --> ParallaxText

    subgraph "Guestbook Components"
      direction TB
      Form["Form"]:::frontend
      Cookies["Cookies"]:::frontend
      FormButton["FormButton"]:::frontend
      FormContent["FormContent"]:::frontend
      HandleFormData["HandleFormData"]:::frontend
      ReactIcons["ReactIcons"]:::frontend
      ResultEntry["ResultEntry"]:::frontend
      ResultEntries["ResultEntries"]:::frontend
      MessageInterface["MessageInterface"]:::frontend
      ConstantsGB["Constants"]:::frontend
    end
    GuestbookPage --> Form
    GuestbookPage --> Cookies
    GuestbookPage --> FormButton
    GuestbookPage --> FormContent
    GuestbookPage --> HandleFormData
    GuestbookPage --> ReactIcons
    GuestbookPage --> ResultEntry
    GuestbookPage --> ResultEntries
    GuestbookPage --> MessageInterface
    GuestbookPage --> ConstantsGB

    AdminPage --> Form
    AdminPage --> Cookies
    AdminPage --> FormButton
    AdminPage --> FormContent
    AdminPage --> HandleFormData
    AdminPage --> ReactIcons
    AdminPage --> ResultEntry
    AdminPage --> ResultEntries
    AdminPage --> MessageInterface
    AdminPage --> ConstantsGB
  end

  %% Server Layer
  subgraph "Next.js App Router on Vercel"
    direction TB

    subgraph "Page Router (SSR/SSG)" 
      direction TB
      PageServer["Next.js Page Server"]:::backend
    end

    subgraph "API Router (Serverless Functions)"
      direction TB
      GBGuestRoute["Guest HTTP Handler"]:::backend
      GBGuestActions["Guest MessageActions"]:::backend
      GBAdminRoute["Admin HTTP Handler"]:::backend
      GBAdminActions["Admin MessageActions"]:::backend
      OpenAIUtil["OpenAI API Utility"]:::external
      MessageDB["Postgres Client Setup"]:::backend
      GBConstants["API Constants"]:::backend
    end

    HomepagePage -->|SSG build-time uses| ProjectsData["Static JSON (projects)"]:::data
    ProjectsData --> PageServer
    PageServer -->|serves HTML/CSS/JS| Browser

    GuestbookPage -->|SSR| PageServer
    AdminPage -->|SSR| PageServer

    GuestbookPage -->|POST/GET| GBGuestRoute
    GBGuestRoute -->|uses| GBGuestActions
    GBGuestActions -->|filters via| OpenAIUtil
    GBGuestActions -->|writes/reads| MessageDB

    GuestbookPage -->|POST/GET| GBAdminRoute
    GBAdminRoute -->|uses| GBAdminActions
    GBAdminActions -->|filters via| OpenAIUtil
    GBAdminActions -->|writes/reads| MessageDB
  end

  %% Database Layer
  MessageDB -->|connects to| PostgresDB["Vercel Postgres"]:::storage

  %% External Services
  OpenAIUtil -->|HTTP call| OpenAI["OpenAI API"]:::external
  GBGuestActions -->|calls| Lorem["Lorem Picsum"]:::external
  GBGuestActions -->|calls| Animal["random-animal-name"]:::external

  %% Static Data
  subgraph "Static Data"
    direction TB
    ProjectsJSON["data/projects/*.json"]:::data
    GuestMock["data/guestbook/messages.json"]:::data
    PublicAssets["public/projects/"]:::storage
  end
  ProjectsJSON -->|build-time| PageServer
  GuestMock -->|dev-mode| GBGuestRoute
  PublicAssets -->|CDN| Browser

  %% Click Events
  click HomepagePage "https://github.com/terristwj/portfolio/blob/main/app/page.tsx"
  click Hero "https://github.com/terristwj/portfolio/blob/main/app/components/Homepage/Hero.tsx"
  click FadingText "https://github.com/terristwj/portfolio/blob/main/app/components/Common/FadingText.tsx"
  click KeywordText "https://github.com/terristwj/portfolio/blob/main/app/components/Common/KeywordText.tsx"
  click ProjectsPage "https://github.com/terristwj/portfolio/blob/main/app/projects/page.tsx"
  click ProjectCard "https://github.com/terristwj/portfolio/blob/main/app/projects/components/ProjectCard.tsx"
  click ProjectActions "https://github.com/terristwj/portfolio/blob/main/app/projects/components/ProjectActions.tsx"
  click AnimatedTabs "https://github.com/terristwj/portfolio/blob/main/app/projects/components/AnimatedTabs.tsx"
  click ParallaxText "https://github.com/terristwj/portfolio/blob/main/app/projects/components/ParallaxText.tsx"
  click ProjectsJSON "https://github.com/terristwj/portfolio/blob/main/data/projects/projects.json"
  click CertificatesJSON "https://github.com/terristwj/portfolio/blob/main/data/projects/certificates.json"
  click PublicAssets "https://github.com/terristwj/portfolio/tree/main/public/projects/"
  click GuestbookPage "https://github.com/terristwj/portfolio/blob/main/app/guestbook/page.tsx"
  click Form "https://github.com/terristwj/portfolio/blob/main/app/guestbook/components/Form/Form.tsx"
  click Cookies "https://github.com/terristwj/portfolio/blob/main/app/guestbook/components/Cookies.tsx"
  click FormButton "https://github.com/terristwj/portfolio/blob/main/app/guestbook/components/FormButton.tsx"
  click FormContent "https://github.com/terristwj/portfolio/blob/main/app/guestbook/components/FormContent.tsx"
  click HandleFormData "https://github.com/terristwj/portfolio/blob/main/app/guestbook/components/HandleFormData.tsx"
  click ReactIcons "https://github.com/terristwj/portfolio/blob/main/app/guestbook/components/ReactIcons.tsx"
  click ResultEntry "https://github.com/terristwj/portfolio/blob/main/app/guestbook/components/ResultEntry.tsx"
  click ResultEntries "https://github.com/terristwj/portfolio/blob/main/app/guestbook/components/ResultEntries.tsx"
  click MessageInterface "https://github.com/terristwj/portfolio/blob/main/app/guestbook/components/MessageInterface.tsx"
  click ConstantsGB "https://github.com/terristwj/portfolio/blob/main/app/guestbook/constants.tsx"
  click AdminPage "https://github.com/terristwj/portfolio/blob/main/app/guestbook/secret/page.tsx"
  click GBGuestRoute "https://github.com/terristwj/portfolio/blob/main/app/api/guestbook/guest/route.ts"
  click GBGuestActions "https://github.com/terristwj/portfolio/blob/main/app/api/guestbook/guest/MessageActions.ts"
  click GBAdminRoute "https://github.com/terristwj/portfolio/blob/main/app/api/guestbook/admin/route.ts"
  click GBAdminActions "https://github.com/terristwj/portfolio/blob/main/app/api/guestbook/admin/MessageActions.ts"
  click MessageDB "https://github.com/terristwj/portfolio/blob/main/app/api/guestbook/MessageDB.ts"
  click GBConstants "https://github.com/terristwj/portfolio/blob/main/app/api/guestbook/constants.ts"
  click OpenAIUtil "https://github.com/terristwj/portfolio/blob/main/app/api/openAI.ts"
  click GuestMock "https://github.com/terristwj/portfolio/blob/main/data/guestbook/messages.json"
  click ProjectsJSON "https://github.com/terristwj/portfolio/blob/main/data/projects/projects.json"
  click CertificatesJSON "https://github.com/terristwj/portfolio/blob/main/data/projects/certificates.json"

  %% Styles
  classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
  classDef backend fill:#DFFFE0,stroke:#2E8B57,color:#2E8B57;
  classDef external fill:#FFEFD5,stroke:#FF8C00,color:#FF8C00;
  classDef storage fill:#FFE0E0,stroke:#DC143C,color:#DC143C;
  classDef data fill:#FFF5BA,stroke:#DAA520,color:#DAA520;
```
