# Koda v3.0 Install Notes

Problems encountered, deviations from spec, and implementation decisions during the v3.0 build.
This document supplements the v1.0 install notes and follows the same format.

**Spec document**: `docs/koda_spec_v3_0.md`
**Build queue**: `instructions/v3-queue.md`

---

## Phase 1: Infrastructure (v3-01)

### Wildcard CF Access Policy
**Spec step**: Configure wildcard CF Access policy on `*.koda.systems`
**Outcome**: Configured successfully. Single policy covers all subdomains. `koda.systems` (bare domain) excluded from policy — remains public as intended.

### Wildcard DNS
**Spec step**: Set up wildcard CNAME DNS record
**Outcome**: Wildcard CNAME `*.koda.systems` pointing to Cloudflare. No issues.

---

## Phase 2: Database Schema (v3-02)

### ADR-018 — Workspace Model
**Spec step**: Create `workspaces` and `workspace_surfaces` tables (replacing `app_channel_links`)
**Decision**: Adopted the workspace model from ADR-018. Each app gets a workspace, surfaces link channels (Signal groups, etc.) to workspaces.
**Deviation**: Task migration from `scope/scope_id` to `workspace_id` was done in a single migration rather than the two-phase approach initially considered.

### User Table Extensions
**Spec step**: Add `signal_uuid`, `whatsapp_id` columns to users table
**Outcome**: Added with appropriate indexes. Existing users backfilled from signal-cli UUID lookups where possible.

---

## Phase 3: RBAC v2 (v3-03)

### Four-Role Hierarchy
**Spec step**: Implement owner → admin → operator → viewer
**Decision**: Role hierarchy is enforced in code (`lib/users.js`), not in database constraints. This allows the permission resolution function to handle both global roles and per-app overrides.
**Note**: Cascading management rule (can only manage roles below your own) is enforced at every API endpoint and command handler.

---

## Phase 4: Multi-Channel (v3-04)

### Identity Resolution
**Spec step**: Unified identity record (email + Signal UUID + WhatsApp ID)
**Outcome**: Implemented. Cross-channel linking is admin-initiated only — no automatic linking based on phone number matching.
**Deviation**: WhatsApp integration deferred (no WhatsApp device available). Column exists but is not populated.

---

## Phase 5: Security (v3-05)

### Code-Enforced Permission Checks
**Spec step**: `checkPermission(user, app, action) → true/false` binary gate
**Decision**: Permission check is a synchronous function — no async DB lookups at check time. Permissions are cached on user resolve and refreshed on change events.

### Privileged Channel Restriction
**Spec step**: Restrict privileged operations to owner DM channel
**Outcome**: Implemented. Self-modify, server restart, and config commands only work in owner DM. Group messages cannot trigger these.

---

## Phase 6: Tier 2 Framework (v3-06)

### Scaffold & Deploy Updates
**Spec step**: Update `scaffold-app.sh` and `deploy-app.sh` for v3.0 conventions
**Outcome**: Templates now include admin API endpoints, audit logging, and permission table setup. D1 migrations generated automatically.

### Permission Sync
**Spec step**: Push mechanism + daily reconciliation
**Decision**: Push happens synchronously when roles change (Koda Core → app admin API). Reconciliation runs as a daily cron job comparing Postgres → D1.

---

## Phase 7: Dashboard Launcher (v3-07)

### CF Workers + D1
**Spec step**: Build dashboard at `dash.koda.systems`
**Outcome**: Deployed as Cloudflare Worker + D1. Dark theme, app launcher tiles, entitlements synced from Koda Postgres.

---

## Phase 8: DET22 Activity Tracker (v3-08)

### Reference Tier 2 App
**Spec step**: Scaffold, build, and deploy DET22 at `det22.koda.systems`
**Outcome**: Fully deployed. Schema: activities, rsvps, standard tables. Mobile-first PWA with RSVP system. Signal group linked via workspace surface.

### Signal Integration
**Decision**: Activity CRUD via Signal uses the NL intent pipeline. Koda parses natural language, maps to structured actions, and calls the DET22 API on behalf of the user.

---

## Phase 9: Audit & Observability (v3-09)

### Three-Actor Model
**Spec step**: user-direct, koda-directed, koda-autonomous audit trails
**Outcome**: Implemented in Koda Core. Tier 2 apps log locally and push audit entries to Koda Core via admin API. Console PWA has audit log viewer with filters.

---

## Phase 10: Documentation (v3-10)

### Architecture Diagrams
**Decision**: Generated dark-themed HTML diagrams rendered to PNG via Playwright (not Excalidraw). Four diagrams: permission architecture, system architecture, data sync model, URL/domain map. Source HTML kept in `docs/diagram-src/` for regeneration.

---

*This file is updated as each instruction file is completed.*
*Last updated: 2026-04-12*