realtruenorth/purzoot

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.