# tskaigi/hokuriku-web-site architecture

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

- Interactive diagram: https://gitdiagram.com/tskaigi/hokuriku-web-site
- Repository: https://github.com/tskaigi/hokuriku-web-site

## Overview

##### Project type and purpose
- This is a full-stack static web application (an event site) built with Next.js 13’s App Router.
- It uses SSG (static site generation) + a custom data-generation script (`scripts/generate-talks-json.ts`) to produce JSON at build time.
- Hosting/deployment is handled via Firebase Hosting (and GitHub Actions for CI/CD), serving only static assets—no runtime backend.

##### File structure
- Top level:
- config files (`next.config.ts`, `.firebaserc`, `firebase.json`, GitHub Actions workflows)
- `scripts/` – custom build-time scripts
- `public/` – static assets (images, OGP cards)
- `src/app/` – Next.js App Router pages/layouts
- `src/components/` – React components, organized by domain (talks, sponsors, UI primitives)
- `src/constants/` & `src/utils/` & `src/hooks/` & `src/lib/` – domain data and helpers
- CI/CD: `.github/workflows/ci.yml` (build + tests), `cd.yml` (deploy to production), `preview.yml` (deploy preview to Firebase).

##### Key README insights
- Uses pnpm package manager
- Prettier and linting enforced on PRs
- GitHub Actions automatically builds and deploys preview URLs to Firebase Hosting
- On merge to main, production deploy occurs

##### Main components and interactions
a. Components
- Developer Workstation (code + local build)
- GitHub Repository
- CI/CD Pipelines (GitHub Actions)
– Build job: `pnpm install` → `pnpm run build` (Next.js + JSON script)
– Preview job: deploy to Firebase Preview channel
– Release job: deploy to Firebase Production
- Firebase Hosting (CDN + edge cache)
- Client Browser
- Next.js Static Artifacts
– HTML/CSS/JS pages (App Router output)
– JSON data (generated in `public/`)
– Public static assets (SVGs, OGP images, etc.)
b. Relationships & data flow
1. Developer pushes code → GitHub
2. GitHub Actions triggers CI → installs → runs build script → outputs artifacts
3. Artifacts → deployed to Firebase Preview (for PR) or Production (on main)
4. End user’s browser requests URL → Firebase CDN edge → serves static HTML/CSS/JS/JSON → browser renders pages
c. Architectural patterns & principles
- Static-First / SSG: all pages are pre-rendered at build time
- Component-Based UI: React components organized by domain
- Separation of concerns: content in `src/constants`, UI in `src/components`, routing in `src/app`
- CI/CD as part of architecture—automated preview and release channels
d. Relevant technologies
- Next.js 13 (App Router + SSG)
- React + TypeScript
- pnpm
- Firebase Hosting (with `.firebaserc` and `firebase.json`)
- GitHub Actions (ci.yml, cd.yml, preview.yml)
- Prettier & ESLint

##### Diagramming recommendations
– Blue for code & CI/CD
– Green for hosting & CDN
– Orange for static artifacts
– Gray for client

##### Key points to capture
- That there is no dynamic backend at runtime—all pages and data are pre-built
- The multi-stage pipeline: local → GitHub → preview → prod
- Static asset flow from `public/` and JSON generation
- Firebase Hosting as the sole serving layer
- React/Next.js App structure (pages in `src/app`, domain components)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Environment
    Dev["Developer Workstation"]:::dev
    Dev -->|git push| Repo["GitHub Repository"]:::code

    %% Repository Configurations
    subgraph "Configurations" 
        NextConfig["next.config.ts"]:::code
        Firebaserc[".firebaserc"]:::code
        FirebaseJson["firebase.json"]:::code
    end
    Repo --> Configs

    %% CI/CD Pipelines
    subgraph "CI/CD Pipelines" 
        CI_CI["Build & Test (ci.yml)"]:::ci
        CI_Preview["Preview Deploy (preview.yml)"]:::ci
        CI_Prod["Production Deploy (cd.yml)"]:::ci
    end
    Repo -->|on push| CI_CI
    CI_CI -->|on pull request| CI_Preview
    CI_CI -->|on merge to main| CI_Prod

    %% Static Artifacts
    subgraph "Static Artifacts" 
        HTML["HTML/CSS/JS Pages"]:::artifact
        JSON["JSON Data (public/talks/,public/timetable/)"]:::artifact
        Assets["Static Assets (public/)"]:::artifact
    end
    CI_CI -->|build & generate JSON| HTML
    CI_CI -->|build & generate JSON| JSON
    CI_CI -->|build & copy assets| Assets

    %% Hosting Infrastructure
    subgraph "Hosting" 
        Firebase["Firebase Hosting CDN"]:::host
    end
    CI_Preview -->|deploy preview| Firebase
    CI_Prod -->|deploy production| Firebase

    %% Client Consumption
    Client["Client Browser"]:::client
    Firebase -->|HTTP GET| Client

    %% Additional Components
    subgraph "Next.js App"
        AppRouter["src/app/"]:::code
    end
    subgraph "Components & Libraries"
        Components["src/components/"]:::code
        Constants["src/constants/"]:::code
        Hooks["src/hooks/"]:::code
        Utils["src/utils/"]:::code
        Lib["src/lib/"]:::code
    end
    AppRouter --> Components
    AppRouter --> Constants
    AppRouter --> Hooks
    AppRouter --> Utils
    AppRouter --> Lib

    %% Click Events
    click script "https://github.com/tskaigi/hokuriku-web-site/blob/main/scripts/generate-talks-json.ts"
    click NextConfig "https://github.com/tskaigi/hokuriku-web-site/blob/main/next.config.ts"
    click Firebaserc "https://github.com/tskaigi/hokuriku-web-site/blob/main/.firebaserc"
    click FirebaseJson "https://github.com/tskaigi/hokuriku-web-site/blob/main/firebase.json"
    click CI_CI "https://github.com/tskaigi/hokuriku-web-site/blob/main/.github/workflows/ci.yml"
    click CI_Preview "https://github.com/tskaigi/hokuriku-web-site/blob/main/.github/workflows/preview.yml"
    click CI_Prod "https://github.com/tskaigi/hokuriku-web-site/blob/main/.github/workflows/cd.yml"
    click Assets "https://github.com/tskaigi/hokuriku-web-site/tree/main/public/"
    click JSON "https://github.com/tskaigi/hokuriku-web-site/tree/main/public/talks/"
    click AppRouter "https://github.com/tskaigi/hokuriku-web-site/tree/main/src/app/"
    click Components "https://github.com/tskaigi/hokuriku-web-site/tree/main/src/components/"
    click Constants "https://github.com/tskaigi/hokuriku-web-site/tree/main/src/constants/"
    click Hooks "https://github.com/tskaigi/hokuriku-web-site/tree/main/src/hooks/"
    click Utils "https://github.com/tskaigi/hokuriku-web-site/tree/main/src/utils/"
    click Lib "https://github.com/tskaigi/hokuriku-web-site/tree/main/src/lib/"

    %% Styles
    classDef dev fill:#bbdefb,stroke:#888;
    classDef code fill:#90caf9,stroke:#333;
    classDef ci fill:#64b5f6,stroke:#333;
    classDef host fill:#a5d6a7,stroke:#333;
    classDef artifact fill:#ffcc80,stroke:#bb6600;
    classDef client fill:#eeeeee,stroke:#888;
```
