# charles5991/jikan-web architecture

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

- Interactive diagram: https://gitdiagram.com/charles5991/jikan-web
- Repository: https://github.com/charles5991/jikan-web

## Overview

##### Project type and purpose
- This is a front-end only single-page application (SPA) starter template built with React, TypeScript and Vite.
- It provides a boilerplate project with standardized folder structure, coding conventions (ESLint/Prettier), pre-commit hooks (Husky), TailwindCSS + shadcn/ui components, Vite plugins (SVG handling, auto-import, fonts), Docker support and Vercel deployment configuration.

##### File structure
- Top-level infra/config folders and files
- `.github/` – Dependabot config
- `Dockerfile`, `docker-compose.yml` – container build/runtime
- `.husky/`, `lintstagedrc.json` – pre-commit linting & formatting
- `eslint.config.js`, `.prettierrc.json`, `tsconfig.json` – dev tool configs
- `vercel.json` – hosting deployment
- Public & static assets
- `public/manifest.webmanifest`, `index.html`, `src/assets`
- Source code under `src/`
- `main.tsx` → app entrypoint & Vite HMR server
- `App.tsx` → root component + router setup
- `page/` → route-level pages (Home, AnimeDetails, NotFound)
- `components/` → shared UI building blocks (buttons, cards, inputs)
- `store/`, `hooks/`, `data/`, `utils/` → state management, custom hooks, API clients, helpers
- `constants/`, `types/`, `configs/` → typing, theme and plugin configs

##### README for additional insights
- Confirms tech stack: React, TypeScript, Vite, Tailwind/shadcn-ui
- Highlights included plugins: vite-plugin-svgr, unplugin-fonts, unplugin-auto-import
- Suggests using Vercel (via `vercel.json`) for production SSR (though this template is client-only)

##### Detail is king
- Every folder or plugin that plays a role in build or runtime.
- Type generation and custom import aliases (`@/components`) in the config.
- Don’t overthink: break the project into infra/config, source code layers, runtime platform, and external services.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Development & Deployment Pipeline
    subgraph "Development & Deployment" 
        direction TB
        DevWorkstation[/"Developer Workstation<br/>(IDE + Git)"/]:::hexagon
        GitHub["GitHub Repository"]:::repo
        DevTools["Husky + lint-staged<br/>ESLint + Prettier"]:::hexagon
        CICD["CI/CD<br/>(GitHub Actions / Vercel)"]:::process
        DockerRegistry[(Docker Registry)]:::database
        Vercel[("Vercel Hosting")]:::cloud
    end

    DevWorkstation -->|push code / pull requests| GitHub
    GitHub -->|pre-commit hooks| DevTools
    GitHub -->|triggers build & test| CICD
    CICD -->|build Docker image| DockerRegistry
    CICD -->|deploy static assets| Vercel

    %% Runtime Architecture
    subgraph "Runtime Architecture"
        direction TB
        subgraph "Local Development"
            ViteServer["Vite Dev Server"]:::process
        end
        subgraph "Production"
            StaticServer["Static File Server<br/>(Docker Container or Vercel)"]:::process
        end
        BrowserClient[/"Browser Client"/]:::browser
    end

    ViteServer -->|serves modules & HMR| BrowserClient
    StaticServer -->|serves built assets| BrowserClient

    CICD -->|push to registry| DockerRegistry
    DockerRegistry --> StaticServer
    Vercel --> StaticServer

    %% Browser Internal Structure
    subgraph "Browser Client"
        direction TB
        Entry["Entry Point<br/>(main.tsx)"]:::module
        AppComp["App.tsx<br/>Root Component & Router"]:::module

        subgraph "Router & Pages"
            direction TB
            HomePage["Home Page"]:::page
            AnimePage["AnimeDetails Page"]:::page
            NotFoundPage["NotFound Page"]:::page
            ErrorBoundary["RootErrorBoundary"]:::page
        end

        subgraph "UI Components<br/>(src/components/ui)"
            direction TB
            Button["Button"]:::component
            Input["Input"]:::component
            SearchInput["SearchInput"]:::component
            Pagination["Pagination"]:::component
            AnimeCard["AnimeCard"]:::component
            Footer["Footer"]:::component
            Skeleton["Skeleton"]:::component
        end

        subgraph "Data & State"
            direction TB
            Store["State Store"]:::module
            DataIndex["data/index.ts"]:::module
            APIClient["api.ts<br/>(utils/api)"]:::module
            Hooks["Custom Hooks"]:::module
            Debounce["debounce.ts"]:::module
            CNHelper["cn.ts"]:::module
            MiscUtils["utils/index.ts<br/>helpers/demo.ts"]:::module
        end

        subgraph "Configs & Types"
            direction TB
            Types["TypeScript Types"]:::module
            Constants["Runtime Constants"]:::module
            ProjectConfigs["Project Configs"]:::module
        end

        Entry --> AppComp
        AppComp --> HomePage
        AppComp --> AnimePage
        AppComp --> NotFoundPage
        AppComp --> ErrorBoundary

        AppComp --> Button
        AppComp --> Input
        AppComp --> SearchInput
        AppComp --> Pagination
        AppComp --> AnimeCard
        AppComp --> Footer
        AppComp --> Skeleton

        HomePage --> APIClient
        AnimePage --> APIClient
        APIClient -->|fetch data| AnimeAPI
        APIClient -->|fetch fonts| GoogleFonts

        APIClient --> Store
        APIClient --> DataIndex
        APIClient --> Hooks
        Hooks --> Debounce
        Hooks --> CNHelper
        Hooks --> MiscUtils

        AppComp --> Types
        AppComp --> Constants
        AppComp --> ProjectConfigs
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GoogleFonts[(Google Fonts CDN)]:::cloud
        AnimeAPI[(3rd-Party Anime API)]:::cloud
    end

    BrowserClient -->|fetch resources| GoogleFonts
    BrowserClient -->|fetch data| AnimeAPI

    %% Click Events
    click Entry "https://github.com/charles5991/jikan-web/blob/main/src/main.tsx"
    click AppComp "https://github.com/charles5991/jikan-web/blob/main/src/App.tsx"
    click HomePage "https://github.com/charles5991/jikan-web/blob/main/src/page/Home.tsx"
    click AnimePage "https://github.com/charles5991/jikan-web/blob/main/src/page/AnimeDetails.tsx"
    click NotFoundPage "https://github.com/charles5991/jikan-web/blob/main/src/page/NotFound.tsx"
    click ErrorBoundary "https://github.com/charles5991/jikan-web/blob/main/src/page/RootErrorBoundary.tsx"
    click Button "https://github.com/charles5991/jikan-web/blob/main/src/components/ui/button.tsx"
    click Input "https://github.com/charles5991/jikan-web/blob/main/src/components/ui/input.tsx"
    click SearchInput "https://github.com/charles5991/jikan-web/blob/main/src/components/ui/search-input.tsx"
    click Pagination "https://github.com/charles5991/jikan-web/blob/main/src/components/ui/pagination.tsx"
    click AnimeCard "https://github.com/charles5991/jikan-web/blob/main/src/components/ui/anime-card.tsx"
    click Footer "https://github.com/charles5991/jikan-web/blob/main/src/components/ui/footer.tsx"
    click Skeleton "https://github.com/charles5991/jikan-web/blob/main/src/components/ui/skeleton.tsx"
    click Store "https://github.com/charles5991/jikan-web/blob/main/src/store/index.ts"
    click DataIndex "https://github.com/charles5991/jikan-web/blob/main/src/data/index.ts"
    click APIClient "https://github.com/charles5991/jikan-web/blob/main/src/utils/api.ts"
    click Hooks "https://github.com/charles5991/jikan-web/blob/main/src/hooks/index.ts"
    click Debounce "https://github.com/charles5991/jikan-web/blob/main/src/utils/debounce.ts"
    click CNHelper "https://github.com/charles5991/jikan-web/blob/main/src/utils/cn.ts"
    click MiscUtils "https://github.com/charles5991/jikan-web/blob/main/src/utils/index.ts"
    click Types "https://github.com/charles5991/jikan-web/blob/main/src/types/index.ts"
    click Constants "https://github.com/charles5991/jikan-web/blob/main/src/constants/index.ts"
    click ProjectConfigs "https://github.com/charles5991/jikan-web/blob/main/configs/index.ts"
    click DevTools "https://github.com/charles5991/jikan-web/blob/main/eslint.config.js"
    click DevTools "https://github.com/charles5991/jikan-web/blob/main/.prettierrc.json"
    click DevTools "https://github.com/charles5991/jikan-web/blob/main/tsconfig.json"
    click DevTools "https://github.com/charles5991/jikan-web/blob/main/tsconfig.node.json"
    click DevTools "https://github.com/charles5991/jikan-web/tree/main/.husky/pre-commit"
    click DevTools "https://github.com/charles5991/jikan-web/blob/main/.lintstagedrc.json"
    click DevTools "https://github.com/charles5991/jikan-web/blob/main/vite.config.ts"
    click DevTools "https://github.com/charles5991/jikan-web/tree/main/Dockerfile"
    click DevTools "https://github.com/charles5991/jikan-web/blob/main/docker-compose.yml"
    click DevTools "https://github.com/charles5991/jikan-web/blob/main/vercel.json"
    click DevTools "https://github.com/charles5991/jikan-web/blob/main/.github/dependabot.yml"

    %% Styles
    classDef hexagon fill:#f9f,stroke:#333,stroke-width:1px;
    classDef repo fill:#bbf,stroke:#333,stroke-width:1px;
    classDef process fill:#bfb,stroke:#333,stroke-width:1px;
    classDef database fill:#ffb,stroke:#333,stroke-width:1px;
    classDef cloud fill:#fbf,stroke:#333,stroke-width:1px;
    classDef browser fill:#aff,stroke:#333,stroke-width:1px;
    classDef module fill:#fea,stroke:#333,stroke-width:1px;
    classDef page fill:#aef,stroke:#333,stroke-width:1px;
    classDef component fill:#eaf,stroke:#333,stroke-width:1px;
```
