# suneo3476/nanawa architecture

> Architecture diagram of the GitHub repository suneo3476/nanawa, 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/suneo3476/nanawa
- Repository: https://github.com/suneo3476/nanawa

## Overview

##### Project Type and Purpose
- This is a front-end web application built with Next.js, as clearly indicated in the README (“This is a Next.js project bootstrapped with create-next-app”). It leverages the Next.js framework to provide server-side rendering, route-based code splitting, and other modern web development benefits.
- The project also involves local data (text files under the data directory) and some custom scripts (e.g., data migration script in scripts/migrate-data.ts), implying that there is a process for data ingestion, transformation, or archiving.

##### File Structure and Architectural Patterns
- Top-Level Directories/Files:
- src: Contains main application logic. Within src, you have the app folder (which integrates Next.js routing, layout, error handling, and various pages such as heatmap, search, stats, timeline) and components (which are reusable UI fragments like Header, Breadcrumbs, LiveCard, and others).
- public: Stores static assets like the _redirects file.
- data: Contains text files (discography, live history, setlist history, tracks) that likely feed into the application content.
- scripts: Contains migration and possibly other utility scripts indicating that some data pre-processing or transformation might be required.
- Configuration files: next.config, tailwind.config, tsconfig, Jest configuration and ESLint configuration among others, which suggest aspects like styling (via Tailwind CSS) and testing.

- Architectural Patterns and Considerations:
- As a Next.js application, it naturally follows a page-based routing approach, wherein each file inside the app directory represents a route.
- There is clear separation between layout (app/layout.tsx) and page components (e.g., app/page.tsx, app/heatmap/page.tsx), which implies an adherence to Next.js conventions.
- The components directory is organized by feature (e.g., AdvancedSearch, Breadcrumbs) following modular and reusable component practices.
- The presence of data transformation scripts in the scripts directory and raw data files in data suggests an additional layer for data management or pre-rendering content.

a. Main Components:
- Next.js App Layer:
- App Directory: Represent pages for main features such as the heatmap, search, stats, timeline.
- Layout & Error Handling: Show the shared layout (app/layout.tsx) and error fallback pages (e.g., not-found.tsx).
- Components Module:
- Various UI components: Header, Breadcrumbs, Live components (LiveCard, LiveList, LiveTimeline, LiveViewIntegrated), AdvancedSearch, StatsDashboard, etc.
- Data Layer:
- Data Directory: Represent the raw data files (discography.txt, live_history.txt, etc.) which support the front-end display and analytics.
- Scripts: Include the data migration or transformation script (scripts/migrate-data.ts) that prepares data for the application.
- Utility & Helper Functions:
- Utils and Types: The utils folder (with API calls, data converters, song enricher, etc.) and types definitions for ensuring type safety.
- Configuration & Build Tools:
- Config Files: next.config, tailwind.config, Jest and ESLint configurations – these configure project behavior, styling, and testing.

b. Relationships and Interactions:
- The App Layer (pages, layouts, error boundaries) interacts with the Components Module to render UI parts.
- The Utils and API layer sits between the application logic and external data sources, processing data retrieved from the static data files.
- The Data Layer (raw content and scripts) feeds into the app via preprocessing, ensuring that the frontend displays updated information.
- Configuration Files ensure that all these pieces work cohesively from local development to deployment (especially given the deployment hints toward Vercel).

c. Architectural Patterns:
- Follow Next.js’ folder-based routing – indicate that each folder under src/app represents a distinct route.
- Modularity by grouping related UI components together to allow reusability.

##### Elements
- Lifecycle or initialization sequences (e.g., how the application bootstraps with Next.js’s app directory structure).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Configuration & Build Tools"
        CFG1["Next.js Config"]:::config
        CFG2["Tailwind Config"]:::config
        CFG3["PostCSS Config"]:::config
        CFG4["Testing & Linting"]:::config
        CFG5["TypeScript Config"]:::config
    end

    subgraph "Data Layer"
        D1["Discography Data"]:::data
        D2["Live History Data"]:::data
        D3["Setlist History Data"]:::data
        D4["Tracks Data"]:::data
        D5["Data Migration Script"]:::data
    end

    subgraph "Utility & Helper Functions"
        U1["API Calls"]:::utility
        U2["Data Converter"]:::utility
        U3["Song Enricher"]:::utility
        U4["Static Data Loader"]:::utility
    end

    subgraph "UI Components Module"
        C1["Header"]:::component
        C2["Breadcrumbs"]:::component
        C3["Advanced Search"]:::component
        C4["LiveCard"]:::component
        C5["LiveList"]:::component
        C6["LiveTimeline"]:::component
        C7["LiveViewIntegrated"]:::component
        C8["PerformanceHeatmap"]:::component
        C9["SetlistPreview"]:::component
        C10["SetlistView"]:::component
        C11["SongCard"]:::component
        C12["StatsDashboard"]:::component
        C13["Settings"]:::component
    end

    subgraph "Next.js App Layer"
        A1["Main Page"]:::app
        A2["Heatmap Page"]:::app
        A3["Search Page"]:::app
        A4["Stats Page"]:::app
        A5["Timeline Page"]:::app
        L["Global Layout"]:::app
        E1["Not Found Error"]:::app
        E2["Heatmap Error"]:::app
        E3["Search Error"]:::app
        E4["Stats Error"]:::app
    end

    subgraph "Type Definitions"
        T1["Live Types"]:::types
        T2["Setlist Types"]:::types
        T3["Song Types"]:::types
    end

    %% Connections between layers
    CFG1 -->|"configures"| L
    CFG5 -->|"supports"| T1
    T1 -->|"enforces"| U1
    T2 -->|"supports"| C10

    D5 -->|"preprocesses"| U2
    D1 -->|"loads"| U4
    D2 -->|"loads"| U4
    D3 -->|"loads"| U4
    D4 -->|"loads"| U4
    U4 -->|"supplies_data"| U1

    U2 -->|"transforms_data"| A1
    U3 -->|"enriches_data"| C11
    U1 -->|"fetches"| C1
    C1 -->|"renders"| L
    C2 -->|"renders"| L
    C12 -->|"updates"| A4

    U1 -->|"supports"| C1
    C1 -->|"integrates_into"| A1

    %% Styling classes
    classDef app fill:#f9e79f,stroke:#e67e22,stroke-width:2px;
    classDef component fill:#aed6f1,stroke:#3498db,stroke-width:2px;
    classDef data fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef utility fill:#fdebd0,stroke:#e74c3c,stroke-width:2px;
    classDef types fill:#f5eef8,stroke:#9b59b6,stroke-width:2px;
    classDef config fill:#fceabb,stroke:#f39c12,stroke-width:2px;

    %% Click Events for Next.js App Layer
    click A1 "https://github.com/suneo3476/nanawa/blob/main/src/app/page.tsx"
    click A2 "https://github.com/suneo3476/nanawa/blob/main/src/app/heatmap/page.tsx"
    click A3 "https://github.com/suneo3476/nanawa/blob/main/src/app/search/page.tsx"
    click A4 "https://github.com/suneo3476/nanawa/blob/main/src/app/stats/page.tsx"
    click A5 "https://github.com/suneo3476/nanawa/blob/main/src/app/timeline/page.tsx"
    click L "https://github.com/suneo3476/nanawa/blob/main/src/app/layout.tsx"
    click E1 "https://github.com/suneo3476/nanawa/blob/main/src/app/not-found.tsx"
    click E2 "https://github.com/suneo3476/nanawa/blob/main/src/app/heatmap/error.tsx"
    click E3 "https://github.com/suneo3476/nanawa/blob/main/src/app/search/error.tsx"
    click E4 "https://github.com/suneo3476/nanawa/blob/main/src/app/stats/error.tsx"

    %% Click Events for UI Components Module
    click C1 "https://github.com/suneo3476/nanawa/blob/main/src/components/Header/Header.tsx"
    click C2 "https://github.com/suneo3476/nanawa/blob/main/src/components/Breadcrumbs/Breadcrumbs.tsx"
    click C3 "https://github.com/suneo3476/nanawa/blob/main/src/components/AdvancedSearch/AdvancedSearch.tsx"
    click C4 "https://github.com/suneo3476/nanawa/blob/main/src/components/LiveCard/LiveCard.tsx"
    click C5 "https://github.com/suneo3476/nanawa/blob/main/src/components/LiveList/LiveListClient.tsx"
    click C6 "https://github.com/suneo3476/nanawa/blob/main/src/components/LiveTimeline/LiveTimeline.tsx"
    click C7 "https://github.com/suneo3476/nanawa/blob/main/src/components/LiveViewIntegrated/LiveViewIntegrated.tsx"
    click C8 "https://github.com/suneo3476/nanawa/blob/main/src/components/PerformanceHeatmap/PerformanceHeatmap.tsx"
    click C9 "https://github.com/suneo3476/nanawa/blob/main/src/components/SetlistPreview/SetlistPreview.tsx"
    click C10 "https://github.com/suneo3476/nanawa/blob/main/src/components/SetlistView/SetlistView.tsx"
    click C11 "https://github.com/suneo3476/nanawa/blob/main/src/components/SongCard/SongCard.tsx"
    click C12 "https://github.com/suneo3476/nanawa/blob/main/src/components/StatsDashboard/StatsDashboard.tsx"
    click C13 "https://github.com/suneo3476/nanawa/blob/main/src/components/Settings/SettingsContext.tsx"

    %% Click Events for Data Layer
    click D1 "https://github.com/suneo3476/nanawa/blob/main/data/discography.txt"
    click D2 "https://github.com/suneo3476/nanawa/blob/main/data/live_history.txt"
    click D3 "https://github.com/suneo3476/nanawa/blob/main/data/setlist_history.txt"
    click D4 "https://github.com/suneo3476/nanawa/blob/main/data/tracks.txt"
    click D5 "https://github.com/suneo3476/nanawa/blob/main/scripts/migrate-data.ts"

    %% Click Events for Utility & Helper Functions
    click U1 "https://github.com/suneo3476/nanawa/blob/main/src/utils/api.ts"
    click U2 "https://github.com/suneo3476/nanawa/blob/main/src/utils/data-converter.ts"
    click U3 "https://github.com/suneo3476/nanawa/blob/main/src/utils/song-enricher.ts"
    click U4 "https://github.com/suneo3476/nanawa/blob/main/src/utils/static-data-loader.ts"

    %% Click Events for Type Definitions
    click T1 "https://github.com/suneo3476/nanawa/blob/main/src/types/live.ts"
    click T2 "https://github.com/suneo3476/nanawa/blob/main/src/types/setlist.ts"
    click T3 "https://github.com/suneo3476/nanawa/blob/main/src/types/song.ts"

    %% Click Events for Configuration & Build Tools
    click CFG1 "https://github.com/suneo3476/nanawa/blob/main/next.config.mjs"
    click CFG2 "https://github.com/suneo3476/nanawa/blob/main/tailwind.config.js"
    click CFG3 "https://github.com/suneo3476/nanawa/blob/main/postcss.config.js"
    click CFG4 "https://github.com/suneo3476/nanawa/blob/main/jest.config.ts"
    click CFG5 "https://github.com/suneo3476/nanawa/blob/main/tsconfig.json"
```
