Core architecture
Foundational decisions about repository structure, runtime standards, and the two-plane execution model.ADR-0001: Monorepo and package boundaries
Enforce clear dependency direction and reduce cross-package coupling in a multi-app system.
ADR-0002: Runtime and build standards
Standardize runtime and build behavior to minimize environment drift and packaging surprises.
ADR-0003: Two-plane system architecture
Separate low-latency inference from asynchronous learning to preserve reliability and control
risk.
Data and storage
How the platform stores, evolves, and retrieves data including temporal facts, query segregation, and vector retrieval.ADR-0004: Primary data platform
Use Supabase Postgres with pgvector and pg_trgm for transactional, relational, and vector
workloads.
ADR-0005: Temporal fact and patch lifecycle
Preserve auditable memory evolution through temporal facts and gated patch promotion.
ADR-0006: DB query surface segregation
Constrain data mutation capabilities by design-time import boundaries.
ADR-0007: Retrieval pipeline design
Build evidence retrieval that combines semantic recall with graph context while remaining
low-latency.
Security and auth
Authentication, authorization, tenant isolation, and content safety across the platform.ADR-0008: Authentication and RBAC model
Support both service-to-service and end-user auth while enforcing server-derived reflection
roles.
ADR-0009: API architecture and authorization
Keep API boundaries explicit with consistent route-level authn/authz and error semantics.
ADR-0015: Tenant isolation and database RLS
Define defense-in-depth tenant isolation across API authorization and database row-level
policies.
ADR-0017: Public share-link boundary
Allow public reflection access via constrained anonymous sessions without exposing privileged
surfaces.
ADR-0018: Ingestion source security
Protect ingestion from hostile or oversized source inputs while preserving deterministic
pipeline behavior.
ADR-0028: Clerk org canonicalization
Canonicalize team-sharing onto Clerk Organizations using free-plan-compatible roles while
preserving creator-private access semantics.
Operations
CI/CD pipelines, observability, migration governance, and ingestion orchestration.ADR-0010: Ingestion orchestration
Make source ingest retry-safe and recoverable while preserving evaluation-gated learning.
ADR-0011: Observability and tracing
Provide actionable diagnostics without making core flows brittle.
ADR-0012: CI/CD quality and release gates
Keep release quality high through automated, ordered validation gates.
ADR-0013: Migration governance
Keep database schema evolution deterministic and verifiable across environments.
Frontend and mobile
Client-side architecture, voice runtime, and mobile API contracts.ADR-0014: Frontend state and realtime
Balance server-state correctness, local UI responsiveness, and realtime ingest visibility.
ADR-0019: Voice runtime provider
Replace self-hosted voice agent with a managed conversation provider while preserving
knowledge-graph authority.
ADR-0020: Expo mobile app (superseded)
Expo mobile configuration contracts in a pnpm monorepo. Superseded by native Swift iOS app.
ADR-0021: Mobile API contracts (superseded)
Centralize mobile-facing DTO schemas via shared Zod schemas. Superseded by native Swift iOS app.
ADR-0027: Agent routing and session orchestration
Explicit three-mode session routing (interview, reflection, share) with mode-aware tool
permissions and dynamic variable budgeting.
ADR-0031: Prompt pack runtime and public freshness
Persisted prompt-pack authority, audience-scoped public runtime, gated artifact promotion, and
freshness-aware public agent selection.
Quality and governance
Lint enforcement strategy, rate limiting, content monitoring, and domain taxonomy.ADR-0022: Lint policy and enforcement layers
Mechanically enforce architectural invariants through layered, defense-in-depth tooling.
ADR-0023: API rate-limit strategy
Keep the in-process limiter for now with explicit key derivation and clear migration triggers.
ADR-0024: Loti content monitoring feed
Ingest daily Loti content-monitoring results into Postgres for talent protection workflows.
ADR-0025: Aspect taxonomy and scoring
Provide user-facing domain structure over the knowledge graph with hybrid classification and
dual scoring.
ADR-0030: Knowledge graph relational overview
Truth-first relational atlas with disclosure-first shell, bundled relationship edges, and
deterministic structure-preserving sampling.
Voice cloning
Voice clone pipeline, lifecycle authority, and readiness gating.ADR-0026: Voice clone pipeline (superseded)
Voice cloning via outbox pattern with quality gating and metrics tracking. Superseded by
ADR-0029.
ADR-0029: Voice clone lifecycle authority
Durable attempt-driven lifecycle with sample-first product contract and multi-condition
readiness gate.
AI strategy
Vendor selection, model strategy, and AI capability boundaries.ADR-0016: AI vendor and model strategy
Separate inference, embedding, and voice-runtime vendor responsibilities with configurable
provider selection.