Diagrams
1. Diagram Principles and Notation
These diagrams are descriptive, not prescriptive: they reflect the behavior and constraints documented elsewhere (
especially system-overview.mdx, tenancy-model.mdx, and module-boundaries.mdx).
Notation
- Boxes represent components or layers.
- Arrows represent direction of calls/data flow.
- Subgraphs represent trust/runtime boundaries (client vs server vs external).
- “Boundary Layer” means Server Actions / Route Handlers where validation, context resolution, and authorization occur.
Keep diagrams honest
If reality changes, update the prose and diagrams together. Diagrams should never become “aspirational.”
2. System Context Diagram
Shows major actors and external dependencies around the TestoQA application.
3. High-Level Runtime Diagram
Separates client and server execution environments.
4. Request Lifecycle Diagram
A typical tenant-scoped request from browser → boundary → DB → response.
5. Authentication and Tenant Resolution Diagram
Shows the ordering constraints: session → tenant resolution → authorization.
6. Module and Layering Diagram
Enforces allowed dependency direction as described in module-boundaries.mdx.
7. Data Flow Diagram
Shows read/write flow and where DTO mapping typically happens.
8. Optional: Upload and Realtime Diagrams
Upload flow (conceptual)
Realtime events (conceptual)
9. Diagram Ownership and Update Policy
-
These diagrams are the canonical visual reference for the architecture section.
-
If behavior changes (tenant resolution, boundaries, layering), update:
- the relevant prose doc, and
- this diagram file in the same change.
Cross-references:
- Invariants:
system-overview.mdx - Tenancy enforcement:
tenancy-model.mdx - Layering rules:
module-boundaries.mdx - Auth + authz specifics:
auth-flow.mdx,authorization-model.mdx - Flow specifics:
data-flow.mdx