03 Architecture

03. Technical Architecture & System Design

Deep-dive architectural specification for PACT OS.

---

🏗️ High-Level System Architecture

graph TD
    Client[Browser / Mobile PWA] -->|HTTPS / WSS| Edge[Vercel Cloud Edge / Next.js 16]
    Edge -->|Server Actions| ActionLayer[Zod Validation & Server Actions]
    ActionLayer -->|Authenticated Context| Supabase[(Supabase PostgreSQL 15+)]
    Supabase -->|Row Level Security| RLS[RLS Boundary: auth.uid = user_id]
    Cron[Vercel Cron / pg_cron] -->|Bearer Auth| Sweeper[/api/cron/sweep-deadlines]
    Sweeper -->|Batch Scan| Supabase

Loading

---

📦 Layered Application Architecture

1. Presentation Layer (src/app/ & src/components/)

• Server Components: Render page shells, fetch initial server-side data, and stream HTML.
• Client Leaf Components: Interactive controls (modals, timers, form inputs) tagged with "use client".
• Design Tokens: Custom CSS variables, Tailwind CSS v4 glassmorphism tokens, and obsidian dark mode palette (#050505).

2. Domain & Application Logic (src/lib/ & src/features/)

• Server Actions: Encapsulate all database mutations with strict Zod schema validation.
• Domain Engines: Pure TypeScript domain logic (e.g. src/lib/money.ts, src/lib/time.ts, src/lib/accountability/).
• URL as State: Application state (filters, dates, tab selections) is bound deterministically to URL query params via useUrlState.

3. Data & Security Layer (supabase/ & @supabase/ssr)

• Database Schema: 26 frozen SQL migrations in supabase/migrations/.
• Authentication: Session cookie management handled by @supabase/ssr.
• Authorization: Row Level Security (RLS) enforced on 100% of PostgreSQL tables.

---

⚡ Server vs. Client Boundary Rules

sequenceDiagram
    participant User as Client Browser
    participant SA as Server Action
    participant Zod as Zod Schema
    participant Auth as Supabase Auth
    participant DB as PostgreSQL DB

    User->>SA: Submit Form Payload
    SA->>Zod: Validate Payload Structure
    alt Schema Invalid
        Zod-->>User: Return Validation Error
    else Schema Valid
        SA->>Auth: Verify Identity (supabase.auth.getUser)
        Auth-->>SA: Verified User (auth.uid)
        SA->>DB: Execute Query with User ID
        DB-->>User: Return Success Result
    end

Loading

1. Server-Side Identity Verification: Identity is derived exclusively from supabase.auth.getUser(). Client-provided user_id values in payloads are rejected.
2. Schema Enforcement: 100% of Server Actions validate input objects against Zod schemas prior to database operations.
3. No Unencrypted Client State: Confidential consequence payloads remain encrypted/masked in PostgreSQL.

---

🌐 Temporal & Timezone Architecture (src/lib/time.ts)

• Storage: All database timestamps use PostgreSQL TIMESTAMPTZ (stored in UTC).
• User Anchor: User timezone is stored as an IANA timezone string in profiles.timezone (e.g., 'America/New_York').
• Day Boundary Conversion: Calculations convert UTC timestamps to localized start-of-day/end-of-day before evaluating streaks or day planner slots.
• Server Clock Authority: Status transitions (e.g. marking a task missed) are evaluated against server time (now()), preventing client clock manipulation.

---

🎧 Focus Soundscape Synthesizer Architecture (src/lib/focus/sound.ts)

graph LR
    UserTrigger[User Starts Timer] --> AudioCtx[Initialize Web Audio Context]
    AudioCtx --> Oscillator[Oscillators & Buffer Generators]
    AudioCtx --> Filter[BiquadFilterNode]
    Filter --> Destination[Audio Output]

Loading

• Offline Sound Synthesis: Generates ambient focus soundscapes dynamically using native Web Audio API (AudioContext).
• Zero External Assets: Contains zero MP3/WAV file downloads or external audio CDN dependencies.
• Synthesizer Nodes: Uses BiquadFilterNode, custom audio buffer noise generators, and sine wave chime oscillators.

---

⏱️ Background Deadline Sweeper (/api/cron/sweep-deadlines)

• Schedule: Executes automatically every minute via Vercel Cron / pg_cron.
• Authentication: Protected by timing-safe Bearer token verification (CRON_SECRET).
• Operation:
  1. Queries all active commitments where deadline_at < NOW() and status = 'pending'.
  2. Updates task status to missed.
  3. Activates bound consequence records (is_activated = true).
  4. Dispatches notification alerts via notification dispatcher.