jpatel900/lifeos

1. Top-level shape

- This is a pnpm monorepo centered on a single Next.js app in apps/web.

- The architecture is a “workflow cockpit” for one person’s daily life ops, with a mock/offline phase-2 slice still available and a Supabase-backed phase-4A path when env vars are configured.

2. Primary user-facing surfaces

- The main screens are route-based workflow stages: capture, triage, review, execute, calendar, plus settings/areas, login, and health.

- AppShell provides the common UI frame, while WorkflowContext carries shared in-app state across the workflow pages.

3. Core workflow and domain state

- The domain is modeled around workflow objects, areas, and captured items, with the workflow logic split across apps/web/src/lib/workflow.ts and apps/web/src/lib/data/workflow.ts.

- apps/web/src/lib/types.ts and the shared schema package define the canonical shapes used across UI, AI parsing, and persistence.

4. Capture ingestion pipeline

- Raw user capture enters the system through /capture and the API route /api/parse-capture.

- That route delegates to the AI parsing layer in apps/web/src/lib/ai, where prompts, workflow orchestration, service wrappers, and regression fixtures/tests live.

- The parse output is contract-driven: apps/web/src/lib/ai/contracts aligns with packages/schemas/src/parse-capture.ts so the prompt/output boundary stays stable.

5. AI subsystem boundary

- The AI layer is deliberately isolated from UI and storage concerns.

- It contains prompt construction, workflow orchestration, and regression coverage, which makes it the main translation layer from messy user text into structured workflow data.

- The repository’s docs and tests suggest this is an important boundary because parsing quality is treated as a system concern, not a UI detail.

6. Persistence and backend data model

- Supabase is the primary backing store for phase-4A features.

- The app uses separate browser/server Supabase clients in apps/web/src/lib/supabase, and server-side data access is concentrated in apps/web/src/lib/data.

- The supabase/migrations directory defines the v1 tables, grants, health-check access, Google Calendar scaffolding, and hardened token storage, showing that the database is part of the architecture, not just a convenience.

7. Auth and multi-user boundaries

- Login flows are supported in the web app, and local seeding creates test users for development.

- Row-level security is a major architectural boundary: there are explicit RLS-related tests and migrations granting authenticated access per table family.

- This means user data isolation is enforced at the database layer, not only in application code.

8. External write subsystem: Google Calendar

- Google Calendar integration is a separate subsystem with its own connect/callback/disconnect/connection/freebusy/create-event routes.

- Client-side settings for this live under settings/areas/GoogleCalendarConnectionPanel.tsx.

- Tokens are stored encrypted in Supabase, and the code and migrations indicate a clear trust boundary around external writes: user action in the app triggers server-side OAuth and calendar operations.

9. Planning and execution orchestration

- apps/web/src/lib/planning/server.ts and apps/web/src/lib/externalWrites/server.ts suggest a controlled orchestration layer for moving from planned items to actual side effects.

- The triage, review, and execute screens are the user-visible stages where captured input becomes actionable work and then external actions.

10. Observability and telemetry

- Observability is first-class and split across Sentry, PostHog, and Langfuse in apps/web/src/lib/observability.

- There are separate client/server instrumentation entrypoints plus runtime-specific config, which implies telemetry is wired into both browser and server execution paths.

- Sanitization utilities are part of this layer, indicating privacy-aware logging/telemetry boundaries.

11. Shared packages and reusable contracts

- packages/schemas is the canonical domain/schema package and includes tests for entities, parse-capture, and model tiers.

- packages/types enforces parity between TypeScript types and schema definitions.

- packages/ui contains shared UI primitives, and packages/utils contains generic helpers; these packages keep app-specific logic from leaking into common code.

12. Local development and infra

- Supabase local development is supported directly from the repo, with migrations and seed data for a local workflow database.

- The README emphasizes that mock mode works without Supabase, OpenAI, or Google OAuth, so the app has a degraded/offline path and a fully integrated path.

- The root-level docs, agent context scripts, and skill files show that repo operations are tightly documented and optimized for phased development and handoff.

13. How data flows through the system

- A typical flow is: user capture → parse route/AI service → structured workflow item → workflow state/UI → persistence in Supabase → optional calendar planning/external write.

- The same workflow can also run in mock mode, where the UI and tests exercise the shell without relying on external services.

- This makes the architecture hybrid: local-first for development, service-backed for production-like behavior.

14. What matters most for a diagram

- Draw the Next.js app as the central runtime.

- Show three major backend edges from it: Supabase persistence/auth, AI parsing, and Google Calendar external writes.

- Put observability as a cross-cutting layer touching both client and server.

- Keep the shared schema/package layer separate from app code, because it defines the contracts used by all major subsystems.