# jpatel900/lifeos architecture

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

- Interactive diagram: https://gitdiagram.com/jpatel900/lifeos
- Repository: https://github.com/jpatel900/lifeos

## Overview

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.

Main entry points: [`apps/web/src/lib/supabase/server.ts`](https://github.com/jpatel900/lifeos/blob/main/apps/web/src/lib/supabase/server.ts) (Supabase clients), [`apps/web/src/lib/ai/parseCaptureWorkflow.ts`](https://github.com/jpatel900/lifeos/blob/main/apps/web/src/lib/ai/parseCaptureWorkflow.ts) (Parse pipeline), [`apps/web/src/app/layout.tsx`](https://github.com/jpatel900/lifeos/blob/main/apps/web/src/app/layout.tsx) (Next.js app), [`apps/web/src/lib/observability/index.ts`](https://github.com/jpatel900/lifeos/blob/main/apps/web/src/lib/observability/index.ts) (Observability)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_app["Web App"]
  node_n_app_runtime["Next.js app<br/>runtime<br/>[layout.tsx]"]
  node_n_shell["AppShell<br/>ui shell<br/>[AppShell.tsx]"]
  node_n_context(("Workflow state<br/>client state"))
  node_n_capture["Capture stage<br/>route page<br/>[page.tsx]"]
  node_n_stages["Workflow stages<br/>route pages<br/>[page.tsx]"]
  node_n_settings["Settings areas<br/>route page<br/>[page.tsx]"]
  node_n_login["Login<br/>route page<br/>[page.tsx]"]
  node_n_health["Health<br/>route page<br/>[page.tsx]"]
  node_n_obs(("Observability<br/>telemetry<br/>[index.ts]"))
end

subgraph group_g_ai["AI Pipeline"]
  node_n_parse_route["Parse API<br/>api route<br/>[route.ts]"]
  node_n_ai_pipeline{{"Parse pipeline<br/>AI service"}}
  node_n_ai_prompt["Parse prompt"]
  node_n_ai_contract["Parse contract<br/>schema contract<br/>[parseCapture.ts]"]
end

subgraph group_g_backend["Backend Data"]
  node_n_workflow_model{{"Workflow model<br/>domain logic<br/>[workflow.ts]"}}
  node_n_workflow_data[("Workflow data<br/>data access<br/>[workflow.ts]")]
  node_n_supabase[("Supabase clients<br/>db clients<br/>[server.ts]")]
  node_n_planning{{"Planning<br/>orchestration<br/>[server.ts]"}}
  node_n_ext_writes{{"External writes<br/>orchestration<br/>[server.ts]"}}
  node_n_gcal{{"Google Calendar<br/>integration<br/>[server.ts]"}}
end

subgraph group_g_shared["Shared Packages"]
  node_n_schema_pkg["Schemas<br/>[index.ts]"]
  node_n_types_pkg["Types<br/>[index.ts]"]
  node_n_ui_pkg["UI kit<br/>[index.ts]"]
  node_n_utils_pkg["Utils<br/>[index.ts]"]
end

subgraph group_g_infra["Infra"]
  node_n_migrations[("Migrations<br/>db schema")]
end

node_n_app_runtime -->|"frames"| node_n_shell
node_n_app_runtime -->|"shares state"| node_n_context
node_n_app_runtime -->|"instruments"| node_n_obs
node_n_capture -->|"submits text"| node_n_parse_route
node_n_parse_route -->|"delegates to"| node_n_ai_pipeline
node_n_ai_pipeline -->|"builds prompt"| node_n_ai_prompt
node_n_ai_pipeline -->|"conforms to"| node_n_ai_contract
node_n_ai_contract -->|"aligns with"| node_n_schema_pkg
node_n_stages -->|"drives"| node_n_workflow_model
node_n_workflow_model -->|"persists via"| node_n_workflow_data
node_n_workflow_data -->|"uses"| node_n_supabase
node_n_login -->|"authenticates with"| node_n_supabase
node_n_health -->|"checks"| node_n_supabase
node_n_planning -->|"orchestrates"| node_n_ext_writes
node_n_ext_writes -->|"calls"| node_n_gcal
node_n_settings -->|"configures"| node_n_gcal
node_n_gcal -->|"stores tokens"| node_n_supabase
node_n_migrations -->|"defines"| node_n_supabase
node_n_schema_pkg -->|"parity"| node_n_types_pkg
node_n_ui_pkg -->|"powers UI"| node_n_shell
node_n_utils_pkg -->|"supports"| node_n_ai_pipeline
node_n_obs -->|"covers"| node_n_parse_route
node_n_obs -->|"covers"| node_n_workflow_data

click node_n_app_runtime "https://github.com/jpatel900/lifeos/blob/main/apps/web/src/app/layout.tsx"
click node_n_shell "https://github.com/jpatel900/lifeos/blob/main/apps/web/src/app/components/AppShell.tsx"
click node_n_context "https://github.com/jpatel900/lifeos/blob/main/apps/web/src/lib/WorkflowContext.tsx"
click node_n_capture "https://github.com/jpatel900/lifeos/blob/main/apps/web/src/app/capture/page.tsx"
click node_n_stages "https://github.com/jpatel900/lifeos/blob/main/apps/web/src/app/triage/page.tsx"
click node_n_settings "https://github.com/jpatel900/lifeos/blob/main/apps/web/src/app/settings/areas/page.tsx"
click node_n_login "https://github.com/jpatel900/lifeos/blob/main/apps/web/src/app/login/page.tsx"
click node_n_health "https://github.com/jpatel900/lifeos/blob/main/apps/web/src/app/health/page.tsx"
click node_n_parse_route "https://github.com/jpatel900/lifeos/blob/main/apps/web/src/app/api/parse-capture/route.ts"
click node_n_ai_pipeline "https://github.com/jpatel900/lifeos/blob/main/apps/web/src/lib/ai/parseCaptureWorkflow.ts"
click node_n_ai_prompt "https://github.com/jpatel900/lifeos/blob/main/apps/web/src/lib/ai/prompts/parseCapturePrompt.ts"
click node_n_ai_contract "https://github.com/jpatel900/lifeos/blob/main/apps/web/src/lib/ai/contracts/parseCapture.ts"
click node_n_workflow_model "https://github.com/jpatel900/lifeos/blob/main/apps/web/src/lib/workflow.ts"
click node_n_workflow_data "https://github.com/jpatel900/lifeos/blob/main/apps/web/src/lib/data/workflow.ts"
click node_n_supabase "https://github.com/jpatel900/lifeos/blob/main/apps/web/src/lib/supabase/server.ts"
click node_n_planning "https://github.com/jpatel900/lifeos/blob/main/apps/web/src/lib/planning/server.ts"
click node_n_ext_writes "https://github.com/jpatel900/lifeos/blob/main/apps/web/src/lib/externalWrites/server.ts"
click node_n_gcal "https://github.com/jpatel900/lifeos/blob/main/apps/web/src/lib/googleCalendar/server.ts"
click node_n_obs "https://github.com/jpatel900/lifeos/blob/main/apps/web/src/lib/observability/index.ts"
click node_n_schema_pkg "https://github.com/jpatel900/lifeos/blob/main/packages/schemas/src/index.ts"
click node_n_types_pkg "https://github.com/jpatel900/lifeos/blob/main/packages/types/src/index.ts"
click node_n_ui_pkg "https://github.com/jpatel900/lifeos/blob/main/packages/ui/src/index.ts"
click node_n_utils_pkg "https://github.com/jpatel900/lifeos/blob/main/packages/utils/src/index.ts"
click node_n_migrations "https://github.com/jpatel900/lifeos/blob/main/supabase/migrations/20260506213000_create_v1_core_tables.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_n_app_runtime,node_n_shell,node_n_context,node_n_capture,node_n_stages,node_n_settings,node_n_login,node_n_health,node_n_obs toneBlue
class node_n_parse_route,node_n_ai_pipeline,node_n_ai_prompt,node_n_ai_contract toneAmber
class node_n_workflow_model,node_n_workflow_data,node_n_supabase,node_n_planning,node_n_ext_writes,node_n_gcal toneMint
class node_n_schema_pkg,node_n_types_pkg,node_n_ui_pkg,node_n_utils_pkg toneRose
class node_n_migrations toneIndigo
```

## Components

### Web App

Next.js runtime, routes, and app-local state

- [Next.js app](https://github.com/jpatel900/lifeos/blob/main/apps/web/src/app/layout.tsx): runtime · Central Next.js app runtime for the workflow cockpit · `apps/web/src/app/layout.tsx`
- [AppShell](https://github.com/jpatel900/lifeos/blob/main/apps/web/src/app/components/AppShell.tsx): ui shell · Common frame shared across workflow screens · `apps/web/src/app/components/AppShell.tsx`
- [Workflow state](https://github.com/jpatel900/lifeos/blob/main/apps/web/src/lib/WorkflowContext.tsx): client state · Shared in-app workflow state and coordination context · `apps/web/src/lib/WorkflowContext.tsx`
- [Capture stage](https://github.com/jpatel900/lifeos/blob/main/apps/web/src/app/capture/page.tsx): route page · Entry screen for raw user capture and handoff to parsing · `apps/web/src/app/capture/page.tsx`
- [Workflow stages](https://github.com/jpatel900/lifeos/blob/main/apps/web/src/app/triage/page.tsx): route pages · Triage, review, execute, and calendar workflow screens · `apps/web/src/app/triage/page.tsx`
- [Settings areas](https://github.com/jpatel900/lifeos/blob/main/apps/web/src/app/settings/areas/page.tsx): route page · Settings surface for area and integration configuration · `apps/web/src/app/settings/areas/page.tsx`
- [Login](https://github.com/jpatel900/lifeos/blob/main/apps/web/src/app/login/page.tsx): route page · Authentication entrypoint for the app · `apps/web/src/app/login/page.tsx`
- [Health](https://github.com/jpatel900/lifeos/blob/main/apps/web/src/app/health/page.tsx): route page · Operational health check surface · `apps/web/src/app/health/page.tsx`
- [Observability](https://github.com/jpatel900/lifeos/blob/main/apps/web/src/lib/observability/index.ts): telemetry · Sentry, PostHog, Langfuse, and sanitization boundary · `apps/web/src/lib/observability/index.ts`

### AI Pipeline

Capture parsing and structured output contracts

- [Parse API](https://github.com/jpatel900/lifeos/blob/main/apps/web/src/app/api/parse-capture/route.ts): api route · Server route that turns capture text into structured workflow data · `apps/web/src/app/api/parse-capture/route.ts`
- [Parse pipeline](https://github.com/jpatel900/lifeos/blob/main/apps/web/src/lib/ai/parseCaptureWorkflow.ts): AI service · Prompting, orchestration, and service wrapper layer for capture parsing · `apps/web/src/lib/ai/parseCaptureWorkflow.ts`
- [Parse prompt](https://github.com/jpatel900/lifeos/blob/main/apps/web/src/lib/ai/prompts/parseCapturePrompt.ts): prompt · Prompt construction for capture parsing · `apps/web/src/lib/ai/prompts/parseCapturePrompt.ts`
- [Parse contract](https://github.com/jpatel900/lifeos/blob/main/apps/web/src/lib/ai/contracts/parseCapture.ts): schema contract · Stable input/output contract for parsed capture data · `apps/web/src/lib/ai/contracts/parseCapture.ts`

### Backend Data

Supabase persistence, planning, and external writes

- [Workflow model](https://github.com/jpatel900/lifeos/blob/main/apps/web/src/lib/workflow.ts): domain logic · Core workflow rules and item state transitions · `apps/web/src/lib/workflow.ts`
- [Workflow data](https://github.com/jpatel900/lifeos/blob/main/apps/web/src/lib/data/workflow.ts): data access · Server-side workflow persistence and query layer · `apps/web/src/lib/data/workflow.ts`
- [Supabase clients](https://github.com/jpatel900/lifeos/blob/main/apps/web/src/lib/supabase/server.ts): db clients · Browser and server Supabase clients and configuration · `apps/web/src/lib/supabase/server.ts`
- [Planning](https://github.com/jpatel900/lifeos/blob/main/apps/web/src/lib/planning/server.ts): orchestration · Server-side planning orchestration for moving items toward execution · `apps/web/src/lib/planning/server.ts`
- [External writes](https://github.com/jpatel900/lifeos/blob/main/apps/web/src/lib/externalWrites/server.ts): orchestration · Controlled server boundary for side effects and outbound actions · `apps/web/src/lib/externalWrites/server.ts`
- [Google Calendar](https://github.com/jpatel900/lifeos/blob/main/apps/web/src/lib/googleCalendar/server.ts): integration · OAuth, freebusy, event creation, and token handling for Calendar · `apps/web/src/lib/googleCalendar/server.ts`

### Shared Packages

Cross-package schemas, types, UI, and utilities

- [Schemas](https://github.com/jpatel900/lifeos/blob/main/packages/schemas/src/index.ts): package · Canonical domain and parse-capture schemas shared across the repo · `packages/schemas/src/index.ts`
- [Types](https://github.com/jpatel900/lifeos/blob/main/packages/types/src/index.ts): package · Type parity layer between TypeScript and schema definitions · `packages/types/src/index.ts`
- [UI kit](https://github.com/jpatel900/lifeos/blob/main/packages/ui/src/index.ts): package · Shared UI primitives used by the app · `packages/ui/src/index.ts`
- [Utils](https://github.com/jpatel900/lifeos/blob/main/packages/utils/src/index.ts): package · Generic helpers shared across packages · `packages/utils/src/index.ts`

### Infra

Database migrations and local development state

- [Migrations](https://github.com/jpatel900/lifeos/blob/main/supabase/migrations/20260506213000_create_v1_core_tables.sql): db schema · Supabase tables, grants, RLS, and Google Calendar token storage · `supabase/migrations/20260506213000_create_v1_core_tables.sql`

## Connections

- Next.js app → AppShell: frames · The app runtime renders the shared shell around workflows
- Next.js app → Workflow state: shares state · Workflow screens consume shared client-side workflow state
- Next.js app → Observability: instruments · Client and server runtime are wired to observability
- Capture stage → Parse API: submits text · Raw capture flows into the parsing API
- Parse API → Parse pipeline: delegates to · The API route hands parsing work to the AI pipeline
- Parse pipeline → Parse prompt: builds prompt · Prompt construction feeds structured capture parsing
- Parse pipeline → Parse contract: conforms to · Parsed output is validated against the shared contract
- Parse contract → Schemas: aligns with · AI contract stays stable with the canonical schema package
- Workflow stages → Workflow model: drives · Triage, review, execute, and calendar screens operate on workflow logic
- Workflow model → Workflow data: persists via · Workflow state is stored and queried through the data layer
- Workflow data → Supabase clients: uses · Server-side persistence goes through Supabase clients
- Login → Supabase clients: authenticates with · Login flow is backed by Supabase auth and user state
- Health → Supabase clients: checks · Health view depends on backend connectivity and health access
- Planning → External writes: orchestrates · Planning hands off to controlled side-effect execution
- External writes → Google Calendar: calls · External write boundary invokes Google Calendar operations
- Settings areas → Google Calendar: configures · Settings surface manages Calendar connection state
- Google Calendar → Supabase clients: stores tokens · Encrypted calendar tokens live in Supabase
- Migrations → Supabase clients: defines · Migrations shape the database schema and access rules
- Schemas → Types: parity · Types package keeps TypeScript and schema shapes aligned
- UI kit → AppShell: powers UI · Shared UI primitives support the app shell and surfaces
- Utils → Parse pipeline: supports · Generic helpers are reused by the AI and workflow layers
- Observability → Parse API: covers · Telemetry spans parsing and server execution paths
- Observability → Workflow data: covers · Telemetry also spans persistence and server data access