Introduction

This section documents the core architecture of TestoQA: how the system is structured, how data flows, and why key decisions were made.

It is intentionally high-level and opinionated, focusing on system behavior, constraints, and boundaries rather than feature details.

How to read this section

If you’re new to the codebase, start with:

1. System Overview → vocabulary + invariants
2. Tenancy + Module Boundaries → the “load-bearing walls”
3. Auth + Authorization + Data Flow → how requests behave in practice
4. Diagrams + Domain Model → system visuals and core concepts
5. Operational Concerns + Decisions → reliability, observability, and why we chose this design

Documents (in recommended order)

1) System Overview

Defines the system’s architecture, runtime model, core components, trust boundaries, and non-negotiable invariants.

• system-overview.mdx

2) Diagrams

Visual references for the system context, request lifecycle, layering rules, and data flow.

• diagrams.mdx

3) Authentication Flow

How identity is established and resolved server-side (authentication only, not permissions).

• auth-flow.mdx

4) Data Flow

How data moves through boundaries → services → repositories → database (reads, writes, uploads, realtime, caching).

• data-flow.mdx

5) Design Decisions

Why the architecture looks the way it does (trade-offs, non-goals, guiding principles).

• design-decisions.mdx

6) Domain Model

The core business concepts (Project, TestCase, TestRun, Execution, Results, Reports) and how they relate.

• domain-model.mdx

7) Tenancy Model

How multi-tenancy works, how tenant context is resolved, and how tenant isolation is enforced.

• tenancy-model.mdx

8) Module Boundaries

Layering rules and dependency constraints that keep security, tenancy, and maintainability intact.

• module-boundaries.mdx

9) Authorization Model

How permissions are derived and enforced per (user, projectId) and where checks must occur.

• authorization-model.mdx

10) Error Handling

How errors are classified, propagated, logged, and safely exposed without leaking tenant or sensitive information.

• error-handling.mdx

11) Observability

Logging, metrics, correlation, audit signals, and alerting principles for operating TestoQA reliably.

• observability.mdx

Architectural invariants (quick reminder)

These are defined fully in system-overview.mdx, but they’re worth repeating as the guiding rules for this section:

• Always resolve a RequestContext at the boundary before doing work.
• Always scope tenant data access by projectId.
• Always authorize server-side before reading or mutating tenant data.
• The server/database is the source of truth; client state is never authoritative.
• Avoid caching tenant/authorization-dependent data unless explicitly scoped.
• Never access Prisma from UI components.