# k1105/petamp architecture

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

- Interactive diagram: https://gitdiagram.com/k1105/petamp
- Repository: https://github.com/k1105/petamp

## Overview

1. This repo is a single React + TypeScript frontend built with Vite, but it is not “just a web app”: it is also packaged for iOS via Capacitor. The architecture is a client-heavy app with local persistence, Firebase-backed sync, GPS/location capture, and an AI-driven character/chat subsystem.

2. The app shell lives in `src/main.tsx`, `src/App.tsx`, and the page components under `src/pages`. Those pages represent the main product surfaces: recording a run, viewing a run, gallery/profile/social views, onboarding, invite flows, chat views, prompt logs, and a shape editor. The route/page layer is the top boundary that assembles feature subsystems.

3. Global UI state is split into dedicated stores in `src/store` rather than one monolithic state container. The stores suggest clear domains: boot/loading, GPS capture, map state, run state, settings, social feed, and transition/UI animation state. This is the main orchestration layer that feeds data into pages and feature components.

4. The run-recording pipeline is a core subsystem. Hooks such as `useCurrentPosition`, `useGpsRecorder`, `useGeolocationPermission`, `useElevationStats`, `useReverseGeocode`, and `useWeather` indicate that the app collects live location data, enriches it with elevation/geocoding/weather, and then stores it. Supporting utilities like `kalmanGps`, `altitudeFilters`, `recordingFilters`, `simplify`, `runSegments`, `runTopology`, and `runStatsAggregate` show that GPS traces are normalized and analyzed before being shown or synced.

5. Run data persistence is split between local and cloud boundaries. Local run storage appears in `src/db/runRepository.ts` and run-related Zustand state, while Firebase modules in `src/firebase/runCloud.ts`, `characterCloud.ts`, `userCloud.ts`, and `friends.ts` handle backend synchronization and social data. `src/firebase/compositeMemoryStore.ts` and `src/character/memory/idbMemoryStore.ts` suggest that some data is intentionally stored offline-first in IndexedDB and then merged with remote state.

6. There is a dedicated “character” AI subsystem under `src/character`. It is not just UI chat: it has domain models (`character`, `dialogue`, `memory`, `runSummary`, `placeProximity`), a prompt system (`systemPrompt`, `summaryPrompt`, schemas/templates), a context builder, a dialogue service abstraction, and a Gemini client implementation. This indicates a clean separation between AI orchestration and the rest of the app.

7. The character subsystem also includes memory and logging. Prompt logs are captured locally via `localStoragePromptLogStore`, while `memory` uses an IndexedDB-backed store. Hooks such as `useCharacterDialogue` and the sync layer in Firebase suggest that conversational state and run summaries can be generated from user activity, stored locally, and selectively synchronized.

8. The app has a separate analysis/representation layer for runs called “notation” in `src/notation`. It includes context, detectors, and strategies, plus pages like `NotationChatPage` and `ShapeEditorPage`. This looks like a domain for classifying or interpreting run paths into symbolic forms, likely used by the chat/character layer and the visualization layer.

9. Visualization is split into several feature families. `src/components/map` handles map rendering, labels, overlays, constraints, and debug panels; `src/components/island` and `src/utils/archipelagoLayout` suggest a stylized spatial view of runs as islands/archipelagos; `src/components/gallery` and `src/components/detail` render run tiles, stats, and animations. These components consume the analyzed run data rather than raw GPS points.

10. Social and identity flows are Firebase-centered. `src/firebase/auth.ts` manages sign-in, `useEnsureUserDoc` ensures the user profile exists, `friends.ts` and `userCloud.ts` back friend/invite features, and `src/pages/InvitePage.tsx` plus profile tabs indicate a social graph on top of the core run product. Firestore rules are present, so backend access control is part of the architecture.

11. Mobile-native concerns matter. The `ios/` project, `GoogleService-Info.plist`, and a patch for `@capacitor-community/background-geolocation` show that continuous or background GPS behavior is a first-class requirement. The app therefore spans browser-style React UI and native iOS capabilities through Capacitor.

12. The system is heavily utility-driven, with most computation in `src/utils`. These utilities cover geometry, bounding boxes, pace distributions, segments, path rendering, grouping, trail/topology calculations, and theme/palette selection. This tells you that a lot of the “business logic” is pure data transformation, which makes the architecture diagram should emphasize flows from raw track points to enriched analytics to UI surfaces.

13. Bootstrapping and synchronization are likely staged: app launch initializes auth/user state, then loads settings and run/social data, then enables recording and character features once permissions and backend state are ready. `useBootStore`, `useAuth`, `useApplyTheme`, and `useCharacterMemorySync` suggest the startup path coordinates both UI readiness and data sync readiness.

14. There are also operational/support pieces outside the main runtime: a migration script for converting follows to friends, a run-grouping design doc, and several JSON exports of track points/reports. These indicate the repo includes data migration and analysis workflows alongside the live app, which is useful if you are drawing boundaries between runtime features and offline tooling.

Main entry points: [`src/App.tsx`](https://github.com/k1105/petamp/blob/main/src/App.tsx) (App), [`src/store/useBootStore.ts`](https://github.com/k1105/petamp/blob/main/src/store/useBootStore.ts) (Boot store), [`src/store/useRunStore.ts`](https://github.com/k1105/petamp/blob/main/src/store/useRunStore.ts) (Run store), [`src/firebase/client.ts`](https://github.com/k1105/petamp/blob/main/src/firebase/client.ts) (Firebase sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["App Shell"]
  node_src_main["main<br/>React entry<br/>[main.tsx]"]
  node_src_app["App<br/>Shell/router<br/>[App.tsx]"]
  node_src_pages["Pages<br/>Route surfaces"]
end

subgraph group_state["State & Boot"]
  node_src_boot_store[("Boot store<br/>Startup state<br/>[useBootStore.ts]")]
  node_src_run_store[("Run store<br/>Run state<br/>[useRunStore.ts]")]
  node_src_gps_store[("GPS store<br/>Capture state<br/>[useGpsStore.ts]")]
  node_src_map_store[("Map store<br/>Map state<br/>[useMapStore.ts]")]
  node_src_settings_store[("Settings<br/>Prefs state")]
  node_src_social_store[("Social feed<br/>Social state")]
  node_src_transition_store[("Transitions<br/>UI motion")]
end

subgraph group_recording["Run Recording"]
  node_src_hooks_recording["Capture hooks<br/>GPS pipeline<br/>[useGpsRecorder.ts]"]
  node_src_utils_recording["Track utils<br/>Track transforms<br/>[runSegments.ts]"]
end

subgraph group_data["Persistence & Sync"]
  node_src_db_repo[("Run repo<br/>Local store<br/>[runRepository.ts]")]
  node_src_firebase[("Firebase sync<br/>Cloud backend<br/>[client.ts]")]
end

subgraph group_character["Character AI"]
  node_src_character_core["Character core<br/>AI domain<br/>[index.ts]"]
  node_src_character_memory[("Memory store<br/>Offline memory<br/>[idbMemoryStore.ts]")]
  node_src_character_hooks["Dialogue hook<br/>AI hook"]
end

subgraph group_notation["Notation"]
  node_src_notation["Notation<br/>Interpretation<br/>[index.ts]"]
end

subgraph group_viz["Visualization UI"]
  node_src_viz["UI views<br/>Visual surfaces<br/>[BaseMap.tsx]"]
end

subgraph group_mobile["Mobile Native"]
  node_src_mobile["iOS shell<br/>Capacitor+iOS<br/>[AppDelegate.swift]"]
end

node_src_main -->|"mounts"| node_src_app
node_src_app -->|"routes to"| node_src_pages
node_src_app -->|"initializes"| node_src_boot_store
node_src_app -->|"reads prefs"| node_src_settings_store
node_src_app -->|"animates"| node_src_transition_store
node_src_boot_store -->|"auth/user"| node_src_firebase
node_src_boot_store -->|"hydrates"| node_src_run_store
node_src_boot_store -->|"hydrates"| node_src_social_store
node_src_run_store -->|"persists"| node_src_db_repo
node_src_run_store -->|"syncs"| node_src_firebase
node_src_gps_store -->|"feeds"| node_src_hooks_recording
node_src_hooks_recording -->|"normalizes"| node_src_utils_recording
node_src_hooks_recording -->|"emits"| node_src_run_store
node_src_utils_recording -->|"renders"| node_src_viz
node_src_firebase -->|"syncs"| node_src_character_core
node_src_character_core -->|"stores memory"| node_src_character_memory
node_src_character_hooks -->|"drives dialogue"| node_src_character_core
node_src_character_core -->|"consumes"| node_src_notation
node_src_notation -->|"shapes UI"| node_src_viz
node_src_firebase -->|"backs"| node_src_social_store
node_src_mobile -->|"hosts"| node_src_app

click node_src_main "https://github.com/k1105/petamp/blob/main/src/main.tsx"
click node_src_app "https://github.com/k1105/petamp/blob/main/src/App.tsx"
click node_src_pages "https://github.com/k1105/petamp/tree/main/src/pages"
click node_src_boot_store "https://github.com/k1105/petamp/blob/main/src/store/useBootStore.ts"
click node_src_run_store "https://github.com/k1105/petamp/blob/main/src/store/useRunStore.ts"
click node_src_gps_store "https://github.com/k1105/petamp/blob/main/src/store/useGpsStore.ts"
click node_src_map_store "https://github.com/k1105/petamp/blob/main/src/store/useMapStore.ts"
click node_src_settings_store "https://github.com/k1105/petamp/blob/main/src/store/useSettingsStore.ts"
click node_src_social_store "https://github.com/k1105/petamp/blob/main/src/store/useSocialFeedStore.ts"
click node_src_transition_store "https://github.com/k1105/petamp/blob/main/src/store/useTransitionStore.ts"
click node_src_hooks_recording "https://github.com/k1105/petamp/blob/main/src/hooks/useGpsRecorder.ts"
click node_src_utils_recording "https://github.com/k1105/petamp/blob/main/src/utils/runSegments.ts"
click node_src_db_repo "https://github.com/k1105/petamp/blob/main/src/db/runRepository.ts"
click node_src_firebase "https://github.com/k1105/petamp/blob/main/src/firebase/client.ts"
click node_src_character_core "https://github.com/k1105/petamp/blob/main/src/character/index.ts"
click node_src_character_memory "https://github.com/k1105/petamp/blob/main/src/character/memory/idbMemoryStore.ts"
click node_src_character_hooks "https://github.com/k1105/petamp/blob/main/src/character/hooks/useCharacterDialogue.ts"
click node_src_notation "https://github.com/k1105/petamp/blob/main/src/notation/index.ts"
click node_src_viz "https://github.com/k1105/petamp/blob/main/src/components/map/BaseMap.tsx"
click node_src_mobile "https://github.com/k1105/petamp/blob/main/ios/App/App/AppDelegate.swift"

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_src_main,node_src_app,node_src_pages,node_src_viz toneBlue
class node_src_boot_store,node_src_run_store,node_src_gps_store,node_src_map_store,node_src_settings_store,node_src_social_store,node_src_transition_store,node_src_mobile toneAmber
class node_src_hooks_recording,node_src_utils_recording toneMint
class node_src_db_repo,node_src_firebase toneRose
class node_src_character_core,node_src_character_memory,node_src_character_hooks toneIndigo
class node_src_notation toneTeal
```

## Components

### App Shell

Entry, routing, and top-level page assembly

- [main](https://github.com/k1105/petamp/blob/main/src/main.tsx): React entry · Bootstraps the app and mounts the root UI · `src/main.tsx`
- [App](https://github.com/k1105/petamp/blob/main/src/App.tsx): Shell/router · Top-level app composition and route wiring · `src/App.tsx`
- [Pages](https://github.com/k1105/petamp/tree/main/src/pages): Route surfaces · User-facing screens for recording, chat, gallery, onboarding, invites, and editor flows · `src/pages`

### State & Boot

Global orchestration stores and startup coordination

- [Boot store](https://github.com/k1105/petamp/blob/main/src/store/useBootStore.ts): Startup state · Coordinates initial loading and readiness · `src/store/useBootStore.ts`
- [Run store](https://github.com/k1105/petamp/blob/main/src/store/useRunStore.ts): Run state · Holds run lifecycle and captured run data · `src/store/useRunStore.ts`
- [GPS store](https://github.com/k1105/petamp/blob/main/src/store/useGpsStore.ts): Capture state · Tracks live location and recording-related GPS state · `src/store/useGpsStore.ts`
- [Map store](https://github.com/k1105/petamp/blob/main/src/store/useMapStore.ts): Map state · Controls map view state and centering · `src/store/useMapStore.ts`
- [Settings](https://github.com/k1105/petamp/blob/main/src/store/useSettingsStore.ts): Prefs state · Persists app preferences and user settings · `src/store/useSettingsStore.ts`
- [Social feed](https://github.com/k1105/petamp/blob/main/src/store/useSocialFeedStore.ts): Social state · Manages feed/invite/social UI state · `src/store/useSocialFeedStore.ts`
- [Transitions](https://github.com/k1105/petamp/blob/main/src/store/useTransitionStore.ts): UI motion · Controls transition and overlay animation state · `src/store/useTransitionStore.ts`

### Run Recording

Live GPS capture, enrichment, and track processing

- [Capture hooks](https://github.com/k1105/petamp/blob/main/src/hooks/useGpsRecorder.ts): GPS pipeline · Live position, permission, recorder, elevation, geocoding, and weather hooks · `src/hooks/useGpsRecorder.ts`
- [Track utils](https://github.com/k1105/petamp/blob/main/src/utils/runSegments.ts): Track transforms · Filters, simplification, segmentation, topology, and stats aggregation for raw traces · `src/utils/runSegments.ts`

### Persistence & Sync

Local storage, Firebase sync, and social backend

- [Run repo](https://github.com/k1105/petamp/blob/main/src/db/runRepository.ts): Local store · Local run persistence boundary · `src/db/runRepository.ts`
- [Firebase sync](https://github.com/k1105/petamp/blob/main/src/firebase/client.ts): Cloud backend · Auth, run sync, character sync, friends, and user documents · `src/firebase/client.ts`

### Character AI

Dialogue, memory, prompts, and LLM integration

- [Character core](https://github.com/k1105/petamp/blob/main/src/character/index.ts): AI domain · Character models, dialogue, memory, prompts, context, and service abstractions · `src/character/index.ts`
- [Memory store](https://github.com/k1105/petamp/blob/main/src/character/memory/idbMemoryStore.ts): Offline memory · IndexedDB and composite memory persistence for character state · `src/character/memory/idbMemoryStore.ts`
- [Dialogue hook](https://github.com/k1105/petamp/blob/main/src/character/hooks/useCharacterDialogue.ts): AI hook · React hook that drives character conversation flows · `src/character/hooks/useCharacterDialogue.ts`

### Notation

Run interpretation and symbolic analysis

- [Notation](https://github.com/k1105/petamp/blob/main/src/notation/index.ts): Interpretation · Context, detectors, strategies, and notation types for run meaning-making · `src/notation/index.ts`

### Visualization UI

Map, gallery, detail, and recording surfaces

- [UI views](https://github.com/k1105/petamp/blob/main/src/components/map/BaseMap.tsx): Visual surfaces · Map, island, gallery, recording, profile, and detail components · `src/components/map/BaseMap.tsx`

### Mobile Native

Capacitor and iOS packaging

- [iOS shell](https://github.com/k1105/petamp/blob/main/ios/App/App/AppDelegate.swift): Capacitor+iOS · Native iOS project and Capacitor packaging · `ios/App/App/AppDelegate.swift`

## Connections

- main → App: mounts · Main entry mounts the root application
- App → Pages: routes to · App shell selects the major user-facing pages
- App → Boot store: initializes · App startup depends on boot/readiness state
- App → Settings: reads prefs · Theme and other preferences influence shell behavior
- App → Transitions: animates · Global transition state drives overlays and motion
- Boot store → Firebase sync: auth/user · Boot sequence waits on authentication and backend readiness
- Boot store → Run store: hydrates · Boot loads core run state
- Boot store → Social feed: hydrates · Boot loads social/feed state
- Run store → Run repo: persists · Run state writes to local repository
- Run store → Firebase sync: syncs · Run state can be synchronized to cloud services
- GPS store → Capture hooks: feeds · Live GPS capture is driven by recorder and permission hooks
- Capture hooks → Track utils: normalizes · Raw points are filtered, simplified, and segmented
- Capture hooks → Run store: emits · Recorded track data updates run state
- Track utils → UI views: renders · Processed tracks feed map, detail, and gallery views
- Firebase sync → Character core: syncs · Cloud services move character and user data between devices
- Character core → Memory store: stores memory · Character memory is backed by offline-first storage
- Dialogue hook → Character core: drives dialogue · Hook orchestrates prompt/context/service interactions
- Character core → Notation: consumes · Run interpretation informs character reasoning and summaries
- Notation → UI views: shapes UI · Notation-derived forms feed chat, editor, and visualization screens
- Firebase sync → Social feed: backs · Friends/invite/user data support social features
- iOS shell → App: hosts · Native iOS wrapper hosts the web app through Capacitor
