# tomokino2015/area-guides architecture

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

- Interactive diagram: https://gitdiagram.com/tomokino2015/area-guides
- Repository: https://github.com/tomokino2015/area-guides

## Overview

##### Project type and purpose
- This is a Next.js 15.2.4 application that serves as a static/SSR “area guide” website for Tokyo’s 23 wards.
- It provides rental property info and living-environment guides via a file-based data layer and React components, styled with Tailwind CSS and using shadcn/ui + Radix for UI primitives.

##### File structure
- Top-level “app/” folder: Next.js App Router pages and layouts (dynamic routes under `[ward]`).
- “components/”: shared React components subdivided into “common,” “ward,” and “ui” libraries.
- “data/”: local data source for each ward (`data/wards/*.ts`) plus an index that aggregates them.
- “lib/”: utility and i18n helper functions.
- “hooks/”: custom React hooks for mobile detection and toast messaging.
- “public/”: static assets (images).
- Configuration files: `next.config.mjs`, `tailwind.config.ts`, `tsconfig.json`, plus build scripts in “scripts/.”

##### README insights
- The README explicitly calls out a “Data-Driven Architecture” where `WardData` objects in TypeScript drive dynamic routing and content rendering.
- Tech stack: Next.js App Router, TypeScript, Tailwind, shadcn/ui + Radix UI, React Hook Form + Zod, Vercel Analytics.
- It describes the branching strategy, deployment on Vercel, and future CMS/API integration plans.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Browser["User Browser"]:::client

    subgraph "Server & Build" 
        direction TB
        NextServer["Next.js Server / Build Process"]:::server
        AppRouter["App Router & Page Components<br/>(app/)"]:::server
        WardPage["Dynamic Ward Page<br/>(app/[ward]/page.tsx)"]:::server
        WardClient["Ward Client-Side Component<br/>(app/[ward]/ward-page-client.tsx)"]:::server
        Marketing["Marketing Pages<br/>(app/(marketing)/areas/[slug]/page.tsx)"]:::server
        Layout["Global Layout & Styles<br/>(layout.tsx, globals.css)"]:::server
        HomePage["Home Page<br/>(app/page.tsx)"]:::server
    end

    subgraph "Data Layer" 
        direction TB
        DataIndex["Ward Data Index<br/>(data/index.ts)"]:::data
        WardDefs["Individual Ward Definitions<br/>(data/wards/*.ts)"]:::data
        ContentFiles["Content Files<br/>(content/area/*.yml)"]:::data
    end

    subgraph "Component Library" 
        direction TB
        CommonComp["Common Components<br/>(components/common/)"]:::ui
        WardComp["Ward-Specific Components<br/>(components/ward/)"]:::ui
        UIPrimitives["UI Primitives<br/>(components/ui/)"]:::ui
        ThemeProv["Theme Provider<br/>(components/theme-provider.tsx)"]:::ui
        SiteHeader["Site Header<br/>(components/AreasHeader.tsx)"]:::ui
    end

    subgraph "Utils & Hooks" 
        direction TB
        AreaLoader["Area Loader & Validators<br/>(lib/area-loader.ts)"]:::util
        ContentSchema["Content Schema<br/>(lib/content/area.schema.ts)"]:::util
        I18n["Internationalization Helpers<br/>(lib/i18n.ts)"]:::util
        Utils["Misc Helpers<br/>(lib/utils.ts)"]:::util
        HooksMobile["Mobile Detection Hook<br/>(hooks/use-mobile.ts)"]:::util
        HooksToast["Toast Hook<br/>(hooks/use-toast.ts)"]:::util
    end

    subgraph "Static Assets" 
        direction TB
        StaticImages["Images<br/>(public/images/)"]:::static
        StylesGlobal["Global Styles<br/>(styles/globals.css)"]:::static
    end

    subgraph "External Services" 
        direction TB
        VercelHost["Vercel Hosting"]:::external
        VercelAnalytics["Vercel Analytics"]:::external
    end

    Browser --> NextServer
    NextServer --> AppRouter
    AppRouter --> WardPage
    AppRouter --> Marketing
    AppRouter --> HomePage
    WardPage --> DataIndex
    WardPage --> WardDefs
    Marketing --> DataIndex
    Marketing --> ContentFiles
    HomePage --> SiteHeader
    NextServer --> StaticImages
    NextServer --> StylesGlobal
    NextServer --> VercelHost

    AppRouter --> CommonComp
    AppRouter --> WardComp
    AppRouter --> UIPrimitives
    AppRouter --> ThemeProv
    AppRouter --> SiteHeader

    CommonComp --> Utils
    WardComp --> Utils
    UIPrimitives --> Utils
    SiteHeader --> I18n

    Browser -->|hydrates| WardClient
    WardClient --> HooksMobile
    WardClient --> HooksToast
    WardClient --> I18n
    Browser -->|analytics events| VercelAnalytics

    NextServer --> DataIndex
    NextServer --> WardDefs
    NextServer --> ContentFiles

    click AppRouter "https://github.com/tomokino2015/area-guides/tree/main/app/"
    click WardPage "https://github.com/tomokino2015/area-guides/blob/main/app/[ward]/page.tsx"
    click WardClient "https://github.com/tomokino2015/area-guides/blob/main/app/[ward]/ward-page-client.tsx"
    click Marketing "https://github.com/tomokino2015/area-guides/blob/main/app/(marketing)/areas/[slug]/page.tsx"
    click Layout "https://github.com/tomokino2015/area-guides/blob/main/app/layout.tsx"
    click HomePage "https://github.com/tomokino2015/area-guides/blob/main/app/page.tsx"
    click CommonComp "https://github.com/tomokino2015/area-guides/tree/main/components/common/"
    click WardComp "https://github.com/tomokino2015/area-guides/tree/main/components/ward/"
    click UIPrimitives "https://github.com/tomokino2015/area-guides/tree/main/components/ui/"
    click ThemeProv "https://github.com/tomokino2015/area-guides/blob/main/components/theme-provider.tsx"
    click SiteHeader "https://github.com/tomokino2015/area-guides/blob/main/components/AreasHeader.tsx"
    click DataIndex "https://github.com/tomokino2015/area-guides/blob/main/data/index.ts"
    click WardDefs "https://github.com/tomokino2015/area-guides/blob/main/data/wards/*.ts"
    click ContentFiles "https://github.com/tomokino2015/area-guides/blob/main/content/area/*.yml"
    click AreaLoader "https://github.com/tomokino2015/area-guides/blob/main/lib/area-loader.ts"
    click ContentSchema "https://github.com/tomokino2015/area-guides/blob/main/lib/content/area.schema.ts"
    click I18n "https://github.com/tomokino2015/area-guides/blob/main/lib/i18n.ts"
    click Utils "https://github.com/tomokino2015/area-guides/blob/main/lib/utils.ts"
    click HooksMobile "https://github.com/tomokino2015/area-guides/blob/main/hooks/use-mobile.ts"
    click HooksToast "https://github.com/tomokino2015/area-guides/blob/main/hooks/use-toast.ts"
    click StaticImages "https://github.com/tomokino2015/area-guides/tree/main/public/images/"

    classDef client fill:#cce5ff,stroke:#3399ff
    classDef server fill:#ffe5b4,stroke:#ff9900
    classDef data fill:#d4edda,stroke:#28a745
    classDef ui fill:#cce5ff,stroke:#0066cc
    classDef util fill:#e0f7fa,stroke:#00bcd4
    classDef static fill:#f2f2f2,stroke:#999999
    classDef external fill:#f5e6ff,stroke:#9933cc
```
