04 Codebase Tour

04. Codebase Tour & Directory Structure

High-level guide to the PACT OS codebase layout and architectural conventions.

---

📂 Root Directory Overview

Pact_OS/
├── .github/                           # CI workflows, issue templates, PR template, CODEOWNERS, labels
├── docs/                              # Project documentation & Wiki master files
├── public/                            # Static PWA assets, icons, manifest
├── scratch/                           # Maintenance scripts, test runners, issue factory
├── src/                               # Application source code
│   ├── app/                           # Next.js 16 App Router (routes, layouts, API endpoints)
│   ├── components/                    # Shared UI design system components
│   ├── features/                      # 21 modular OS domain feature packages
│   ├── hooks/                         # Custom React hooks
│   ├── lib/                           # Core domain math, utility engines, and Supabase client
│   └── types/                         # Shared TypeScript interfaces & domain contracts
├── supabase/                          # Database schema, migrations, RLS policies
├── tests/                             # 56 domain unit & integration test suites
├── next.config.mjs                    # Next.js configuration & header security
├── package.json                       # Dependencies & npm scripts
└── tsconfig.json                      # Strict TypeScript compiler options

---

🧱 Key Subsystems Breakdown

1. Next.js App Router (src/app/)

• (auth)/: Authentication login, registration, and OAuth callback handlers.
• (dashboard)/app/: Main OS dashboard shell and 14 module sub-routes (accountability/, analytics/, calendar/, finance/, focus/, goals/, habits/, onboarding/, planner/, projects/, review/, settings/, tasks/).
• api/: Route handlers for background cron sweepers (/api/cron/sweep-deadlines), webhooks, and user data exports.

2. Feature Modules (src/features/)

PACT separates domain features into modular packages under src/features/:

• components/: Feature-specific UI components (e.g. TaskFormModal, DailyCadenceWidget, StreakSummaryCard).
• actions.ts: Next.js Server Actions handling mutations for the feature.
• data-access.ts: Server-side data fetching functions.

3. Pure Domain Engines (src/lib/)

Contains pure TypeScript math and logic independent of React UI components:

• money.ts: Integer-cents currency parsing, formatting, and budget arithmetic.
• time.ts: Local-to-UTC timezone conversions and day-boundary math.
• accountability/: Commitment state machine transitions and consequence activation logic.
• focus/sound.ts: Client-side Web Audio ambient soundscape synthesizer.
• integrations/: Connectors for external proof platforms (GitHub, LeetCode, Codeforces, Google Calendar).

4. Database Schema (supabase/migrations/)

26 frozen SQL migration files governing PostgreSQL tables, indexes, triggers, and Row Level Security (RLS) policies.

---

📐 Architectural Conventions

Code Type	Target Directory	Example File
New UI Component (Reusable)	src/components/ui/	src/components/ui/modal.tsx
Feature View/Widget	src/features/<feature>/components/	src/features/tasks/components/task-form-modal.tsx
Pure Math / Domain Logic	src/lib/<domain>/	src/lib/money.ts
Server Action / Mutation	src/features/<feature>/actions.ts	src/features/tasks/actions.ts
Domain Type / Contract	src/types/	src/types/domain.ts
Unit / Integration Test	tests/	tests/weekly-review.test.ts

---

⚠️ Protected Areas & Rules

1. supabase/migrations/: All 26 SQL migration files are frozen. Do NOT alter existing migration files.
2. src/lib/money.ts: Pure integer-cents arithmetic must be strictly preserved. Do NOT introduce floating-point currency math.
3. Row Level Security: Always verify auth.uid() = user_id in database queries and Server Actions.