# kotaoue/gamemo architecture

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

- Interactive diagram: https://gitdiagram.com/kotaoue/gamemo
- Repository: https://github.com/kotaoue/gamemo

## Overview

##### Project type & purpose (from file tree + top README)

This repo is primarily a **personal knowledge base + analysis notebook** (“gamemo”) organized by game/topic (Splatoon, Pokémon, etc.) using **Markdown files** as the main artifact.

In addition, it contains a couple of **small Go-based tooling subprojects** that automate collecting/transformation of data into Markdown:

- `splatoon3/ikamemo/` — a Go tool (with `Makefile`) that likely **generates memo/summary Markdown** from Splatoon-related data (notably the `splatoon3/sheets/*.json` files and `splatoon3/results/template.md`).
- `hypnosismic/hypwiki/` — a Go tool with files like `scraper.go`, `writer.go` that strongly implies **scraping + writing wiki-style content**.

There is also automation via GitHub Actions:

- `.github/workflows/fetch-splatoon3-sheets.yml` — a workflow that likely fetches or updates Splatoon 3 “sheets” data into `splatoon3/sheets/`.

##### Repository as the canonical store
- Markdown notes (manual + generated)
- JSON datasets (“sheets”)
- Generated outputs (`splatoon3/results/`, possibly more)

##### Automation paths that update the repo
- GitHub Actions (scheduled or manual)
- Local developer runs (Makefile / go run)

##### External sources
- Whatever the workflow fetches (likely Google Sheets or some hosted JSON)
- Whatever `hypwiki` scrapes (a website/wiki)

##### “Content” (human-facing artifacts)
From the tree, these are the primary deliverables:

- Top-level Markdown collections:
`splatoon3/*.md`, `splatoon2/gear.md`, `pokemon/*.md`, `ocg/*.md`, `mhr/mhr.md`, `ssb/spirits.md`, `tsumtsum/tsumtsum.md`, etc.
- Splatoon 3 outputs:
`splatoon3/results/template.md` (template), `splatoon3/results/` (likely generated result docs)
- Images:
`splatoon3/images/`

##### Data inputs / datasets
- `splatoon3/sheets/*.json` (multiple datasets, plus `download_sheets.sh`)
- Anything fetched by `.github/workflows/fetch-splatoon3-sheets.yml`

##### Tooling subprojects (Go)
- `splatoon3/ikamemo/`
- `main.go` (entrypoint/CLI)
- `generator.go` (core transformation logic)
- `writer.go` (output formatting/writing)
- `go.mod`, `go.sum` (dependencies)
- `Makefile` (local execution)
- `hypnosismic/hypwiki/`
- `main.go` (entrypoint/CLI)
- `scraper.go` (external fetch/parse)
- `writer.go` (writes markdown/pages)
- `go.mod`, `go.sum`

##### Automation / orchestration
- GitHub Actions workflow: `.github/workflows/fetch-splatoon3-sheets.yml`
- Shell helper: `splatoon3/sheets/download_sheets.sh`
- (Optional) Dev environment docs: `environment/desktop.md`

##### External Sheets Source
↓ (HTTP fetch/export)
##### GitHub Actions: `fetch-splatoon3-sheets.yml` and/or local script `download_sheets.sh`
↓ (writes/updates)
##### Repo folder: `splatoon3/sheets/*.json`
↓ (read)
##### Go CLI: `splatoon3/ikamemo/main.go`
- `generator.go` transforms JSON → internal model → sections/metrics
- `writer.go` renders Markdown
↓ (write)
##### Repo outputs: `splatoon3/results/` and/or `splatoon3/*.md`

- Local dev run (Makefile)

##### External Hypnosismic site/wiki
↓ (HTTP scrape)
##### Go CLI: `hypnosismic/hypwiki/main.go`
- `scraper.go` fetch/parse
- `writer.go` outputs Markdown
↓ (write)

##### Manual content authoring
- “Human editor” → modifies Markdown notes directly across topic folders
- Human also runs tools locally

##### Architectural patterns / design principles to highlight (from structure)

Even without reading code, the file naming implies clear separations:

- **CLI entrypoint** (`main.go`) vs **domain logic** (`generator.go` / `scraper.go`) vs **IO/output** (`writer.go`)
- **Data-driven generation**: JSON datasets are treated as inputs; Markdown is output.
- **Repo as single source of truth**: both raw inputs (JSON) and final artifacts (Markdown) live together.
- **Automation-as-code**: GitHub Actions codifies ingestion steps.

- In `.github/workflows/fetch-splatoon3-sheets.yml`:
- schedule vs manual trigger
- exact source endpoint(s)
- whether it commits back to repo
- In `splatoon3/ikamemo/README.md` and `main.go`:
- exact inputs (which JSON files)
- exact outputs (which `.md` files/paths)
- whether it uses `splatoon3/results/template.md`
- In `hypnosismic/hypwiki/README.md` and `scraper.go`:
- scraped site(s) and output directory structure

- External: “Sheets Source” → (GitHub Actions / download_sheets.sh) → `splatoon3/sheets/*.json`
- `splatoon3/sheets/*.json` → `splatoon3/ikamemo` (Go CLI) → `splatoon3/results/*` + `splatoon3/*.md`
- External: “Hypnosismic Wiki Site” → `hypnosismic/hypwiki` (Go CLI scraper) → `hypnosismic/*.md`
- Actor: “Author” ↔ Repo (manual edits + runs tools locally)

This captures the essential architecture: **ingest → transform → publish**, with the repo as the hub.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Actors & External Systems
  %% =========================
  subgraph "Actors"
    Author["Author / Editor"]:::actor
  end

  subgraph "External Systems"
    SheetsSrc(["Sheets Data Source\n(e.g., Google Sheets / JSON endpoint)"]):::external
    HypSite(["Hypnosismic Website / Wiki Source"]):::external
    GHCloud(["GitHub Platform"]):::external
  end

  %% =========================
  %% GitHub Repository (Canonical Store)
  %% =========================
  subgraph "gamemo Repository (Canonical Content Store)"
    Readme["Repository README / Index"]:::doc

    subgraph "Manual Topic Notes (Markdown)"
      S3Notes["Splatoon 3 Notes (Markdown)"]:::doc
      S2Gear["Splatoon 2 Gear Notes (Markdown)"]:::doc
      PokemonNotes["Pokémon Notes (Markdown)"]:::doc
      OcgNotes["OCG Notes (Markdown)"]:::doc
      MhrNotes["MHR Notes (Markdown)"]:::doc
      SsbNotes["SSB Spirits Notes (Markdown)"]:::doc
      TsumNotes["TsumTsum Notes (Markdown)"]:::doc
      S3Images["Splatoon 3 Images"]:::asset
    end

    subgraph "Splatoon 3 Data & Outputs"
      SheetsJSON[("Splatoon 3 Sheets Datasets (JSON)")]:::datastore
      ResultsDir[("Splatoon 3 Generated Results (Markdown)")]:::datastore
      ResultsTemplate["Results Template (Markdown)"]:::doc
    end

    subgraph "Automation as Code"
      GHAWorkflow["GitHub Actions Workflow:\nFetch/Update Sheets"]:::automation
      DownloadScript["Local Helper Script:\nDownload Sheets JSON"]:::automation
      EnvDoc["Developer Environment Notes"]:::doc
    end

    subgraph "Go Tooling: Splatoon 3 (ikamemo)"
      IkamemoCLI["ikamemo CLI (Go)"]:::tool
      IkMain["main.go\n(CLI entrypoint)"]:::component
      IkGen["generator.go\n(Transform JSON → model/sections)"]:::component
      IkWriter["writer.go\n(Render/Write Markdown)"]:::component
      IkMake["Makefile\n(Local run orchestration)"]:::automation
      IkMod["go.mod\n(Dependencies)"]:::component
      IkSum["go.sum\n(Lockfile)"]:::component
      IkReadme["README.md\n(Usage/Docs)"]:::doc
    end

    subgraph "Go Tooling: Hypnosismic (hypwiki)"
      HypwikiCLI["hypwiki CLI (Go)"]:::tool
      HyMain["main.go\n(CLI entrypoint)"]:::component
      HyScrape["scraper.go\n(HTTP fetch/parse)"]:::component
      HyWriter["writer.go\n(Write Markdown)"]:::component
      HyMod["go.mod\n(Dependencies)"]:::component
      HySum["go.sum\n(Lockfile)"]:::component
      HyReadme["README.md\n(Usage/Docs)"]:::doc
      HypOut[("Hypnosismic Generated Markdown Content")]:::datastore
    end
  end

  %% =========================
  %% Relationships / Pipelines
  %% =========================

  %% Author interactions
  Author -->|"edits_manual_notes"| S3Notes
  Author -->|"edits_manual_notes"| S2Gear
  Author -->|"edits_manual_notes"| PokemonNotes
  Author -->|"edits_manual_notes"| OcgNotes
  Author -->|"edits_manual_notes"| MhrNotes
  Author -->|"edits_manual_notes"| SsbNotes
  Author -->|"edits_manual_notes"| TsumNotes
  Author -->|"adds/updates_assets"| S3Images
  Author -->|"reads/uses"| Readme
  Author -->|"references"| EnvDoc

  %% GitHub platform ties
  GHCloud -.->|"hosts_repo"| Readme
  GHCloud -.->|"runs"| GHAWorkflow

  %% Pipeline 1: Sheets -> JSON -> ikamemo -> Markdown outputs
  SheetsSrc -->|"HTTP_export/fetch"| GHAWorkflow
  SheetsSrc -->|"HTTP_export/fetch"| DownloadScript

  GHAWorkflow -.->|"writes/updates"| SheetsJSON
  DownloadScript -.->|"writes/updates"| SheetsJSON

  Author -.->|"runs_locally"| IkMake
  IkMake -.->|"executes"| IkamemoCLI

  Author -.->|"runs_go_cli"| IkamemoCLI

  IkamemoCLI -->|"calls"| IkMain
  IkMain -->|"uses"| IkGen
  IkMain -->|"uses"| IkWriter

  SheetsJSON -->|"read_json_datasets"| IkGen
  ResultsTemplate -->|"read_template"| IkWriter

  IkWriter -->|"write_generated_markdown"| ResultsDir
  IkWriter -->|"optionally_update"| S3Notes

  %% Pipeline 2: Hyp site -> hypwiki -> generated Markdown under hypnosismic/
  HypSite -->|"HTTP_scrape"| HyScrape
  Author -.->|"runs_go_cli"| HypwikiCLI

  HypwikiCLI -->|"calls"| HyMain
  HyMain -->|"uses"| HyScrape
  HyMain -->|"uses"| HyWriter

  HyWriter -->|"write_generated_markdown"| HypOut

  %% =========================
  %% Click Events (from component_mapping)
  %% =========================
  click Readme "https://github.com/kotaoue/gamemo/blob/main/README.md"

  click S3Notes "https://github.com/kotaoue/gamemo/blob/main/splatoon3/*.md"
  click S2Gear "https://github.com/kotaoue/gamemo/blob/main/splatoon2/gear.md"
  click PokemonNotes "https://github.com/kotaoue/gamemo/blob/main/pokemon/*.md"
  click OcgNotes "https://github.com/kotaoue/gamemo/blob/main/ocg/*.md"
  click MhrNotes "https://github.com/kotaoue/gamemo/blob/main/mhr/mhr.md"
  click SsbNotes "https://github.com/kotaoue/gamemo/blob/main/ssb/spirits.md"
  click TsumNotes "https://github.com/kotaoue/gamemo/blob/main/tsumtsum/tsumtsum.md"

  click ResultsDir "https://github.com/kotaoue/gamemo/tree/main/splatoon3/results/"
  click ResultsTemplate "https://github.com/kotaoue/gamemo/blob/main/splatoon3/results/template.md"
  click S3Images "https://github.com/kotaoue/gamemo/tree/main/splatoon3/images/"

  click SheetsJSON "https://github.com/kotaoue/gamemo/blob/main/splatoon3/sheets/*.json"
  click DownloadScript "https://github.com/kotaoue/gamemo/blob/main/splatoon3/sheets/download_sheets.sh"

  click GHAWorkflow "https://github.com/kotaoue/gamemo/blob/main/.github/workflows/fetch-splatoon3-sheets.yml"

  click IkamemoCLI "https://github.com/kotaoue/gamemo/tree/main/splatoon3/ikamemo/"
  click IkMain "https://github.com/kotaoue/gamemo/blob/main/splatoon3/ikamemo/main.go"
  click IkGen "https://github.com/kotaoue/gamemo/blob/main/splatoon3/ikamemo/generator.go"
  click IkWriter "https://github.com/kotaoue/gamemo/blob/main/splatoon3/ikamemo/writer.go"
  click IkMake "https://github.com/kotaoue/gamemo/tree/main/splatoon3/ikamemo/Makefile"
  click IkMod "https://github.com/kotaoue/gamemo/blob/main/splatoon3/ikamemo/go.mod"
  click IkSum "https://github.com/kotaoue/gamemo/blob/main/splatoon3/ikamemo/go.sum"
  click IkReadme "https://github.com/kotaoue/gamemo/blob/main/splatoon3/ikamemo/README.md"

  click HypwikiCLI "https://github.com/kotaoue/gamemo/tree/main/hypnosismic/hypwiki/"
  click HyMain "https://github.com/kotaoue/gamemo/blob/main/hypnosismic/hypwiki/main.go"
  click HyScrape "https://github.com/kotaoue/gamemo/blob/main/hypnosismic/hypwiki/scraper.go"
  click HyWriter "https://github.com/kotaoue/gamemo/blob/main/hypnosismic/hypwiki/writer.go"
  click HyMod "https://github.com/kotaoue/gamemo/blob/main/hypnosismic/hypwiki/go.mod"
  click HySum "https://github.com/kotaoue/gamemo/blob/main/hypnosismic/hypwiki/go.sum"
  click HyReadme "https://github.com/kotaoue/gamemo/blob/main/hypnosismic/hypwiki/README.md"

  click EnvDoc "https://github.com/kotaoue/gamemo/blob/main/environment/desktop.md"

  %% =========================
  %% Styles
  %% =========================
  classDef actor fill:#E3F2FD,stroke:#1E88E5,stroke-width:2px,color:#0D47A1
  classDef external fill:#F2F2F2,stroke:#616161,stroke-width:2px,color:#212121
  classDef automation fill:#FFF3E0,stroke:#EF6C00,stroke-width:2px,color:#BF360C
  classDef tool fill:#E8EAF6,stroke:#3949AB,stroke-width:2px,color:#1A237E
  classDef component fill:#EDE7F6,stroke:#6A1B9A,stroke-width:1.5px,color:#311B92
  classDef datastore fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px,color:#1B5E20
  classDef doc fill:#F3E5F5,stroke:#8E24AA,stroke-width:2px,color:#4A148C
  classDef asset fill:#E0F7FA,stroke:#00838F,stroke-width:2px,color:#004D40
```
