# Technical Reference Documents

Technical Reference Documents (TRDs) capture the design rationale, architecture, alternatives explored, and decision log for significant engineering work in ows-coda. Each TRD is written before or during implementation and updated to reflect the final shipped design. They serve as the canonical reference for "why was it built this way?"

## Index

| Title                                                                           | Status      | Date       | Summary                                                                                                                                                                                         |
| ------------------------------------------------------------------------------- | ----------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Algorithms & Structures Exploration](algorithms-and-structures-exploration.md) | In Progress | 2026-05-17 | Audit of @coda/data-structures: adopted/deferred/rejected algorithms, integration opportunities across the codebase, evidence-based verdicts on HLL/count-min/bloom/t-digest/parallel-reducers. |
| [Search Service](search-service.md)                                             | Shipped     | 2026-03-29 | Standalone ConnectRPC microservice for hybrid BM25+HNSW+glossary search over GraphQL and Snowflake schemas, with S3 snapshots and circuit-breaker-wrapped embedding on GPU (g4dn.xlarge).       |
| [Snowflake Schema Index](snowflake-schema-index.md)                             | Shipped     | 2026-03-22 | Two-phase Snowflake index: fast table catalog at startup, background column enrichment, FK graph inference, and polling for changes.                                                            |
| [Semantic Schema Search](semantic-schema-search.md)                             | Shipped     | 2026-03-22 | Original hybrid search design (in-process): vector embeddings + keyword matching + curated glossary over GraphQL schema, with graph-based relationship traversal.                               |
| [Ephemeral Environments](ephemeral-environments.md)                             | Shipped     | 2026-03-22 | PR-triggered ephemeral environments on QA infrastructure with TTL-based cleanup, capacity management, and automated DB provisioning.                                                            |
| [Codebase Review Remediation](codebase-review-remediation.md)                   | In Progress | 2026-03-22 | Systematic fix plan for P0/P1/P2 issues from the 2026-03-20 codebase audit: abort-on-disconnect, fragile regex, TOCTOU races, and more.                                                         |
| [Logging Improvements](logging-improvements.md)                                 | Shipped     | 2026-03-22 | Structured JSON logging with AsyncLocalStorage-based request context (requestId, identityHash, conversationId) for Datadog faceting.                                                            |
| [Functional Tests](functional-tests.md)                                         | Shipped     | 2026-03-22 | 43-case functional test suite exercising the full server stack with real MySQL/Redis and a deterministic FakeProvider.                                                                          |
| [Collections Consistency](collections-consistency.md)                           | Shipped     | 2026-03-22 | Align List and Heap collection interfaces: add `has()`/`delete()` to List, remove `contains()` from Heap, fix SkipList capacity and index handling.                                             |
| [File Splits & Deduplication](file-splits-dedup.md)                             | Shipped     | 2026-03-20 | Split oversized schema-index.ts, extract shared tokenize utility, replace O(n^2) Map lookups, extract useConversationMutations hook.                                                            |
| [Message Status & Stream Persister](message-status-stream-persister.md)         | Shipped     | 2026-03-18 | Added `status` lifecycle column to messages and replaced batch-at-end persistence with incremental writes via StreamPersister.                                                                  |
| [GET /api/v1/chats/:id Endpoint](get-single-chat-endpoint.md)                   | Shipped     | 2026-03-18 | Single-chat GET endpoint to eliminate paginated over-fetching during MutationQueue conflict resolution.                                                                                         |
| [Docker Compose Environment](docker-compose-environment.md)                     | Shipped     | 2026-03-17 | Complete containerized local dev environment with MySQL, Redis, S3 (RustFS), HMR, and test profiles.                                                                                            |
| [@coda/db Package Extraction](db-package-extraction.md)                         | Shipped     | 2026-03-16 | Extracted Prisma schema, migrations, client, types, and crypto into a shared `@coda/db` workspace package.                                                                                      |
| [Stream Module](stream-module.md)                                               | Shipped     | 2026-03-18 | Typed SSE stream module in `@coda/core-api` with `StreamWriter`/`StreamReader` and compile-time event contract enforcement.                                                                     |