# katyono4ek/fukuoka-guide architecture

> Architecture diagram of the GitHub repository katyono4ek/fukuoka-guide, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/katyono4ek/fukuoka-guide
- Repository: https://github.com/katyono4ek/fukuoka-guide

## Overview

Fukuoka, softly is a bilingual, JSON-driven static travel guide. Editors add localized sections, place entries, and photo metadata; the build loads and validates that content, renders a complete page for each locale, and copies local assets into a static site for readers. In the browser, JavaScript enhances the pages with theme, language, filtering, and navigation behavior; the content remains readable without it. A separate photo tool fetches and crops Commons images, while a local-only server previews built output. Relationships for client-side behavior and some content capabilities are based on README documentation; unsampled asset internals are not inspected.

Main entry points: [`src/content.mjs`](https://github.com/katyono4ek/fukuoka-guide/blob/main/src/content.mjs) (Load and validate), [`src/build.mjs`](https://github.com/katyono4ek/fukuoka-guide/blob/main/src/build.mjs) (Static site builder), [`tools/photo.mjs`](https://github.com/katyono4ek/fukuoka-guide/blob/main/tools/photo.mjs) (Photo fetch and crop), [`src/templates.mjs`](https://github.com/katyono4ek/fukuoka-guide/blob/main/src/templates.mjs) (HTML rendering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_content["Guide content"]
  node_siteconfig["Site configuration<br/>[site.json]"]
  node_sections["Guide sections"]
  node_photodata["Photo metadata<br/>[photos.json]"]
  node_photofiles["Photo files"]
end

subgraph group_generation["Site generation"]
  node_loader["Load and validate<br/>[content.mjs]"]
  node_photoformats["Photo formats<br/>[photos.mjs]"]
  node_renderer["HTML rendering<br/>[templates.mjs]"]
  node_builder["Static site builder<br/>[build.mjs]"]
end

subgraph group_reader["Reader experience"]
  node_staticpages["Localized static pages<br/>[build.mjs]"]
  node_theme["Theme toggle<br/>[theme.js]"]
  node_filters["Tag filters<br/>[app.js]"]
  node_navigation["Language and page navigation<br/>[gate.js]"]
  node_styles["Page styling<br/>[styles.css]"]
  node_preview["Local preview server<br/>[serve.mjs]"]
end

subgraph group_authoring["Photo authoring"]
  node_phototool["Photo fetch and crop<br/>[photo.mjs]"]
end

node_editor(("Content editor"))
node_readeractor(("Guide reader"))
node_commons["Wikimedia Commons"]

node_editor -->|"edits settings"| node_siteconfig
node_editor -->|"adds entries"| node_sections
node_editor -->|"writes alt text"| node_photodata
node_loader -->|"loads"| node_siteconfig
node_loader -->|"loads and validates"| node_sections
node_loader -->|"loads and validates"| node_photodata
node_loader -->|"checks photo files"| node_photoformats
node_builder -->|"loads content"| node_loader
node_builder -->|"renders pages"| node_renderer
node_builder -->|"writes output"| node_staticpages
node_builder -->|"copies photos"| node_photofiles
node_renderer -->|"uses translations"| node_loader
node_renderer -->|"builds photo markup"| node_photoformats
node_renderer -->|"renders credits and alt text"| node_photodata
node_staticpages -->|"serves guide"| node_readeractor
node_readeractor -->|"toggles theme"| node_theme
node_readeractor -->|"filters tags"| node_filters
node_readeractor -->|"switches language"| node_navigation
node_staticpages -->|"loads styling"| node_styles
node_preview -->|"serves built output"| node_staticpages
node_phototool -->|"fetches image data"| node_commons
node_phototool -->|"writes cropped photos"| node_photofiles
node_phototool -->|"updates credits"| node_photodata
node_phototool -->|"uses dimensions"| node_photoformats

click node_siteconfig "https://github.com/katyono4ek/fukuoka-guide/blob/main/content/site.json"
click node_sections "https://github.com/katyono4ek/fukuoka-guide/tree/main/content/sections"
click node_photodata "https://github.com/katyono4ek/fukuoka-guide/blob/main/content/photos.json"
click node_photofiles "https://github.com/katyono4ek/fukuoka-guide/tree/main/content/photos"
click node_loader "https://github.com/katyono4ek/fukuoka-guide/blob/main/src/content.mjs"
click node_photoformats "https://github.com/katyono4ek/fukuoka-guide/blob/main/src/photos.mjs"
click node_renderer "https://github.com/katyono4ek/fukuoka-guide/blob/main/src/templates.mjs"
click node_builder "https://github.com/katyono4ek/fukuoka-guide/blob/main/src/build.mjs"
click node_staticpages "https://github.com/katyono4ek/fukuoka-guide/blob/main/src/build.mjs"
click node_theme "https://github.com/katyono4ek/fukuoka-guide/blob/main/src/assets/theme.js"
click node_filters "https://github.com/katyono4ek/fukuoka-guide/blob/main/src/assets/app.js"
click node_navigation "https://github.com/katyono4ek/fukuoka-guide/blob/main/src/assets/gate.js"
click node_styles "https://github.com/katyono4ek/fukuoka-guide/blob/main/src/assets/styles.css"
click node_preview "https://github.com/katyono4ek/fukuoka-guide/blob/main/src/serve.mjs"
click node_phototool "https://github.com/katyono4ek/fukuoka-guide/blob/main/tools/photo.mjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_siteconfig,node_sections,node_photodata,node_photofiles toneBlue
class node_loader,node_photoformats,node_renderer,node_builder toneAmber
class node_staticpages,node_theme,node_filters,node_navigation,node_styles,node_preview toneMint
class node_phototool toneRose
class node_editor,node_readeractor,node_commons toneIndigo
```

## Components

### Guide content

- [Site configuration](https://github.com/katyono4ek/fukuoka-guide/blob/main/content/site.json): `content/site.json`
- [Guide sections](https://github.com/katyono4ek/fukuoka-guide/tree/main/content/sections): `content/sections`
- [Photo metadata](https://github.com/katyono4ek/fukuoka-guide/blob/main/content/photos.json): `content/photos.json`
- [Photo files](https://github.com/katyono4ek/fukuoka-guide/tree/main/content/photos): `content/photos`

### Site generation

- [Load and validate](https://github.com/katyono4ek/fukuoka-guide/blob/main/src/content.mjs): `src/content.mjs`
- [Photo formats](https://github.com/katyono4ek/fukuoka-guide/blob/main/src/photos.mjs): `src/photos.mjs`
- [HTML rendering](https://github.com/katyono4ek/fukuoka-guide/blob/main/src/templates.mjs): `src/templates.mjs`
- [Static site builder](https://github.com/katyono4ek/fukuoka-guide/blob/main/src/build.mjs): `src/build.mjs`

### Reader experience

- [Localized static pages](https://github.com/katyono4ek/fukuoka-guide/blob/main/src/build.mjs): `src/build.mjs`
- [Theme toggle](https://github.com/katyono4ek/fukuoka-guide/blob/main/src/assets/theme.js): `src/assets/theme.js`
- [Tag filters](https://github.com/katyono4ek/fukuoka-guide/blob/main/src/assets/app.js): `src/assets/app.js`
- [Language and page navigation](https://github.com/katyono4ek/fukuoka-guide/blob/main/src/assets/gate.js): `src/assets/gate.js`
- [Page styling](https://github.com/katyono4ek/fukuoka-guide/blob/main/src/assets/styles.css): `src/assets/styles.css`
- [Local preview server](https://github.com/katyono4ek/fukuoka-guide/blob/main/src/serve.mjs): `src/serve.mjs`

### Photo authoring

- [Photo fetch and crop](https://github.com/katyono4ek/fukuoka-guide/blob/main/tools/photo.mjs): `tools/photo.mjs`

### Other components

- **Content editor**
- **Guide reader**
- **Wikimedia Commons**

## Connections

- Content editor → Site configuration: edits settings (evidence: `README.md`)
- Content editor → Guide sections: adds entries (evidence: `README.md`)
- Content editor → Photo metadata: writes alt text (evidence: `README.md`)
- Load and validate → Site configuration: loads (evidence: `src/content.mjs`)
- Load and validate → Guide sections: loads and validates (evidence: `src/content.mjs`)
- Load and validate → Photo metadata: loads and validates (evidence: `src/content.mjs`)
- Load and validate → Photo formats: checks photo files (evidence: `src/content.mjs`)
- Static site builder → Load and validate: loads content (evidence: `src/build.mjs`)
- Static site builder → HTML rendering: renders pages (evidence: `src/build.mjs`)
- Static site builder → Localized static pages: writes output (evidence: `src/build.mjs`)
- Static site builder → Photo files: copies photos (evidence: `src/build.mjs`)
- HTML rendering → Load and validate: uses translations (evidence: `src/templates.mjs`)
- HTML rendering → Photo formats: builds photo markup (evidence: `src/templates.mjs`)
- HTML rendering → Photo metadata: renders credits and alt text (evidence: `README.md`)
- Localized static pages → Guide reader: serves guide (evidence: `README.md`)
- Guide reader → Theme toggle: toggles theme (evidence: `README.md`)
- Guide reader → Tag filters: filters tags (evidence: `README.md`)
- Guide reader → Language and page navigation: switches language (evidence: `README.md`)
- Localized static pages → Page styling: loads styling
- Local preview server → Localized static pages: serves built output (evidence: `src/serve.mjs`)
- Photo fetch and crop → Wikimedia Commons: fetches image data (evidence: `tools/photo.mjs`)
- Photo fetch and crop → Photo files: writes cropped photos (evidence: `tools/photo.mjs`)
- Photo fetch and crop → Photo metadata: updates credits (evidence: `tools/photo.mjs`)
- Photo fetch and crop → Photo formats: uses dimensions (evidence: `tools/photo.mjs`)
