# realtruenorth/purzoot architecture

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

- Interactive diagram: https://gitdiagram.com/realtruenorth/purzoot
- Repository: https://github.com/realtruenorth/purzoot

## Overview

1. **This is a monorepo with three major runtime surfaces**
   - The main product app in `src/` is the primary React 18 + Vite frontend.
   - `server/` is a separate Node/TypeScript API and database service.
   - `admin-console/` is a distinct React/Vite admin app.
   - Shared contracts and utilities live in `packages/`, while data/seed pipelines live under `data/activity-atlas/`.

2. **The main app is organized as a route-first product spine**
   - `src/App.tsx` and `src/pages/` define the user-facing routes: public discovery, signed-in participation, creator flows, partner flows, ops pages, and legal/info pages.
   - The UI is split into large feature areas: social, live/realtime, participation, creator, ops, media-plane, and landing/discovery.
   - This is not a single-purpose app; it is the primary shell for multiple product surfaces sharing one navigation and domain model.

3. **The core product model is local-first and Moment-centric**
   - The README’s key flow is: `Session -> Proof -> Moment`.
   - In code, that model is supported by `src/lib/moments.ts`, `src/lib/feedSurface.ts`, `src/lib/sessionArchive.ts`, `src/lib/publicMetadata.ts`, and related domain helpers.
   - A central architectural boundary is that sessions, sync state, and publish/visibility state are independent, so the app can keep private local capture separate from eventual publishing.

4. **Persistence is split by environment via provider boundaries**
   - `src/platform/providers/` defines abstract provider interfaces for auth, analytics, chat, live, media storage, payments, and search.
   - Concrete implementations include local/mock versions and cloud-backed versions such as Amplify auth, IVS chat/live, S3 media storage, and EventBridge analytics.
   - This provider layer is the main seam between local-first behavior and cloud integrations.

5. **Offline-first behavior is a first-class subsystem**
   - `src/lib/sync/syncEngine.ts`, `src/sw.ts`, and storage helpers in `src/lib/data/` support offline mutation queuing, local persistence, and service-worker/PWA behavior.
   - Local data is stored in browser-backed mechanisms such as IndexedDB/localStorage, with sync and replay handled separately from UI rendering.
   - This means the app can function as a standalone local prototype even when cloud services are unavailable.

6. **The server is a separate canonical data/API boundary**
   - `server/src/index.ts` starts a Node service that owns API handling, security checks, admin auth, request validation, and PostgreSQL access.
   - Database access is encapsulated in `server/src/db/` and repository code such as `PostgresCanonicalRepository.ts`.
   - Migrations live in `server/src/db/migrations/`, so canonical server-side state is explicitly versioned and schema-managed.

7. **The server also hosts the shared canonical/partner spine**
   - `server/src/partnerSpine.ts`, `server/src/activityAtlasAdmin.ts`, and the migration set show that the backend is not just generic CRUD; it owns canonical activity atlas and partner-spine data structures.
   - Tests for admin auth, API validation, and HTTP security indicate that the backend boundary is responsible for access control and contract correctness.
   - The OpenAPI file in `openapi/` documents the partner API surface as a separate contract.

8. **Activity Atlas is a major data pipeline subsystem**
   - Under `data/activity-atlas/` there is a full ingestion, normalization, deduplication, validation, generation, and import pipeline.
   - Sources flow from raw/manual and raw/wikidata into canonical CSV/JSON artifacts, then into generated search documents and seed files, and finally into SQL import/migration paths.
   - This subsystem feeds both the database schema and the app’s discovery/categorization surfaces.

9. **The admin console is a separate authenticated operational UI**
   - `admin-console/` is its own React app with dedicated auth, query, and layout layers.
   - It uses Cognito/Amplify configuration, admin session handling, and modular pages for diagnostics, feature flags, platform health, sessions, proof, moments, and audit log review.
   - Architecturally, it is an operations/control-plane UI rather than part of the end-user app.

10. **Shared packages provide reusable contracts, not just UI code**
   - `packages/purzoot-schema` contains versioned JSON Schemas and valid/invalid fixtures for canonical objects like moment, proof, session, channel, community, partner, and webhooks.
   - `packages/purzoot-sdk` and `packages/purzoot-cli` suggest a public/shared interface layer for programmatic integration and validation.
   - These packages define the stable boundary between app, server, data pipeline, and external integrators.

11. **AWS and live-media integrations are scaffolded behind adapters**
   - Amplify resources in `amplify/` and outputs in `amplify_outputs.json` support auth/data/storage integration.
   - Live, chat, and media flows are abstracted behind adapters for IVS, OBS, Meta, Strava, payments, and recommendations.
   - The architecture intentionally keeps these integrations swappable through provider abstractions rather than hard-coding them into the UI.

12. **Operational tooling and quality gates are part of the system architecture**
   - The repo includes health workflows, security workflows, database-health checks, Playwright E2E tests, Vitest unit tests, and repo-level health commands.
   - `docker-compose.yml`, environment examples, and deployment safety docs show a local reproducible posture with explicit DB and CI validation.
   - For a diagram, treat these as the validation/control plane around the app and backend rather than core product logic.

13. **Primary data flows to draw**
   - User interaction starts in the React app, writes to local persistence, and later syncs through the offline queue to the server/cloud.
   - Discovery and feed surfaces consume Moment/Session/Proof projections from local data and canonical server-backed data.
   - Admin and ops surfaces read from backend/stateful services to inspect, moderate, reconcile, and repair records.
   - Activity Atlas flows from raw source data into canonical taxonomy assets, then into the database and app-facing search/discovery surfaces.

14. **Important boundaries to keep distinct in the diagram**
   - Public app vs admin console.
   - Local-first browser state vs server canonical state.
   - Provider interfaces vs cloud/local implementations.
   - Product UI vs operational/control-plane tools.
   - Canonical schemas/data pipelines vs generated seed/runtime app data.

Main entry points: [`server/src/index.ts`](https://github.com/realtruenorth/purzoot/blob/main/server/src/index.ts) (API server), [`server/src/db/client.ts`](https://github.com/realtruenorth/purzoot/blob/main/server/src/db/client.ts) (DB layer), [`src/pages`](https://github.com/realtruenorth/purzoot/tree/main/src/pages) (Routes), [`src/platform/providers/auth/AuthProvider.ts`](https://github.com/realtruenorth/purzoot/blob/main/src/platform/providers/auth/AuthProvider.ts) (Providers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public_app["Public app"]
  node_app_shell["App shell<br/>react entry<br/>[App.tsx]"]
  node_route_pages["Routes"]
  node_moments_model["Moments<br/>domain model<br/>[moments.ts]"]
  node_feed_surface["Feed<br/>projection layer<br/>[feedSurface.ts]"]
  node_session_archive["Session archive<br/>local archive<br/>[sessionArchive.ts]"]
  node_sync_engine["Sync engine<br/>offline sync<br/>[syncEngine.ts]"]
  node_provider_seam["Providers<br/>runtime seam<br/>[AuthProvider.ts]"]
  node_cloud_adapters["Cloud adapters<br/>service impls"]
  node_local_adapters["Local adapters<br/>mock/local impls"]
end

subgraph group_server["Server"]
  node_server_entry["API server<br/>node service<br/>[index.ts]"]
  node_server_db["DB layer<br/>postgres access<br/>[client.ts]"]
  node_canonical_repo["Canonical repo"]
  node_partner_spine["Partner spine<br/>backend domain<br/>[partnerSpine.ts]"]
  node_atlas_admin["Atlas admin<br/>backend domain"]
  node_db_migrations["Migrations<br/>schema versioning"]
end

subgraph group_admin_console["Admin console"]
  node_admin_shell["Admin shell<br/>react admin<br/>[App.tsx]"]
  node_admin_gate["Auth gate<br/>admin auth<br/>[AuthGate.tsx]"]
  node_admin_modules["Admin modules<br/>ops ui<br/>[Diagnostics.tsx]"]
end

subgraph group_shared["Shared contracts"]
  node_schema_pack["Schemas<br/>contracts<br/>[manifest.json]"]
  node_sdk_cli["SDK/CLI<br/>integrations<br/>[index.ts]"]
end

subgraph group_atlas["Activity Atlas"]
  node_atlas_pipeline["Atlas pipeline<br/>data pipeline<br/>[ingest_sources.py]"]
  node_atlas_assets["Atlas assets<br/>canonical data"]
  node_atlas_sql["Atlas SQL<br/>db bootstrap"]
end

node_app_shell -->|"renders"| node_route_pages
node_route_pages -->|"uses"| node_moments_model
node_route_pages -->|"drives"| node_feed_surface
node_moments_model -->|"persists as"| node_session_archive
node_session_archive -->|"replays through"| node_sync_engine
node_sync_engine -->|"adapts via"| node_provider_seam
node_provider_seam -->|"implements"| node_cloud_adapters
node_provider_seam -->|"implements"| node_local_adapters
node_cloud_adapters -->|"syncs with"| node_server_entry
node_local_adapters -->|"supports"| node_sync_engine
node_server_entry -->|"serves"| node_server_db
node_server_db -->|"exposes"| node_canonical_repo
node_server_entry -->|"hosts"| node_partner_spine
node_server_entry -->|"hosts"| node_atlas_admin
node_server_db -->|"versioned by"| node_db_migrations
node_admin_shell -->|"protects"| node_admin_gate
node_admin_shell -->|"navigates"| node_admin_modules
node_admin_modules -->|"queries"| node_server_entry
node_schema_pack -->|"contracts"| node_server_entry
node_schema_pack -->|"contracts"| node_app_shell
node_sdk_cli -->|"validates"| node_schema_pack
node_atlas_pipeline -->|"generates"| node_atlas_assets
node_atlas_assets -->|"imports to"| node_atlas_sql
node_atlas_sql -->|"seeds"| node_server_db
node_atlas_assets -->|"feeds"| node_feed_surface
node_atlas_pipeline -.->|"reviews"| node_admin_modules

click node_app_shell "https://github.com/realtruenorth/purzoot/blob/main/src/App.tsx"
click node_route_pages "https://github.com/realtruenorth/purzoot/tree/main/src/pages"
click node_moments_model "https://github.com/realtruenorth/purzoot/blob/main/src/lib/moments.ts"
click node_feed_surface "https://github.com/realtruenorth/purzoot/blob/main/src/lib/feedSurface.ts"
click node_session_archive "https://github.com/realtruenorth/purzoot/blob/main/src/lib/sessionArchive.ts"
click node_sync_engine "https://github.com/realtruenorth/purzoot/blob/main/src/lib/sync/syncEngine.ts"
click node_provider_seam "https://github.com/realtruenorth/purzoot/blob/main/src/platform/providers/auth/AuthProvider.ts"
click node_server_entry "https://github.com/realtruenorth/purzoot/blob/main/server/src/index.ts"
click node_server_db "https://github.com/realtruenorth/purzoot/blob/main/server/src/db/client.ts"
click node_canonical_repo "https://github.com/realtruenorth/purzoot/blob/main/server/src/repositories/PostgresCanonicalRepository.ts"
click node_partner_spine "https://github.com/realtruenorth/purzoot/blob/main/server/src/partnerSpine.ts"
click node_atlas_admin "https://github.com/realtruenorth/purzoot/blob/main/server/src/activityAtlasAdmin.ts"
click node_db_migrations "https://github.com/realtruenorth/purzoot/blob/main/server/src/db/migrations/001_canonical_v1.sql"
click node_admin_shell "https://github.com/realtruenorth/purzoot/blob/main/admin-console/src/App.tsx"
click node_admin_gate "https://github.com/realtruenorth/purzoot/blob/main/admin-console/src/auth/AuthGate.tsx"
click node_admin_modules "https://github.com/realtruenorth/purzoot/blob/main/admin-console/src/modules/diagnostics/Diagnostics.tsx"
click node_schema_pack "https://github.com/realtruenorth/purzoot/blob/main/packages/purzoot-schema/schemas/v1/manifest.json"
click node_sdk_cli "https://github.com/realtruenorth/purzoot/blob/main/packages/purzoot-sdk/src/index.ts"
click node_atlas_pipeline "https://github.com/realtruenorth/purzoot/blob/main/data/activity-atlas/scripts/ingest_sources.py"
click node_atlas_assets "https://github.com/realtruenorth/purzoot/blob/main/data/activity-atlas/canonical/canonical_activities.v0.csv"
click node_atlas_sql "https://github.com/realtruenorth/purzoot/blob/main/data/activity-atlas/sql/001_create_activity_atlas.sql"

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_app_shell,node_route_pages,node_moments_model,node_feed_surface,node_session_archive,node_sync_engine,node_provider_seam,node_cloud_adapters,node_local_adapters toneBlue
class node_server_entry,node_server_db,node_canonical_repo,node_partner_spine,node_atlas_admin,node_db_migrations toneAmber
class node_admin_shell,node_admin_gate,node_admin_modules toneMint
class node_schema_pack,node_sdk_cli toneRose
class node_atlas_pipeline,node_atlas_assets,node_atlas_sql toneIndigo
```

## Components

### Public app

Main React/Vite product experience and its local-first runtime

- [App shell](https://github.com/realtruenorth/purzoot/blob/main/src/App.tsx): react entry · Top-level product shell and route composition · `src/App.tsx`
- [Routes](https://github.com/realtruenorth/purzoot/tree/main/src/pages): product routes · User-facing route set spanning discovery, participation, creator, partner, ops, and legal pages · `src/pages`
- [Moments](https://github.com/realtruenorth/purzoot/blob/main/src/lib/moments.ts): domain model · Core Session -> Proof -> Moment model and related projections · `src/lib/moments.ts`
- [Feed](https://github.com/realtruenorth/purzoot/blob/main/src/lib/feedSurface.ts): projection layer · Discovery/feed surface built from local and canonical content · `src/lib/feedSurface.ts`
- [Session archive](https://github.com/realtruenorth/purzoot/blob/main/src/lib/sessionArchive.ts): local archive · Local-first session history and deferred publish boundary · `src/lib/sessionArchive.ts`
- [Sync engine](https://github.com/realtruenorth/purzoot/blob/main/src/lib/sync/syncEngine.ts): offline sync · Mutation queue, replay, and sync coordination for browser state · `src/lib/sync/syncEngine.ts`
- [Providers](https://github.com/realtruenorth/purzoot/blob/main/src/platform/providers/auth/AuthProvider.ts): runtime seam · Abstract provider interfaces for auth, analytics, chat, live, media, payments, and search · `src/platform/providers/auth/AuthProvider.ts`
- **Cloud adapters**: service impls · Concrete cloud-backed implementations behind the provider seam
- **Local adapters**: mock/local impls · Local and mock implementations used for offline and development modes

### Server

Canonical API, persistence, and partner/activity-atlas backend

- [API server](https://github.com/realtruenorth/purzoot/blob/main/server/src/index.ts): node service · Node/TypeScript service entrypoint and request boundary · `server/src/index.ts`
- [DB layer](https://github.com/realtruenorth/purzoot/blob/main/server/src/db/client.ts): postgres access · PostgreSQL client, migrations, and repository access · `server/src/db/client.ts`
- [Canonical repo](https://github.com/realtruenorth/purzoot/blob/main/server/src/repositories/PostgresCanonicalRepository.ts): repository · Server-side canonical data repository implementation · `server/src/repositories/PostgresCanonicalRepository.ts`
- [Partner spine](https://github.com/realtruenorth/purzoot/blob/main/server/src/partnerSpine.ts): backend domain · Partner and canonical activity-spine logic · `server/src/partnerSpine.ts`
- [Atlas admin](https://github.com/realtruenorth/purzoot/blob/main/server/src/activityAtlasAdmin.ts): backend domain · Backend support for activity atlas administration · `server/src/activityAtlasAdmin.ts`
- [Migrations](https://github.com/realtruenorth/purzoot/blob/main/server/src/db/migrations/001_canonical_v1.sql): schema versioning · Versioned canonical, partner, and atlas schema migrations · `server/src/db/migrations/001_canonical_v1.sql`

### Admin console

Authenticated operational UI for review, diagnostics, and moderation

- [Admin shell](https://github.com/realtruenorth/purzoot/blob/main/admin-console/src/App.tsx): react admin · Authenticated admin application shell and navigation · `admin-console/src/App.tsx`
- [Auth gate](https://github.com/realtruenorth/purzoot/blob/main/admin-console/src/auth/AuthGate.tsx): admin auth · Admin session, permission, and access control boundary · `admin-console/src/auth/AuthGate.tsx`
- [Admin modules](https://github.com/realtruenorth/purzoot/blob/main/admin-console/src/modules/diagnostics/Diagnostics.tsx): ops ui · Operational pages for diagnostics, flags, health, sessions, proofs, moments, and audit logs · `admin-console/src/modules/diagnostics/Diagnostics.tsx`

### Shared contracts

Reusable schemas and integration interfaces across runtimes

- [Schemas](https://github.com/realtruenorth/purzoot/blob/main/packages/purzoot-schema/schemas/v1/manifest.json): contracts · Versioned canonical JSON Schemas and fixtures · `packages/purzoot-schema/schemas/v1/manifest.json`
- [SDK/CLI](https://github.com/realtruenorth/purzoot/blob/main/packages/purzoot-sdk/src/index.ts): integrations · Shared programmatic interface for validation and automation · `packages/purzoot-sdk/src/index.ts`

### Activity Atlas

Data ingestion, normalization, generation, and SQL import pipeline

- [Atlas pipeline](https://github.com/realtruenorth/purzoot/blob/main/data/activity-atlas/scripts/ingest_sources.py): data pipeline · Raw-to-canonical ingestion, normalization, generation, and import pipeline · `data/activity-atlas/scripts/ingest_sources.py`
- [Atlas assets](https://github.com/realtruenorth/purzoot/blob/main/data/activity-atlas/canonical/canonical_activities.v0.csv): canonical data · Canonical CSV/JSON artifacts and generated search/runtime seed files · `data/activity-atlas/canonical/canonical_activities.v0.csv`
- [Atlas SQL](https://github.com/realtruenorth/purzoot/blob/main/data/activity-atlas/sql/001_create_activity_atlas.sql): db bootstrap · SQL schema and import paths for atlas and review workflow · `data/activity-atlas/sql/001_create_activity_atlas.sql`

## Connections

- App shell → Routes: renders · The main shell composes the route-first product surfaces
- Routes → Moments: uses · Pages and feature areas are built around the local-first moment model
- Routes → Feed: drives · Discovery and feed pages consume feed projections
- Moments → Session archive: persists as · Session capture is archived separately from publish state
- Session archive → Sync engine: replays through · Local archive changes are queued and synchronized later
- Sync engine → Providers: adapts via · Sync and runtime capabilities depend on provider abstractions
- Providers → Cloud adapters: implements · Cloud services are attached behind the provider boundary
- Providers → Local adapters: implements · Local/mock backends support offline and development modes
- Cloud adapters → API server: syncs with · Cloud-backed browser behavior converges on server APIs and canonical state
- Local adapters → Sync engine: supports · Local implementations keep the app functional without cloud services
- API server → DB layer: serves · API requests are validated and persisted through the DB layer
- DB layer → Canonical repo: exposes · Repository code encapsulates canonical access patterns
- API server → Partner spine: hosts · Server owns the partner/canonical backend spine
- API server → Atlas admin: hosts · Server exposes activity atlas administration boundaries
- DB layer → Migrations: versioned by · Schema and review workflow evolve through migrations
- Admin shell → Auth gate: protects · Admin console is gated by auth and permissions
- Admin shell → Admin modules: navigates · The shell routes into diagnostics and operational modules
- Admin modules → API server: queries · Admin UI reads and inspects backend state
- Schemas → API server: contracts · Canonical schemas align app/server validation
- Schemas → App shell: contracts · Shared object shapes also guide the product app
- SDK/CLI → Schemas: validates · SDK/CLI sit on top of shared schema definitions
- Atlas pipeline → Atlas assets: generates · Ingestion and normalization produce canonical and generated atlas artifacts
- Atlas assets → Atlas SQL: imports to · Generated assets feed SQL bootstrap and import paths
- Atlas SQL → DB layer: seeds · Atlas schema and import output are loaded into the server database
- Atlas assets → Feed: feeds · Atlas taxonomy powers discovery and search-facing surfaces
- Atlas pipeline → Admin modules: reviews · Admin tools support review and reconciliation of atlas data