How k1105/petamp works
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: App.tsx App · useBootStore.ts Boot store · useRunStore.ts Run store · client.ts Firebase sync
Components 20
App Shell
Entry, routing, and top-level page assembly
State & Boot
Global orchestration stores and startup coordination
- Boot store · Coordinates initial loading and readiness
src/store/useBootStore.ts - Run store · Holds run lifecycle and captured run data
src/store/useRunStore.ts - GPS store · Tracks live location and recording-related GPS state
src/store/useGpsStore.ts - Map store · Controls map view state and centering
src/store/useMapStore.ts - Settings · Persists app preferences and user settings
src/store/useSettingsStore.ts - Social feed · Manages feed/invite/social UI state
src/store/useSocialFeedStore.ts - Transitions · Controls transition and overlay animation state
src/store/useTransitionStore.ts
Run Recording
Live GPS capture, enrichment, and track processing
- Capture hooks · Live position, permission, recorder, elevation, geocoding, and weather hooks
src/hooks/useGpsRecorder.ts - Track utils · 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 · Local run persistence boundary
src/db/runRepository.ts - Firebase sync · Auth, run sync, character sync, friends, and user documents
src/firebase/client.ts
Character AI
Dialogue, memory, prompts, and LLM integration
- Character core · Character models, dialogue, memory, prompts, context, and service abstractions
src/character/index.ts - Memory store · IndexedDB and composite memory persistence for character state
src/character/memory/idbMemoryStore.ts - Dialogue hook · React hook that drives character conversation flows
src/character/hooks/useCharacterDialogue.ts
Notation
Run interpretation and symbolic analysis
- Notation · Context, detectors, strategies, and notation types for run meaning-making
src/notation/index.ts
Visualization UI
Map, gallery, detail, and recording surfaces
- UI views · Map, island, gallery, recording, profile, and detail components
src/components/map/BaseMap.tsx
Mobile Native
Capacitor and iOS packaging
- iOS shell · Native iOS project and Capacitor packaging
ios/App/App/AppDelegate.swift
Connections 21
- 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