# once-ui-system/magic-portfolio architecture

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

- Interactive diagram: https://gitdiagram.com/once-ui-system/magic-portfolio
- Repository: https://github.com/once-ui-system/magic-portfolio

## Overview

##### Project type and purpose
- This is a full-stack, Next.js-based portfolio/CMS-style application that uses SSG/SSR along with dynamic API routes for lightweight serverless behavior.
- It ships a custom UI library (Once UI) alongside client pages, MDX-driven content (blog & projects), API routes (authentication, OG generation, sitemap), and static assets.

##### File structure
- Top-level “public/” holds static assets (fonts, images, videos).
- “src/app/” is the Next.js App Router: pages, layouts, API routes under api/authenticate, api/check-auth, api/og, plus next-generated sitemap and robots.
- “src/components/” contains reusable UI bits.
- “src/once-ui/” is the embedded component library (tokens, styles, hooks, components).
- “src/app/resources/” holds runtime configuration and content manifests.
- MDX posts live under “src/app/blog/posts” and “src/app/work/projects.”
- Config files: next.config.mjs, tsconfig.json, ESLint, PostCSS, package.json.

##### Key insights from the README
- Built with Next.js & Once UI, targeting Vercel.
- Features: automatic SEO (open-graph via next/og, metadata/schema), conditional page rendering (content-driven), password-protected routes, localization support (next-intl branch).
- MDX used for rich content; dynamic asset import.

##### Main components & interactions (to represent
a. Client (Browser)
– Requests HTML/CSS/JS.
– Runs React app, toggles theme, navigates between pages.
b. CDN / Static Asset Layer
– Serves files in “public/” (images, fonts, videos).
– Delivers built JS/CSS bundles.
c. Next.js Serverless Functions (on Vercel)
– SSG at build time: reads MDX files → generates static pages (blog, projects).
– SSR/API at runtime:
- /api/authenticate (password protection)
- /api/check-auth (verify session)
- /app/og route (dynamic OG image generation)
- /sitemap.xml and /robots.txt generation
– Data layer: imports from src/app/resources/config.js & content.js.
d. MDX Content Store
– Local files under blog/posts & work/projects.
– Parsed via next-mdx (build & hydration).
e. Once UI Component Library
– Shared tokens, styles, hooks, and components consumed by pages & src/components.
– Treat as an internal package module.
f. External Services
– Mailchimp (via Mailchimp.tsx) for newsletter sign-up.
– Vercel (hosting & deployment).
– (Potential) Analytics/CDN logging.

- Browser → CDN/static (GET bundles & assets)
- Browser → Next.js server (initial SSR or on-demand API calls)
- Next.js build process → MDX content → static page generation
- API routes ↔ Browser (auth, OG image fetch)
- Once UI library → consumed by pages & components

##### Architectural patterns & design principles
- Jamstack / hybrid SSG+SSR (Next.js App Router)
- Content-driven rendering (MDX + config)
- Design system integration (Once UI as a mono-repo component layer)
- API-first lightweight serverless endpoints for auth & dynamic assets
- Separation of concerns:
– Presentation (React + Once UI)
– Content (MDX)
– Config (JS modules)
– Serverless logic (API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (Browser)" 
        B["Browser"]:::client
    end

    %% CDN / Static Asset Layer
    subgraph "CDN / Static Asset Layer"
        CDN["Static Assets & Bundles"]:::cdn
    end

    %% Next.js Build & Runtime Layer
    subgraph "Next.js Build & Runtime" 
        subgraph "Build Time (SSG)" 
            MDXStore["MDX Content Store"]:::data
            SSG["SSG Process"]:::server
        end
        subgraph "Runtime"
            NextRuntime["Next.js Serverless Runtime"]:::server
            subgraph "API Routes"
                Auth["/api/authenticate"]:::api
                Check["/api/check-auth"]:::api
                OG["/app/og (OG Image)"]:::api
                Sitemap["/sitemap.xml"]:::api
                Robots["/robots.txt"]:::api
            end
        end
    end

    %% Data / Config Store
    subgraph "Data / Config Store"
        Config["Config & Content Manifests"]:::data
    end

    %% Internal Libraries & Components
    subgraph "Internal Libraries & Components"
        Components["Reusable UI Components"]:::app
        OnceUI["Once UI Component Library"]:::lib
        MDXHelpers["MDX Rendering Helpers"]:::app
        Utils["Utility Functions"]:::app
    end

    %% External Services
    subgraph "External Services"
        Mailchimp["Mailchimp"]:::external
        Vercel["Vercel Hosting"]:::external
    end

    %% Connections
    B -->|"GET Bundles & Assets"| CDN
    B -->|"Initial SSR or Client Nav"| NextRuntime
    NextRuntime -->|"reads MDX at build"| MDXStore
    SSG -->|"generate static pages"| CDN
    NextRuntime -->|"uses Config & Manifests"| Config
    NextRuntime -->|"serves static files"| CDN
    B -->|"POST /api/authenticate"| Auth
    B -->|"GET /api/check-auth"| Check
    B -->|"GET /app/og"| OG
    B -->|"GET /sitemap.xml"| Sitemap
    B -->|"GET /robots.txt"| Robots
    NextRuntime -->|"consumes UI components"| Components
    NextRuntime -->|"consumes Once UI library"| OnceUI
    Components -->|"internal dep on"| OnceUI
    MDXHelpers -->|"wrap MDX content"| SSG
    NextRuntime -->|"wrap MDX at runtime"| MDXHelpers
    NextRuntime -->|"uses utils"| Utils
    SSG -->|"read MDX content"| MDXStore
    B -->|"newsletter sign-up"| Mailchimp
    Vercel -->|"hosts runtime & assets"| NextRuntime
    Vercel -->|"hosts CDN layer"| CDN

    %% Click Events
    click B "https://github.com/once-ui-system/magic-portfolio/blob/main/src/app/page.tsx"
    click B "https://github.com/once-ui-system/magic-portfolio/blob/main/src/app/layout.tsx"
    click CDN "https://github.com/once-ui-system/magic-portfolio/tree/main/public/"
    click Auth "https://github.com/once-ui-system/magic-portfolio/blob/main/src/app/api/authenticate/route.ts"
    click Check "https://github.com/once-ui-system/magic-portfolio/blob/main/src/app/api/check-auth/route.ts"
    click OG "https://github.com/once-ui-system/magic-portfolio/blob/main/src/app/og/route.tsx"
    click Sitemap "https://github.com/once-ui-system/magic-portfolio/blob/main/src/app/sitemap.ts"
    click Robots "https://github.com/once-ui-system/magic-portfolio/blob/main/src/app/robots.ts"
    click MDXStore "https://github.com/once-ui-system/magic-portfolio/tree/main/src/app/blog/posts/"
    click MDXStore "https://github.com/once-ui-system/magic-portfolio/tree/main/src/app/work/projects/"
    click Config "https://github.com/once-ui-system/magic-portfolio/blob/main/src/app/resources/config.js"
    click Config "https://github.com/once-ui-system/magic-portfolio/blob/main/src/app/resources/content.js"
    click Config "https://github.com/once-ui-system/magic-portfolio/blob/main/src/app/resources/index.ts"
    click Components "https://github.com/once-ui-system/magic-portfolio/tree/main/src/components/"
    click Components "https://github.com/once-ui-system/magic-portfolio/blob/main/src/components/Mailchimp.tsx"
    click Components "https://github.com/once-ui-system/magic-portfolio/blob/main/src/components/RouteGuard.tsx"
    click Components "https://github.com/once-ui-system/magic-portfolio/blob/main/src/components/ThemeToggle.tsx"
    click Components "https://github.com/once-ui-system/magic-portfolio/blob/main/src/components/Header.tsx"
    click Components "https://github.com/once-ui-system/magic-portfolio/blob/main/src/components/Footer.tsx"
    click OnceUI "https://github.com/once-ui-system/magic-portfolio/tree/main/src/once-ui/components/"
    click OnceUI "https://github.com/once-ui-system/magic-portfolio/blob/main/src/once-ui/hooks/useTheme.ts"
    click OnceUI "https://github.com/once-ui-system/magic-portfolio/blob/main/src/once-ui/hooks/useDebounce.ts"
    click OnceUI "https://github.com/once-ui-system/magic-portfolio/blob/main/src/once-ui/modules/seo/Meta.tsx"
    click OnceUI "https://github.com/once-ui-system/magic-portfolio/blob/main/src/once-ui/modules/seo/Schema.tsx"
    click OnceUI "https://github.com/once-ui-system/magic-portfolio/blob/main/src/once-ui/components/index.ts"
    click OnceUI "https://github.com/once-ui-system/magic-portfolio/blob/main/src/once-ui/modules/index.ts"
    click Utils "https://github.com/once-ui-system/magic-portfolio/blob/main/src/app/utils/formatDate.ts"
    click Utils "https://github.com/once-ui-system/magic-portfolio/blob/main/src/app/utils/utils.ts"
    click MDXHelpers "https://github.com/once-ui-system/magic-portfolio/blob/main/src/components/mdx.tsx"
    click Vercel "https://github.com/once-ui-system/magic-portfolio/blob/main/package.json"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef cdn fill:#FFE5B4,stroke:#E37B09,color:#E37B09;
    classDef server fill:#DFF2D8,stroke:#2E8B57,color:#2E8B57;
    classDef api fill:#C8E6C9,stroke:#388E3C,color:#388E3C;
    classDef data fill:#F0F0F0,stroke:#9E9E9E,color:#424242;
    classDef app fill:#E8EAF6,stroke:#3F51B5,color:#3F51B5;
    classDef lib fill:#FFF0F5,stroke:#C71585,color:#C71585;
    classDef external fill:#F3E5F5,stroke:#8E24AA,color:#8E24AA;
```
