# haotool/app architecture

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

- Interactive diagram: https://gitdiagram.com/haotool/app
- Repository: https://github.com/haotool/app

## Overview

1. **Repository shape**
   - This is a **pnpm monorepo** of multiple independently deployable React applications.
   - Shared conventions come from the root TypeScript config, workspace setup, lint/test tooling, and repo-wide CI/CD.

2. **Primary application boundary**
   - Each app under `apps/*` is its own unit with its own `src`, `public`, `vite.config`, tests, and deployment surface.
   - The main runtime model is **client-side React + Vite**, with several apps also using **SSG/prerendering** for SEO and shareable content.

3. **Cross-app shared code**
   - `apps/shared/analytics` contains reusable analytics behavior, especially route tracking and GA integration.
   - Most other functionality is intentionally app-local, which keeps the monorepo loosely coupled.

4. **RateWise is the most system-like app**
   - RateWise combines a **UI app**, **data-fetching services**, **generated rate/SEO artifacts**, **offline/PWA support**, and **large SEO surface**.
   - Its data flow is: external rate sources and scheduled scripts produce committed/generated JSON/TS assets, the app consumes those via service and config layers, and the UI renders converters, histories, trends, and localized landing pages.

5. **RateWise data and content pipeline**
   - Static and generated outputs live in `public/api`, `public/rates`, `src/config/generated`, and SEO-related files.
   - Scripts under `apps/ratewise/scripts` refresh live exchange data, build OpenAPI/manifest/robots/LLMs assets, optimize images, and verify production and SEO invariants.
   - The app also has a **service worker**, offline fallback, storage helpers, and hydration/recovery logic, so the browser is a first-class execution boundary.

6. **NihonName is content + data transformation**
   - NihonName centers on local datasets such as `surname_database.csv`, pun-name data, and utilities like romaji conversion.
   - It includes historical content pages, SEO metadata, and dedicated tests/E2E checks, making it closer to a curated content product than a pure utility app.

7. **Park Keeper is browser-device integrated**
   - This app uses browser capabilities more heavily: **geolocation**, **device orientation/compass**, local persistence, map tile caching, and PWA update prompting.
   - Its services layer separates device sensing, map/image utilities, and storage from the UI components that render navigation and parking workflows.

8. **Quake-School is an interactive educational app**
   - Its architecture is mostly local and presentation-driven: lesson data, simulators, quizzes, and visual components for seismic concepts.
   - The main boundary is between lesson/data modules and interactive UI components that visualize magnitude, depth, waves, and intensity.

9. **Split Meow is a stateful mobile-friendly utility**
   - Split Meow focuses on trip expense splitting, calculator behavior, member/payer management, and cat-themed interactions.
   - State is concentrated in a store plus utility modules, with browser-only features like sharing, update prompts, and a service worker for app-like behavior.

10. **haotool is the showcase shell**
   - The root `apps/haotool` app is the marketing/home surface for the product family, with a 3D hero and project navigation.
   - It is intentionally lightweight compared with the product apps, and serves as the public entry point to the ecosystem.

11. **Build, test, and release pipeline**
   - The repo uses **Vitest** for unit/component tests and **Playwright** for E2E.
   - GitHub Actions handle CI, release automation, SEO audits, rate updates, and production governance.
   - `changesets` is the release/version source of truth, and the repo treats versioning and changelogs as generated governance artifacts rather than manual edits.

12. **Deployment and edge/runtime services**
   - Production hosting is split across **Zeabur/Vercel-style static app deployment** and edge services.
   - The repo also includes Cloudflare Worker-style packages such as `rating-api` and `security-headers`, indicating some cross-cutting edge behavior outside the React apps themselves.
   - The browser, PWA service worker, and edge layer form the main runtime boundary around the monorepo’s static assets and generated content.

Main entry points: [`apps/ratewise`](https://github.com/haotool/app/tree/main/apps/ratewise) (RateWise), [`pnpm-workspace.yaml`](https://github.com/haotool/app/blob/main/pnpm-workspace.yaml) (pnpm workspace), [`apps/shared/analytics`](https://github.com/haotool/app/tree/main/apps/shared/analytics) (Shared analytics), [`apps/ratewise/src/services`](https://github.com/haotool/app/tree/main/apps/ratewise/src/services) (Data services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace"]
  node_root_workspace["pnpm workspace<br/>monorepo root"]
end

subgraph group_apps["React apps"]
  node_shared_analytics["Shared analytics<br/>cross-app lib"]
  node_haotool["haotool shell<br/>marketing React app"]
  node_nihonname["NihonName<br/>content React app"]
  node_parkkeeper["Park Keeper<br/>PWA React app"]
  node_quakeschool["Quake-School<br/>educational React app"]
  node_ratewise["RateWise<br/>SEO PWA app"]
  node_splitmeow["Split Meow<br/>mobile utility app"]
  node_ratewise_config["Config layer<br/>route/theme/SEO config"]
  node_ratewise_features["RateWise features<br/>converter domain"]
  node_ratewise_calculator["Calculator feature<br/>interactive module"]
  node_ratewise_services["Data services<br/>rate services"]
  node_ratewise_pwa["PWA runtime<br/>browser runtime<br/>[sw.ts]"]
  node_ratewise_content["Generated content<br/>static artifacts"]
  node_ratewise_pages["SEO pages<br/>prerendered routes"]
  node_parkkeeper_services["Device services<br/>sensor/storage layer"]
  node_nihonname_data["Local datasets<br/>content/data layer"]
  node_quakeschool_lessons["Lesson data<br/>lesson/content layer"]
  node_splitmeow_store["App store<br/>state management"]
end

subgraph group_edge["Edge services"]
  node_edge_rating_api["rating-api<br/>cloudflare worker<br/>[worker.js]"]
  node_edge_security_headers["security-headers<br/>cloudflare worker<br/>[worker.js]"]
end

subgraph group_pipeline["Build pipeline"]
  node_root_ci["CI & release<br/>github actions<br/>[ci.yml]"]
  node_root_scripts["Ops scripts<br/>node/python scripts"]
  node_changesets["Changesets<br/>release governance<br/>[config.json]"]
end

node_root_workspace -->|"workspace"| node_haotool
node_root_workspace -->|"workspace"| node_nihonname
node_root_workspace -->|"workspace"| node_parkkeeper
node_root_workspace -->|"workspace"| node_quakeschool
node_root_workspace -->|"workspace"| node_ratewise
node_root_workspace -->|"workspace"| node_splitmeow
node_root_workspace -->|"shared lib"| node_shared_analytics
node_root_ci -->|"orchestrates"| node_root_scripts
node_changesets -->|"releases"| node_root_ci
node_ratewise -->|"uses"| node_ratewise_config
node_ratewise -->|"renders"| node_ratewise_features
node_ratewise -->|"embeds"| node_ratewise_calculator
node_ratewise -->|"reads rates"| node_ratewise_services
node_ratewise -->|"runs in browser"| node_ratewise_pwa
node_ratewise -->|"serves assets"| node_ratewise_content
node_ratewise -->|"prerenders"| node_ratewise_pages
node_ratewise_content -->|"feeds"| node_ratewise_services
node_ratewise_services -->|"supplies data"| node_ratewise_features
node_shared_analytics -->|"tracks routes"| node_ratewise
node_shared_analytics -->|"tracks routes"| node_haotool
node_nihonname -->|"uses"| node_nihonname_data
node_parkkeeper -->|"uses"| node_parkkeeper_services
node_quakeschool -->|"uses"| node_quakeschool_lessons
node_splitmeow -->|"state"| node_splitmeow_store
node_edge_rating_api -.->|"supports"| node_ratewise
node_edge_security_headers -.->|"validated by"| node_root_ci

click node_root_workspace "https://github.com/haotool/app/blob/main/pnpm-workspace.yaml"
click node_root_ci "https://github.com/haotool/app/blob/main/.github/workflows/ci.yml"
click node_root_scripts "https://github.com/haotool/app/tree/main/scripts"
click node_changesets "https://github.com/haotool/app/blob/main/.changeset/config.json"
click node_shared_analytics "https://github.com/haotool/app/tree/main/apps/shared/analytics"
click node_haotool "https://github.com/haotool/app/tree/main/apps/haotool"
click node_nihonname "https://github.com/haotool/app/tree/main/apps/nihonname"
click node_parkkeeper "https://github.com/haotool/app/tree/main/apps/park-keeper"
click node_quakeschool "https://github.com/haotool/app/tree/main/apps/quake-school"
click node_ratewise "https://github.com/haotool/app/tree/main/apps/ratewise"
click node_splitmeow "https://github.com/haotool/app/tree/main/apps/split-meow"
click node_ratewise_config "https://github.com/haotool/app/tree/main/apps/ratewise/src/config"
click node_ratewise_features "https://github.com/haotool/app/tree/main/apps/ratewise/src/features/ratewise"
click node_ratewise_calculator "https://github.com/haotool/app/tree/main/apps/ratewise/src/features/calculator"
click node_ratewise_services "https://github.com/haotool/app/tree/main/apps/ratewise/src/services"
click node_ratewise_pwa "https://github.com/haotool/app/blob/main/apps/ratewise/src/sw.ts"
click node_ratewise_content "https://github.com/haotool/app/tree/main/apps/ratewise/public/api"
click node_ratewise_pages "https://github.com/haotool/app/tree/main/apps/ratewise/src/pages"
click node_parkkeeper_services "https://github.com/haotool/app/tree/main/apps/park-keeper/src/services"
click node_nihonname_data "https://github.com/haotool/app/tree/main/apps/nihonname/src/data"
click node_quakeschool_lessons "https://github.com/haotool/app/tree/main/apps/quake-school/src/data"
click node_splitmeow_store "https://github.com/haotool/app/tree/main/apps/split-meow/src/store"
click node_edge_rating_api "https://github.com/haotool/app/blob/main/rating-api/src/worker.js"
click node_edge_security_headers "https://github.com/haotool/app/blob/main/security-headers/src/worker.js"

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_root_workspace toneBlue
class node_shared_analytics,node_haotool,node_nihonname,node_parkkeeper,node_quakeschool,node_ratewise,node_splitmeow,node_ratewise_config,node_ratewise_features,node_ratewise_calculator,node_ratewise_services,node_ratewise_pwa,node_ratewise_content,node_ratewise_pages,node_parkkeeper_services,node_nihonname_data,node_quakeschool_lessons,node_splitmeow_store toneAmber
class node_edge_rating_api,node_edge_security_headers toneMint
class node_root_ci,node_root_scripts,node_changesets toneRose
```

## Components

### Workspace

Monorepo-wide setup, shared tooling, and governance.

- [pnpm workspace](https://github.com/haotool/app/blob/main/pnpm-workspace.yaml): monorepo root · Workspace manifests, TypeScript base config, and repo-wide conventions. · `pnpm-workspace.yaml`

### React apps

Independently deployable app surfaces under apps/*.

- [Shared analytics](https://github.com/haotool/app/tree/main/apps/shared/analytics): cross-app lib · Reusable route tracking and GA integration shared by multiple apps. · `apps/shared/analytics`
- [haotool shell](https://github.com/haotool/app/tree/main/apps/haotool): marketing React app · Lightweight showcase/home surface for the product family with hero and project navigation. · `apps/haotool`
- [NihonName](https://github.com/haotool/app/tree/main/apps/nihonname): content React app · Curated surname and pun-name content app with local datasets and historical pages. · `apps/nihonname`
- [Park Keeper](https://github.com/haotool/app/tree/main/apps/park-keeper): PWA React app · Browser-device integrated parking app with geolocation, orientation, map caching, and update prompting. · `apps/park-keeper`
- [Quake-School](https://github.com/haotool/app/tree/main/apps/quake-school): educational React app · Interactive earthquake lessons, simulators, quizzes, and visual explanations. · `apps/quake-school`
- [RateWise](https://github.com/haotool/app/tree/main/apps/ratewise): SEO PWA app · System-like exchange-rate app with converter UI, generated artifacts, offline support, and SEO-heavy surface. · `apps/ratewise`
- [Split Meow](https://github.com/haotool/app/tree/main/apps/split-meow): mobile utility app · Stateful expense-splitting app with calculator, member/payer management, and app-like browser features. · `apps/split-meow`
- [Config layer](https://github.com/haotool/app/tree/main/apps/ratewise/src/config): route/theme/SEO config · Central registry for routes, themes, SEO metadata, providers, and build-time semantics. · `apps/ratewise/src/config`
- [RateWise features](https://github.com/haotool/app/tree/main/apps/ratewise/src/features/ratewise): converter domain · Core converter and rate-selection experience that powers the main product workflows. · `apps/ratewise/src/features/ratewise`
- [Calculator feature](https://github.com/haotool/app/tree/main/apps/ratewise/src/features/calculator): interactive module · Currency calculator UI and behavior, including keyboard, validation, and easter eggs. · `apps/ratewise/src/features/calculator`
- [Data services](https://github.com/haotool/app/tree/main/apps/ratewise/src/services): rate services · Exchange-rate and MoneyBox fetch/aggregation services consumed by the UI and SEO content. · `apps/ratewise/src/services`
- [PWA runtime](https://github.com/haotool/app/blob/main/apps/ratewise/src/sw.ts): browser runtime · Service worker, offline recovery, hydration safety, and update/install behavior. · `apps/ratewise/src/sw.ts`
- [Generated content](https://github.com/haotool/app/tree/main/apps/ratewise/public/api): static artifacts · Committed/generated API, rates, SEO, and helper assets served from public and generated config. · `apps/ratewise/public/api`
- [SEO pages](https://github.com/haotool/app/tree/main/apps/ratewise/src/pages): prerendered routes · Currency landing pages, guides, FAQs, and supporting informational surfaces. · `apps/ratewise/src/pages`
- [Device services](https://github.com/haotool/app/tree/main/apps/park-keeper/src/services): sensor/storage layer · Geolocation, orientation, map tile caching, storage, and image utilities. · `apps/park-keeper/src/services`
- [Local datasets](https://github.com/haotool/app/tree/main/apps/nihonname/src/data): content/data layer · Surname CSV, pun-name data, and romaji/content transformation utilities. · `apps/nihonname/src/data`
- [Lesson data](https://github.com/haotool/app/tree/main/apps/quake-school/src/data): lesson/content layer · Structured lessons and supporting educational content for interactive learning flows. · `apps/quake-school/src/data`
- [App store](https://github.com/haotool/app/tree/main/apps/split-meow/src/store): state management · Central store and expression/business logic for trip splitting and mobile utility flows. · `apps/split-meow/src/store`

### Edge services

Non-React runtime services and security headers.

- [rating-api](https://github.com/haotool/app/blob/main/rating-api/src/worker.js): cloudflare worker · Edge worker package for rating-related API behavior outside the React apps. · `rating-api/src/worker.js`
- [security-headers](https://github.com/haotool/app/blob/main/security-headers/src/worker.js): cloudflare worker · Edge worker package for security header policy and deployment. · `security-headers/src/worker.js`

### Build pipeline

Scripts, CI, releases, SEO, and rate/content generation.

- [CI & release](https://github.com/haotool/app/blob/main/.github/workflows/ci.yml): github actions · Repository automation for CI, release automation, SEO audits, and production governance. · `.github/workflows/ci.yml`
- [Ops scripts](https://github.com/haotool/app/tree/main/scripts): node/python scripts · Repo-level maintenance scripts for SEO, deployment, verification, caching, and rate updates. · `scripts`
- [Changesets](https://github.com/haotool/app/blob/main/.changeset/config.json): release governance · Versioning, changelog, and release source of truth. · `.changeset/config.json`

## Connections

- pnpm workspace → haotool shell: workspace · Monorepo workspace includes the showcase app.
- pnpm workspace → NihonName: workspace · Monorepo workspace includes the content app.
- pnpm workspace → Park Keeper: workspace · Monorepo workspace includes the park app.
- pnpm workspace → Quake-School: workspace · Monorepo workspace includes the education app.
- pnpm workspace → RateWise: workspace · Monorepo workspace includes the main system-like app.
- pnpm workspace → Split Meow: workspace · Monorepo workspace includes the utility app.
- pnpm workspace → Shared analytics: shared lib · Shared analytics package is available to app surfaces.
- CI & release → Ops scripts: orchestrates · CI invokes repo scripts for validation, SEO, and deployment checks.
- Changesets → CI & release: releases · Versioning and changelog governance feed release automation.
- RateWise → Config layer: uses · RateWise routes, themes, SEO, and provider registries come from config.
- RateWise → RateWise features: renders · Main UI is composed from converter and rate-selection features.
- RateWise → Calculator feature: embeds · Converter flows can open the calculator subsystem.
- RateWise → Data services: reads rates · UI and landing pages consume exchange-rate services.
- RateWise → PWA runtime: runs in browser · Offline support, recovery, and update behavior are first-class runtime concerns.
- RateWise → Generated content: serves assets · App is backed by committed/generated API, SEO, and rate artifacts.
- RateWise → SEO pages: prerenders · SEO landing pages and informational routes form the public surface.
- Generated content → Data services: feeds · Generated rate snapshots and artifacts are consumed by services.
- Data services → RateWise features: supplies data · Services provide rate histories, quotes, and provider data to the UI.
- Shared analytics → RateWise: tracks routes · Shared analytics supports navigation and GA integration.
- Shared analytics → haotool shell: tracks routes · Shared analytics supports the showcase app.
- NihonName → Local datasets: uses · Content pages and transforms are driven by local datasets.
- Park Keeper → Device services: uses · UI workflows rely on device sensing, caching, and storage services.
- Quake-School → Lesson data: uses · Interactive lessons and quizzes are built from lesson data.
- Split Meow → App store: state · Trip splitting and calculator interactions are centralized in the store.
- rating-api → RateWise: supports · Edge API behavior complements RateWise content and rate delivery.
- security-headers → CI & release: validated by · Security header behavior is governed through repo automation and checks.
