# yukaorange/portfolio-2024 architecture

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

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

## Overview

##### Project Type and Purpose
- This is a portfolio website built for showcasing technical skills during a job search.
- It is built using Next.js with React and TypeScript, and it leverages R3F (React Three Fiber) together with Three.js for interactive WebGL graphics.
- The site integrates with microCMS to fetch content and assets, using static site generation (SSG), and it is deployed on Vercel.
- The project also emphasizes advanced visual effects, shader animations, and interactive UI transitions.

##### Main Components
a. Frontend UI Layer:
- Next.js pages and layouts (located primarily in the app directory: app/page.tsx, app/layout.tsx, etc.)
- Component library (organized under the components directory: Common, Layout, Gallery, About, Top, etc.) which handles modular UI elements, navigation, and interactivity.
- React Context Providers (in the app folder) for managing scroll, transition, and other UI states.
b. WebGL / 3D Graphics Module:
- R3F and Three.js components (found in components/WebGL and associated shader files in the shaders directory).
- Custom shader programs (directory “shaders”) used to animate textures, lighting, and post-process effects.
c. State Management:
- Recoil atoms (organized in the store directory) that manage global state such as loading progress, navigation state, and texture information.
- Custom hooks (in the hooks directory) that help integrate and maintain component state and animations, including viewport calculations and frame rate control.
d. Data Integration Layer:
- Integration with microCMS via the lib/microcms.ts file for fetching content.
- Usage of static generation (SSG) in Next.js to prebuild pages with external data.
e. Asset and Public Resources:
- Resources such as fonts, images, models, and JSON data are stored under the public directory.
- WebGL models (in public/models) and Draco decoder files (in public/draco) are crucial for efficient 3D model loading.
f. Development and Styling:
- Shared styling and configuration files for ESLint, Prettier, styleLint, SCSS mixins, and global styles (in both the root and styles directories).

##### Relationships and Interactions
- The Browser sends requests which are handled by Next.js routes defined in the app directory. The route resolver picks the correct page component which in turn utilizes layout wrappers and reusable components from the components directory.
- Components interact with each other via React props, context providers, and Recoil state management to maintain a reactive and highly interactive UX.
- During page transitions or initial load, the WebGL layer initiates visual effects that drive the dynamic image textures and animations, with shader programs running on the client.
- Data is fetched from microCMS via the lib module and is provided to the pages during the build time (SSG) or runtime.
- The build process makes use of utilities like gltfjsx to convert 3D models into React components (as referenced in the README).
- Deployment is streamlined using Vercel.

##### Architectural Patterns and Design Principles
- Component-Based Design: Clear separation into presentation, container, and utility components.
- File System-Based Routing (Next.js): Organizing pages and sub-pages inside the app directory.
- Separation of Concerns: Distinct folders for UI components, business logic (hooks and state), WebGL rendering, and shader code.
- Declarative State Management: Use of Recoil and Context Providers to minimize unnecessary renders and manage cross-cutting concerns (like scroll and transition states).
- Optimized Asset Delivery: Use of public directories for static assets, and dedicated paths for WebGL and shader assets for optimal performance.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    Browser["Browser Client"]:::external
    Router["Next.js Router (SSG)"]:::external
    Vercel["Vercel Deployment"]:::external

    %% Frontend UI Layer
    subgraph "Frontend UI Layer"
        %% Pages & Layouts Subgraph
        subgraph "Pages & Layouts"
            A1["Home Page (app/page.tsx)"]:::frontend
            A2["Layout (app/layout.tsx)"]:::frontend
            A3["About Page (app/about/page.tsx)"]:::frontend
            A4["Gallery Page (app/gallery/[slug]/page.tsx)"]:::frontend
        end

        %% Component Library Subgraph
        subgraph "Component Library"
            B1["Header (components/Layout/Header/Header.tsx)"]:::frontend
            B2["Footer (components/Layout/Footer/Footer.tsx)"]:::frontend
            B3["About Components (components/About)"]:::frontend
            B4["Gallery Components (components/Gallery)"]:::frontend
            B5["Top Components (components/Top)"]:::frontend
            B6["Common Components (components/Common)"]:::frontend
        end
    end

    %% State Management Layer
    subgraph "State Management"
        %% Recoil Atoms
        subgraph "Recoil State"
            S1a["activeArchiveNumberAtom (store/activeArchiveNumberAtom.ts)"]:::state
            S1b["fpsAtom (store/fpsAtom.ts)"]:::state
            S1c["textureAtom (store/textureAtom.ts)"]:::state
        end
        %% Custom Hooks
        subgraph "Custom Hooks"
            S2a["useComponentLogger (hooks/useComponentLogger.ts)"]:::state
            S2b["useFrameRate (hooks/useFrameRate.ts)"]:::state
            S2c["useViewportCalculator (hooks/useViewportCalculator.ts)"]:::state
        end
    end

    %% WebGL / 3D Graphics Module
    subgraph "WebGL Module"
        %% R3F / Three.js Components
        subgraph "R3F/Three.js"
            W1a["App Component (components/WebGL/App/App.tsx)"]:::webgl
            W1b["Experience Component (components/WebGL/Experience/Experience.tsx)"]:::webgl
        end
        %% Shader Programs
        subgraph "Shader Programs"
            SW1["Character Shader (shaders/character)"]:::webgl
            SW2["Floor Shader (shaders/floor)"]:::webgl
            SW3["Panel Shader (shaders/panel)"]:::webgl
            SW4["Postprocess Shader (shaders/postprocess)"]:::webgl
            SW5["Suitcase Shader (shaders/suitcase)"]:::webgl
            SW6["Utils Shader (shaders/utils)"]:::webgl
        end
    end

    %% Data Integration Layer
    subgraph "Data Integration"
        D1["microCMS Integration (lib/microcms.ts)"]:::data
    end

    %% Asset and Public Resources
    subgraph "Assets & Public Resources"
        PA["Public Assets (public)"]:::asset
    end

    %% Development and Styling
    subgraph "Development & Styling"
        DS1["Config Files (.eslintrc.json, .prettierrc, .stylelintrc.json)"]:::dev
        DS2["Styles (styles)"]:::dev
    end

    %% Relationships & Data Flows
    Browser -->|"sends requests"| Router
    Router -->|"routes to"| A1
    Router --> A2
    Router --> A3
    Router --> A4
    A1 -->|"renders"| B1
    A1 --> B2
    A1 --> B3
    A1 --> B4
    A1 --> B5
    A1 --> B6
    A1 -->|"fetches data from"| D1
    A1 -->|"updates via"| S1a
    A1 -->|"updates via"| S1b
    A1 -->|"updates via"| S1c
    A1 -->|"utilizes"| S2a
    A1 -->|"utilizes"| S2b
    A1 -->|"utilizes"| S2c
    A1 -->|"triggers visual effects in"| W1a
    A1 -->|"triggers visual effects in"| W1b
    W1a -->|"uses shaders from"| SW1
    W1a --> SW2
    W1a --> SW3
    W1a --> SW4
    W1a --> SW5
    W1a --> SW6
    PA -->|"provides assets to"| W1a
    PA -->|"provides assets to"| B3
    Router --> Vercel
    DS1 --- A1
    DS2 --- A1

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef webgl fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef state fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef data fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;
    classDef asset fill:#FDEBD0,stroke:#E67E22,stroke-width:2px;
    classDef dev fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef external fill:#D6EAF8,stroke:#3498DB,stroke-width:2px;

    %% Click Events for Frontend UI Layer
    click A1 "https://github.com/yukaorange/portfolio-2024/blob/main/app/page.tsx"
    click A2 "https://github.com/yukaorange/portfolio-2024/blob/main/app/layout.tsx"
    click A3 "https://github.com/yukaorange/portfolio-2024/blob/main/app/about/page.tsx"
    click A4 "https://github.com/yukaorange/portfolio-2024/blob/main/app/gallery/[slug]/page.tsx"
    click B1 "https://github.com/yukaorange/portfolio-2024/blob/main/components/Layout/Header/Header.tsx"
    click B2 "https://github.com/yukaorange/portfolio-2024/blob/main/components/Layout/Footer/Footer.tsx"
    click B3 "https://github.com/yukaorange/portfolio-2024/tree/main/components/About"
    click B4 "https://github.com/yukaorange/portfolio-2024/tree/main/components/Gallery"
    click B5 "https://github.com/yukaorange/portfolio-2024/tree/main/components/Top"
    click B6 "https://github.com/yukaorange/portfolio-2024/tree/main/components/Common"

    %% Click Events for WebGL / 3D Graphics Module
    click W1a "https://github.com/yukaorange/portfolio-2024/blob/main/components/WebGL/App/App.tsx"
    click W1b "https://github.com/yukaorange/portfolio-2024/blob/main/components/WebGL/Experience/Experience.tsx"
    click SW1 "https://github.com/yukaorange/portfolio-2024/tree/main/shaders/character"
    click SW2 "https://github.com/yukaorange/portfolio-2024/tree/main/shaders/floor"
    click SW3 "https://github.com/yukaorange/portfolio-2024/tree/main/shaders/panel"
    click SW4 "https://github.com/yukaorange/portfolio-2024/tree/main/shaders/postprocess"
    click SW5 "https://github.com/yukaorange/portfolio-2024/tree/main/shaders/suitcase"
    click SW6 "https://github.com/yukaorange/portfolio-2024/tree/main/shaders/utils"

    %% Click Events for State Management
    click S1a "https://github.com/yukaorange/portfolio-2024/blob/main/store/activeArchiveNumberAtom.ts"
    click S1b "https://github.com/yukaorange/portfolio-2024/blob/main/store/fpsAtom.ts"
    click S1c "https://github.com/yukaorange/portfolio-2024/blob/main/store/textureAtom.ts"
    click S2a "https://github.com/yukaorange/portfolio-2024/blob/main/hooks/useComponentLogger.ts"
    click S2b "https://github.com/yukaorange/portfolio-2024/blob/main/hooks/useFrameRate.ts"
    click S2c "https://github.com/yukaorange/portfolio-2024/blob/main/hooks/useViewportCalculator.ts"

    %% Click Event for Data Integration
    click D1 "https://github.com/yukaorange/portfolio-2024/blob/main/lib/microcms.ts"

    %% Click Event for Assets
    click PA "https://github.com/yukaorange/portfolio-2024/tree/main/public"

    %% Click Events for Development and Styling
    click DS1 "https://github.com/yukaorange/portfolio-2024/blob/main/.eslintrc.json"
    click DS2 "https://github.com/yukaorange/portfolio-2024/blob/main/styles/style.scss"
```
