How haotool/app works
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: ratewise RateWise · pnpm-workspace.yaml pnpm workspace · analytics Shared analytics · services Data services
Components 24
Workspace
Monorepo-wide setup, shared tooling, and governance.
- pnpm workspace · Workspace manifests, TypeScript base config, and repo-wide conventions.
pnpm-workspace.yaml
React apps
Independently deployable app surfaces under apps/*.
- Shared analytics · Reusable route tracking and GA integration shared by multiple apps.
apps/shared/analytics - haotool shell · Lightweight showcase/home surface for the product family with hero and project navigation.
apps/haotool - NihonName · Curated surname and pun-name content app with local datasets and historical pages.
apps/nihonname - Park Keeper · Browser-device integrated parking app with geolocation, orientation, map caching, and update prompting.
apps/park-keeper - Quake-School · Interactive earthquake lessons, simulators, quizzes, and visual explanations.
apps/quake-school - RateWise · System-like exchange-rate app with converter UI, generated artifacts, offline support, and SEO-heavy surface.
apps/ratewise - Split Meow · Stateful expense-splitting app with calculator, member/payer management, and app-like browser features.
apps/split-meow - Config layer · Central registry for routes, themes, SEO metadata, providers, and build-time semantics.
apps/ratewise/src/config - RateWise features · Core converter and rate-selection experience that powers the main product workflows.
apps/ratewise/src/features/ratewise - Calculator feature · Currency calculator UI and behavior, including keyboard, validation, and easter eggs.
apps/ratewise/src/features/calculator - Data services · Exchange-rate and MoneyBox fetch/aggregation services consumed by the UI and SEO content.
apps/ratewise/src/services - PWA runtime · Service worker, offline recovery, hydration safety, and update/install behavior.
apps/ratewise/src/sw.ts - Generated content · Committed/generated API, rates, SEO, and helper assets served from public and generated config.
apps/ratewise/public/api - SEO pages · Currency landing pages, guides, FAQs, and supporting informational surfaces.
apps/ratewise/src/pages - Device services · Geolocation, orientation, map tile caching, storage, and image utilities.
apps/park-keeper/src/services - Local datasets · Surname CSV, pun-name data, and romaji/content transformation utilities.
apps/nihonname/src/data - Lesson data · Structured lessons and supporting educational content for interactive learning flows.
apps/quake-school/src/data - App store · 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 · Edge worker package for rating-related API behavior outside the React apps.
rating-api/src/worker.js - security-headers · 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 · Repository automation for CI, release automation, SEO audits, and production governance.
.github/workflows/ci.yml - Ops scripts · Repo-level maintenance scripts for SEO, deployment, verification, caching, and rate updates.
scripts - Changesets · Versioning, changelog, and release source of truth.
.changeset/config.json
Connections 26
- 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.