Technical Debt Tracker

This document tracks known architectural shortcuts, brittle patterns, or areas of the platform requiring refactoring to ensure maintainability and production readiness.

Core Services

Security & Context

• Principal-Based Contexts / RBAC: Our target architecture relies on a robust Principal or UserContext model across the entire system. We aim to implement a unified internal authentication and authorization schema (utilizing Service Accounts, System Users, or fine-grained Permissions contexts). This will replace our early iterations of internal routing methods (like GetByIDInternal), unifying our security pattern under a single, robust model.

System Infrastructure & Testing

External API Simulation

• AssemblyAI Mock Robustness: Invest in an industry-standard, fully independent AssemblyAI mock server. The current mock setup successfully supports WebSocket transcription tests over TLS, but further iterations should aim to eliminate any remaining need to adjust the system's internal connectivity paths or logic when under test.
• Automated Contract Verification: To guarantee zero contract drift, our target architecture includes a rigorous CI pipeline check that executes ./dev generate during every pull request. If git diff flags uncommitted schema changes (from OpenAPI or AsyncAPI), the build will fail. By strictly enforcing this automation, we ensure generated SDK clients are perfectly aligned with source specifications before merge, paving the way for in-memory JSON Schema Contract Testing within the unit test boundaries.