# Documentation

- [Wordloop Platform](/docs): Monorepo for meeting transcription, speaker identification, and AI-powered conversation intelligence.
- Start Here
  - [Getting Started](/docs/start/quickstart): First-time setup, prerequisites, and running the platform locally.
  - [Your First Contribution](/docs/start/first-contribution): Walk through the mechanics of shipping your first change to Wordloop.
- Learn
  - [Learn the Platform](/docs/learn): Conceptual guides to Wordloop's architecture, services, and the vocabulary we use to talk about them.
  - Concepts
    - [Concepts](/docs/learn/concepts): The vocabulary of Wordloop — the entities, relationships, and ideas every engineer must share.
  - Architecture
    - [System Architecture](/docs/learn/architecture/overview): High-level topology, service boundaries, and communication patterns.
    - [Authentication & Authorization](/docs/learn/architecture/auth): How identity, sessions, and service-to-service auth are managed.
    - [System Workflows](/docs/learn/architecture/system-workflows): Key data and message flows across the Wordloop system architecture.
    - [Optimistic Mutation with Echo-Suppressed Streaming](/docs/learn/architecture/data-flow): Wordloop's core data architecture — REST mutations with optimistic UI, WebSocket streaming for real-time reads, and echo suppression for multi-device synchronization.
    - [Infrastructure & Hosting](/docs/learn/architecture/infrastructure): Production hosting, local emulation, and network routing.
    - [Local Infrastructure](/docs/learn/architecture/local-infrastructure): Emulation, hybrid development model, and local port layout.
    - [Observability](/docs/learn/architecture/observability): How telemetry, events, and tracing are propagated across the Wordloop platform using a Trace-First approach.
  - Platform Services
    - [Platform Services](/docs/learn/services): Per-service handbooks for Wordloop's four deployable services.
    - Core (Go)
      - [Core Service (Go)](/docs/learn/services/core): Getting started and overview for wordloop-core
      - [Core Architecture Rules](/docs/learn/services/core/architecture): Clean Architecture guidelines for Wordloop Core
      - [Core Implementation Guide](/docs/learn/services/core/implementation): Concrete Go patterns for trace-first logging, clean architecture, and error handling.
    - ML (Python)
      - [ML Service (Python)](/docs/learn/services/ml): Getting started and overview for wordloop-ml
      - [Architecture Rules](/docs/learn/services/ml/architecture): Clean Architecture guidelines for WordLoop Python Core
      - [ML Implementation Guide](/docs/learn/services/ml/implementation): Concrete Python patterns for trace-first logging, clean architecture, and error handling.
    - App (Next.js)
      - [App Service (Next.js)](/docs/learn/services/app): Getting started and overview for wordloop-app
      - [App Architecture Rules](/docs/learn/services/app/architecture): Frontend Architecture & Codebase Conventions for Wordloop App
      - [App Implementation Guide](/docs/learn/services/app/implementation): Concrete Next.js patterns for Server Actions, Client Providers, and UI separation.
      - [Design Guide](/docs/learn/services/app/design-guide): Visual Design and CSS Execution Guide
      - [UX Guide](/docs/learn/services/app/ux-guide): User Experience Guide and the Velocity Manifesto
- Guides
  - [Guides](/docs/guides): Task-oriented how-tos for the operations that come up most often on Wordloop.
  - [Code Generation](/docs/guides/code-generation): AsyncAPI, Orval, and oapi-codegen client generation workflows.
  - [Add an API Endpoint](/docs/guides/add-api-endpoint): Spec-first workflow to add a new HTTP endpoint to wordloop-core.
  - [Add a Service](/docs/guides/add-service): Scaffold a new microservice that plugs into gateway, observability, and CI.
  - [Run Tests](/docs/guides/run-tests): Unit, integration, and system tests — how to run them locally and read their output.
  - [Deploy](/docs/guides/deploy): Trigger a build, watch the canary, promote to production.
  - [Migrate the Schema](/docs/guides/migrate-schema): Write, review, and apply a Postgres migration with zero downtime.
  - [Keep Docs and Skills in Sync](/docs/guides/keep-docs-and-skills-in-sync): Workflow for changing canonical documentation and agent skills without creating drift.
  - [Correct Documentation Drift](/docs/guides/correct-documentation-drift): Workflow for resolving disagreements between docs, skills, code, contracts, data-flow diagrams, and design records.
- Reference
  - [Reference](/docs/reference): Structured lookup surfaces — CLI flags, API contracts, database schema, configuration keys, error codes, and glossary.
  - [CLI Reference](/docs/reference/cli): Complete reference for every command in the ./dev CLI.
  - API
    - [Core API](/docs/reference/api/core): Interactive Scalar API reference for the Core service.
    - [ML API](/docs/reference/api/ml): Interactive Scalar API reference for the ML service.
  - Events
    - [WebSocket Events](/docs/reference/events/core-ws): Interactive standalone AsyncAPI reference for the Core service's WebSocket event-driven contracts (CloudEvents v1.0).
    - [Pub/Sub Events](/docs/reference/events/core-pubsub): Interactive standalone AsyncAPI reference for the Core service's internal Pub/Sub messaging contracts (CloudEvents v1.0).
  - [Database Schema](/docs/reference/database): Postgres schema — tables, relationships, and ER diagram.
  - [Configuration](/docs/reference/configuration): Every environment variable, config key, and feature flag, organised by service.
  - [Errors](/docs/reference/errors): Error codes with HTTP status, meaning, and operator action.
  - [Glossary](/docs/reference/glossary): The canonical definition for every domain term and acronym used across Wordloop.
- Operations
  - [Operations](/docs/operations): Runbooks, on-call procedures, and troubleshooting guides for engineers responsible for keeping Wordloop up.
  - [Troubleshooting](/docs/operations/troubleshooting): Common failure symptoms and how to localise them — service-by-service diagnostic trees.
  - [On-Call](/docs/operations/on-call): Rotation, escalation, incident-response protocol, and the tools an on-call engineer needs on hand.
  - Runbooks
    - [Runbooks](/docs/operations/runbooks): Step-by-step recovery procedures for known failure modes.
  - [Documentation Freshness](/docs/operations/documentation-freshness): Review windows, freshness statuses, ownership rules, and stale-document handling for Wordloop documentation.
- Decisions (ADRs)
  - [Architecture Decision Records](/docs/decisions): The append-only log of significant, hard-to-reverse decisions — and the debt each one carries.
  - [Postgres with pgvector as the production vector store](/docs/decisions/0001-postgres-for-vector-search): We keep embeddings alongside their source rows in Postgres via pgvector rather than running a standalone vector database.
  - [Next.js with Server Components for the web app](/docs/decisions/0002-nextjs-ssr-for-app): We ship wordloop-app on Next.js Server Components rather than a client-side SPA to collapse AI-context data-fetch waterfalls.
  - [Stateful containers for the ML service](/docs/decisions/0003-stateful-containers-for-ml): We run wordloop-ml as long-lived orchestrated containers rather than serverless functions to keep models warm for real-time transcription.
  - [Hosting-layer Link header for llms.txt discovery](/docs/decisions/0004-hosting-layer-llms-txt-link-header): We publish the llms-txt rel link via Firebase Hosting headers because the docs site is a Next.js static export and cannot set response headers at the framework layer.
  - [Docs are canonical knowledge and skills are the agent execution layer](/docs/decisions/0005-docs-canonical-skills-execution-layer): We keep durable engineering guidance in the docs site and keep agent skills focused on triggering, context routing, tool use, safety, and verification.
- Engineering Principles
  - [Engineering Manifesto](/docs/principles): What we believe about building software at Wordloop, and why.
  - Foundations
    - [Foundations](/docs/principles/foundations): The ideas that shape how we think about software before any specific technology choice enters the conversation.
    - [Product Engineering](/docs/principles/foundations/product-engineering): Engineering in service of user outcomes — shaped work, appetite-based planning, and the refusal to ship the wrong thing faster.
    - [Code Craft](/docs/principles/foundations/code-craft): Simplicity, readability, the discipline of deletion, and the refusal to build for hypothetical futures.
    - [Documentation](/docs/principles/foundations/documentation): Docs as an active product surface for humans and AI agents — canonical knowledge, machine-readable interfaces, automation-first governance, and drift control.
    - [Testing](/docs/principles/foundations/testing): Continuous Risk Assurance — testing the system, not the mock of the system.
  - System Design
    - [System Design](/docs/principles/system-design): The structural commitments that determine whether a system stays tractable as it grows.
    - [Hexagonal Architecture](/docs/principles/system-design/hexagonal-architecture): Ports, adapters, and unidirectional dependency flow — the cornerstone structural choice for an agent-led codebase in 2026.
    - [API Design](/docs/principles/system-design/api-design): Contract-first design, versioning, evolution, pagination, and AI-agent readiness.
    - [Real-Time](/docs/principles/system-design/real-time): WebSockets, streaming, backpressure, echo suppression, and the patterns that make live experiences survive a degraded network.
    - [Data Engineering](/docs/principles/system-design/data-engineering): Events, streams, CQRS, event sourcing, and the data contracts that outlive any service.
    - [Integration Patterns](/docs/principles/system-design/integration-patterns): Webhooks, the outbox pattern, idempotency, and the sync-vs-async trade-off.
  - Stack
    - [Stack](/docs/principles/stack): How we use our chosen tools well — the idioms, patterns, and conventions that keep each language code-reviewable.
    - [Go Services](/docs/principles/stack/go-services): Idiomatic Go, gateway patterns, error handling, concurrency, and the shape of wordloop-core.
    - [Frontend](/docs/principles/stack/frontend): React 19, Server Components, SWR, Tailwind, and the design language of wordloop-app.
    - [ML Systems](/docs/principles/stack/ml-systems): Python, FastAPI, hexagonal ML architecture, model serving, and the disciplines that keep an AI runtime reliable.
    - [Postgres](/docs/principles/stack/postgres): Schema design, JSONB, migrations, indexing, and pgvector as our production vector store.
  - Quality
    - [Quality](/docs/principles/quality): How we protect users and the system — reliability, observability, performance, security, privacy, and accessibility.
    - [Reliability](/docs/principles/quality/reliability): SRE fundamentals, graceful degradation, circuit breakers, and the design patterns that keep systems up under load and failure.
    - [Observability](/docs/principles/quality/observability): OpenTelemetry-first design, SLOs, error budgets, and trace-driven development.
    - [Performance](/docs/principles/quality/performance): Latency budgets, tail latency, backpressure, and load shedding.
    - [Security](/docs/principles/quality/security): Zero-trust, threat modeling, SLSA supply-chain integrity, and the secure SDLC.
    - [Privacy](/docs/principles/quality/privacy): Data minimisation, GDPR, PII handling, and data residency for a platform that processes meeting audio.
    - [Accessibility](/docs/principles/quality/accessibility): WCAG 2.2 AA, keyboard-first design, screen-reader flows, and inclusive UX as a baseline, not a stretch goal.
  - Delivery
    - [Delivery](/docs/principles/delivery): How we ship — the inner-loop tooling, the release cadence, the platform under our platform, and the cost discipline behind it.
    - [Developer Experience](/docs/principles/delivery/devex): Golden paths, paved roads, inner-loop optimisation, and DORA metrics as the measure of whether the loop is healthy.
    - [Progressive Delivery](/docs/principles/delivery/progressive-delivery): Feature flags, canaries, trunk-based development, and deployment strategies that let us move fast without breaking things.
    - [Platform](/docs/principles/delivery/platform): Internal developer platforms, self-service tooling, and the treatment of `./dev` as a product in its own right.
    - [Cost Engineering](/docs/principles/delivery/cost-engineering): FinOps, cost-aware architecture, and the economics of autoscaling.
  - AI-Native
    - [AI-Native](/docs/principles/ai-native): How we build with and for AI — both inside the product and inside the development loop.
    - [AI Engineering](/docs/principles/ai-native/ai-engineering): Prompt engineering, evaluations, agent design, RAG, and context engineering.
    - [Agent-Native Systems](/docs/principles/ai-native/agent-native-systems): Making APIs and docs AI-consumable — MCP, llms.txt, structured metadata, and the interfaces that let agents work alongside humans.
- Work
  - [How We Work](/docs/work): A streamlined process for outcome-driven delivery, mapping strategic problems straight through to test-driven execution.
  - Problem Statements
    - [Problem Statements](/docs/work/problem-statements): A raw observation of friction. One paragraph. No solution. Evidence the problem is real.
    - [Backplane](/docs/work/problem-statements/backplane): No pod-to-pod event routing — WebSocket push is constrained to sticky sessions, blocking horizontal scaling.
    - [Recording Consent](/docs/work/problem-statements/recording-consent): No consent mechanism for recording meeting participants — legal risk proportional to adoption.
    - [Data Retention & Deletion](/docs/work/problem-statements/data-retention-and-deletion): No cascade-delete path for meetings — audio, embeddings, and derived artefacts accumulate with no erasure flow.
    - [Pause & Resume](/docs/work/problem-statements/pause-resume): Users cannot temporarily pause a live recording — there is no way to go 'off record' without ending the session.
    - [System Audio Capture](/docs/work/problem-statements/system-audio-capture): WordLoop can only capture the user's microphone — meetings happening through other apps (Zoom, Teams) require a different audio pipeline.
    - [Session Recovery](/docs/work/problem-statements/session-recovery): OPFS audio persists beyond tab close, but the recording session does not — accidental tab closure ends a live session with no recovery path.
    - [ML→Core Write-Back Resilience](/docs/work/problem-statements/ml-writeback-resilience): ML has no durable fallback when Core is unavailable during post-meeting result delivery.
    - [Orphaned Meeting Cleanup](/docs/work/problem-statements/orphaned-meeting-cleanup): If recording startup fails after the meeting is created, the user is left with an empty meeting and no clear recovery path.
    - [Replay Buffer Optimization](/docs/work/problem-statements/replay-buffer-optimization): After a WebSocket reconnect beyond the 5-minute replay buffer, the client must do a full REST re-fetch of all meeting state — expensive for long sessions.
  - Pitches
    - [Pitches](/docs/work/pitches): A refined problem with a rough solution sketch, confirmed appetite, rabbit holes, and no-gos.
  - Delivered
    - [Delivered Bets](/docs/work/delivered): Completed bets that have made impact in production.
    - Live Capture
      - [Problem Statement](/docs/work/delivered/live-capture/01-problem-statement): Meeting Recording — observed problem, appetite, and why we're solving this now.
      - [Pitch](/docs/work/delivered/live-capture/02-pitch): Meeting Recording — rough solution sketch, rabbit holes, and no-gos.
      - Technical Design
        - [User Flow](/docs/work/delivered/live-capture/03-tdd/user-flow): Meeting Recording — 12 user stories with acceptance criteria, screen inventory, and information architecture.
        - [Data Flow](/docs/work/delivered/live-capture/03-tdd/data-flow): Meeting Recording — system context, per-flow sequence diagrams, and boundary inventory.
        - Contracts
          - Core
            - [Core REST API](/docs/work/delivered/live-capture/03-tdd/contracts/core/rest): REST API contracts for the Core service.
            - [Core WebSocket API](/docs/work/delivered/live-capture/03-tdd/contracts/core/websocket): WebSocket API contracts and events for the Core service.
            - [Pub/Sub Events](/docs/work/delivered/live-capture/03-tdd/contracts/core/pubsub): Pub/Sub events published by Core.
          - ML
            - [ML NDJSON Stream API](/docs/work/delivered/live-capture/03-tdd/contracts/ml/ndjson-stream): HTTP streaming API and NDJSON events for the ML service.
        - Schemas
          - Core
            - [PostgreSQL Schema](/docs/work/delivered/live-capture/03-tdd/schemas/core/postgres): Relational database schema for the Core service.
            - [Cloud Storage Schema](/docs/work/delivered/live-capture/03-tdd/schemas/core/gcs): Object storage schema and structure for audio recordings.
        - Milestones
          - Live Recording
            - [Live Recording Operational](/docs/work/delivered/live-capture/03-tdd/milestones/live-recording): Milestone 1 integration overview.
            - [Core — Schema, Endpoints, Events](/docs/work/delivered/live-capture/03-tdd/milestones/live-recording/slice-core): Slice 1 Core.
            - [App — Live UI](/docs/work/delivered/live-capture/03-tdd/milestones/live-recording/slice-app): Slice 3 App.
            - [ML — Streaming API](/docs/work/delivered/live-capture/03-tdd/milestones/live-recording/slice-ml): Slice 2 ML.
          - Full Pipeline
            - [Full Pipeline Operational](/docs/work/delivered/live-capture/03-tdd/milestones/full-pipeline): Milestone 2 integration overview.
            - [Core — Post-Meeting](/docs/work/delivered/live-capture/03-tdd/milestones/full-pipeline/slice-core): Slice 4a Core.
            - [ML — Post-Meeting](/docs/work/delivered/live-capture/03-tdd/milestones/full-pipeline/slice-ml): Slice 4b ML.
          - Full Experience
            - [Full Meeting Experience](/docs/work/delivered/live-capture/03-tdd/milestones/full-experience): Milestone 3 integration overview.
            - [App — Playback UI](/docs/work/delivered/live-capture/03-tdd/milestones/full-experience/slice-app): Slice 5 App.

  - **Active Bets**
  - Meeting Recording
    - [Pitch](/docs/work/meeting-recording/pitch): Shaped pitch — problem, proposed solution, appetite, rabbit holes, and no-gos.
    - Technical Design Doc
      - [Overview](/docs/work/meeting-recording/tdd): Architectural approach, success criteria, key decisions, constraints, and navigation map for the Meeting Recording TDD.
      - [UI Design](/docs/work/meeting-recording/tdd/ui-design): Screen walkthrough — wireframes, states, interactions, and user journeys for the Meeting Recording feature.
      - [Data Flow](/docs/work/meeting-recording/tdd/data-flow): Meeting Recording — system context, per-flow sequence diagrams, and boundary inventory.
      - Contracts
        - [Contracts](/docs/work/meeting-recording/tdd/contracts): API contract reference for the Meeting Recording bet — organised by entity, covering REST, WebSocket, and Pub/Sub.
        - [Infrastructure](/docs/work/meeting-recording/tdd/contracts/infrastructure): Cross-cutting API concerns — authentication, connections, CloudEvents, error format, Pub/Sub, and failure semantics.
        - [Meeting](/docs/work/meeting-recording/tdd/contracts/meeting): Top-level resource — CRUD, expand parameter, speaker-label assignment, and audio playback URL.
        - [Recording](/docs/work/meeting-recording/tdd/contracts/recording): Live recording lifecycle — WebSocket commands and events, ML session management, OPFS gap repair, and Pub/Sub drain.
        - [Audio](/docs/work/meeting-recording/tdd/contracts/audio): Binary audio transport — frame formats, chunk storage, ML forwarding, acknowledgement, and backpressure.
        - [Transcription](/docs/work/meeting-recording/tdd/contracts/transcription): Transcript processing lifecycle and segments — CRUD, live streaming events, batch processing, ML write-back, and Pub/Sub trigger.
        - [Synthesis](/docs/work/meeting-recording/tdd/contracts/synthesis): ML-generated artefacts — summary, topics, talking points. Read endpoints, ML write-back, and live events.
        - [Task](/docs/work/meeting-recording/tdd/contracts/task): Action items — full CRUD with sub-task nesting, user-created and system-generated via ML.
        - [Person & Speaker Identity](/docs/work/meeting-recording/tdd/contracts/person): People CRUD, speaker identification pipeline, voice profiles, and ML speaker matching events.