# yassenshopov/pokemonpalette-nextjs architecture

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

- Interactive diagram: https://gitdiagram.com/yassenshopov/pokemonpalette-nextjs
- Repository: https://github.com/yassenshopov/pokemonpalette-nextjs

## Overview

##### File Structure Analysis
- **`app/`**: Next.js entry point. Contains server-rendered pages, layouts, dynamic routes (`[pokemon]`, `app/api` for serverless functions).
- **`components/`**: Reusable React UI in subfolders (`ui/` for primitives, `landing/`, `blog/`, etc.).
- **`contexts/`**: React Context providers for theme, likes, saves.
- **`lib/`**: Utility functions, hooks, mock-db and API wrappers (e.g., `pokemon-service.ts`).
- **`data/`**: Static JSON, mock data, resource lists.
- **`public/`**: Static assets (images, offline page, manifest, service worker).
- **`scripts/`**: Node scripts to download Pokémon images.
- Config files: `next.config.js`, `tailwind.config.ts`, lint/build configs.

##### Key Architectural Insights from the README
- Next.js handles both client and server rendering.
- Uses PokeAPI as external data source.
- Deployed on Vercel (serverless functions for API routes).

##### Main Components and Their Interactions
a. **Client Browser** (User’s device)
– Issues HTTP(S) requests, holds React application, interacts with UI components and Contexts.
– Fetches prerendered pages or CSR bundles from the CDN.
b. **Next.js Frontend (App Layer)**
– Renders pages (SSG, SSR, or CSR).
– Uses layouts and components under `app/` and `components/`.
– Manages global state via `providers.tsx`.
c. **API Routes (Serverless Functions)**
– `app/api/ai-info/*` and `app/api/designs/*`, `app/api/supporters` handle dynamic data operations (likes, fetch AI info, supporters).
– Each route runs as a Vercel Function.
d. **External Services**
– PokeAPI (live Pokémon data).
– Google Analytics.
e. **Data Storage**
– For prototyping, uses in-memory/mock DB (`lib/mock-db`).
– LocalStorage or IndexedDB for saved palettes (client side).
f. **Static Assets CDN**
– Serves images under `public/images/` and static files (`robots.txt`, `sw.js`, etc.).

##### Architectural Patterns & Design Principles
- Component-based UI with a clear separation of “primitive” (`components/ui/`) vs. domain-specific components.
- Serverless micro-endpoints for discrete API needs.
- Context API for global state (theme, likes, saves).
- Static generation (SSG) for pages where possible (e.g., blog, Pokemon pages), dynamic SSR for others (e.g., user-specific data).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Browser
    subgraph "Client Browser"
        Browser["Browser (User)"]:::frontend
        Analytics["Google Analytics"]:::external
    end
    Browser -->|Requests Pages| NextApp
    Browser -.->|Sends Events| Analytics

    %% Next.js Frontend
    subgraph "Next.js Frontend"
        NextApp["Next.js App"]:::frontend
        subgraph "Entry & Layouts"
            Entry["app/page.tsx"]:::frontend
            Layout["app/layout.tsx"]:::frontend
            Providers["app/providers.tsx"]:::frontend
        end
        subgraph "Rendering"
            PageRender["Page Rendering (SSG/SSR)"]:::frontend
            ClientReact["Client-side React + Contexts"]:::frontend
        end
    end
    NextApp --> Entry
    NextApp --> Layout
    NextApp --> Providers
    NextApp --> PageRender
    NextApp --> ClientReact

    %% Internal Pages
    subgraph "Internal Pages"
        Blog["Blog List"]:::frontend
        BlogDetail["Blog Detail"]:::frontend
        BlogLayout["Blog Layout"]:::frontend
        Explore["Explore Designs"]:::frontend
        ExploreDetail["Design Detail"]:::frontend
        FAQ["FAQ"]:::frontend
        Saved["Saved Palettes"]:::frontend
        Settings["Settings"]:::frontend
        Profile["Profile"]:::frontend
        Users["User Profile"]:::frontend
        Showcase["Showcase"]:::frontend
        Resources["Resources"]:::frontend
        Game["Game Demo"]:::frontend
    end
    Entry --> Blog
    Entry --> Explore
    Entry --> FAQ
    Entry --> Saved
    Entry --> Settings
    Entry --> Profile
    Entry --> Showcase
    Entry --> Resources
    Entry --> Game
    Blog --> BlogDetail
    BlogDetail --> BlogLayout

    %% Dynamic Pokemon Page
    subgraph "Dynamic Pages"
        PokemonPage["app/[pokemon]/page.tsx"]:::frontend
        PokemonMeta["app/[pokemon]/metadata.tsx"]:::frontend
        PokemonOG["app/[pokemon]/opengraph-image.tsx"]:::frontend
    end
    Entry --> PokemonPage
    PokemonPage --> PokemonMeta
    PokemonPage --> PokemonOG

    %% API Layer (Serverless Functions)
    subgraph "API Routes"
        AIInfo["AI Info Routes"]:::api
        AIInfoDetail["AI Info Pokémon"]:::api
        Designs["Designs"]:::api
        DesignsLike["Design Like"]:::api
        Supporters["Supporters"]:::api
    end
    ClientReact -->|Fetches| AIInfo
    ClientReact -->|Fetches| Designs
    ClientReact -->|Fetches| Supporters
    AIInfo --> AIInfoDetail
    Designs --> DesignsLike

    %% Data Layer
    subgraph "Data Layer"
        MockDB["Mock DB (in-memory)"]:::datastore
        FutureDB["Persistent DB (placeholder)"]:::datastore
        LocalStorage["LocalStorage/IndexedDB"]:::datastore
    end
    AIInfoDetail --> MockDB
    DesignsLike --> MockDB
    ClientReact --> LocalStorage

    %% External Services
    subgraph "External Services"
        PokeAPI["PokeAPI"]:::external
    end
    NextApp -->|Server-side Fetch| PokeAPI
    APIInfoDetail -->|Server Fetch| PokeAPI

    %% CDN / Public Assets
    subgraph "CDN / Public Assets"
        PublicAssets["public/**"]:::cdn
    end
    Browser -->|Fetches| PublicAssets
    NextApp -->|Deploy on Vercel| PublicAssets

    %% Contexts
    subgraph "Global Providers & Contexts"
        ColorCtx["contexts/color-context.tsx"]:::utility
        LikesCtx["contexts/likes-context.tsx"]:::utility
        SaveCtx["contexts/save-context.tsx"]:::utility
    end
    Providers --> ColorCtx
    Providers --> LikesCtx
    Providers --> SaveCtx

    %% Utilities & Libraries
    subgraph "Utilities & Hooks"
        PokemonService["lib/pokemon-service.ts"]:::utility
        MockDBLib["lib/mock-db/designs.ts"]:::utility
        ColorUtils["lib/color-utils.ts"]:::utility
        Tokens["lib/design-tokens.ts"]:::utility
        Hooks["lib/hooks"]:::utility
        Logger["lib/logger.ts"]:::utility
        Utils["lib/utils.ts"]:::utility
    end
    NextApp --> PokemonService
    MockDB --> MockDBLib
    ClientReact --> ColorUtils
    ClientReact --> Hooks
    ClientReact --> Logger
    ClientReact --> Utils

    %% Static Data & Scripts
    subgraph "Static Data & Scripts"
        Species["data/species.json"]:::data
        MockData["data/mockData.ts"]:::data
        ResourcesData["data/resources.ts"]:::data
        ScriptsAll["scripts/download-all-pokemon-images.js"]:::script
        ScriptSingle["scripts/download-pokemon-images.js"]:::script
    end
    PokemonService --> Species
    PokemonService --> MockData
    ScriptSingle --> PublicAssets
    ScriptsAll --> PublicAssets

    %% Click Events
    click Entry "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/app/page.tsx"
    click Layout "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/app/layout.tsx"
    click Providers "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/app/providers.tsx"
    click Blog "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/app/(internal)/blog/page.tsx"
    click BlogDetail "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/app/(internal)/blog/[...]/page.tsx"
    click BlogLayout "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/app/(internal)/blog/layout.tsx"
    click Explore "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/app/(internal)/explore/page.tsx"
    click ExploreDetail "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/app/(internal)/explore/[designId]/page.tsx"
    click FAQ "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/app/(internal)/faq/page.tsx"
    click Saved "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/app/(internal)/saved/page.tsx"
    click Settings "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/app/(internal)/settings/[[...rest]]/page.tsx"
    click Profile "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/app/(internal)/profile/page.tsx"
    click Users "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/app/(internal)/users/[userId]/page.tsx"
    click Showcase "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/app/(internal)/showcase/page.tsx"
    click Resources "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/app/(internal)/resources/page.tsx"
    click Game "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/app/(internal)/game/page.tsx"
    click PokemonPage "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/app/[pokemon]/page.tsx"
    click PokemonMeta "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/app/[pokemon]/metadata.tsx"
    click PokemonOG "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/app/[pokemon]/opengraph-image.tsx"
    click AIInfo "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/app/api/ai-info/route.ts"
    click AIInfoDetail "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/app/api/ai-info/pokemon/route.ts"
    click Designs "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/app/api/designs/route.ts"
    click DesignsLike "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/app/api/designs/[id]/like/route.ts"
    click Supporters "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/app/api/supporters/route.ts"
    click ColorCtx "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/contexts/color-context.tsx"
    click LikesCtx "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/contexts/likes-context.tsx"
    click SaveCtx "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/contexts/save-context.tsx"
    click PokemonService "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/lib/pokemon-service.ts"
    click MockDBLib "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/lib/mock-db/designs.ts"
    click ColorUtils "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/lib/color-utils.ts"
    click Tokens "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/lib/design-tokens.ts"
    click Hooks "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/lib/hooks/use-loading.ts"
    click Logger "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/lib/logger.ts"
    click Utils "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/lib/utils.ts"
    click Species "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/data/species.json"
    click MockData "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/data/mockData.ts"
    click ResourcesData "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/data/resources.ts"
    click ScriptsAll "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/scripts/download-all-pokemon-images.js"
    click ScriptSingle "https://github.com/yassenshopov/pokemonpalette-nextjs/blob/main/scripts/download-pokemon-images.js"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#000
    classDef api fill:#DFF7D6,stroke:#1F8A70,color:#000
    classDef datastore fill:#FFE8A1,stroke:#D3993E,color:#000
    classDef external fill:#E2E2E2,stroke:#8A8A8A,color:#000
    classDef cdn fill:#F0F0F0,stroke:#A0A0A0,color:#000
    classDef utility fill:#FDE2E2,stroke:#D1495B,color:#000
    classDef data fill:#FFF5E6,stroke:#D98E04,color:#000
    classDef script fill:#E9E9FF,stroke:#6B5B95,color:#000
```
