System Overview

1. Introduction

This document provides a high-level architectural overview of the TestoQA system.

It defines:

how the system is structured,
how responsibilities are divided,
where trust boundaries exist, and
which architectural rules are non-negotiable.

This file acts as the entry point for the Architecture section. All other architecture documents build on the concepts and constraints defined here.

2. Purpose & Scope

Purpose

The purpose of the system overview is to:

Explain how TestoQA works at a structural level
Establish shared vocabulary and mental models
Document architectural constraints and invariants
Serve as a long-lived reference for contributors

This document is intentionally opinionated. It describes how the system is designed to work, not every possible way it could be implemented.

Scope

This document covers:

Architectural style and runtime model
Core system components and their responsibilities
Trust boundaries and execution environments
Invariants that must hold across the entire system

3. In Scope vs Out of Scope

In Scope

High-level system structure
Runtime execution model
Server vs client responsibilities
Trust and security boundaries
Cross-cutting architectural rules

Out of Scope

Feature-level behavior
UI component structure
Database schema details
Deployment pipelines and CI configuration
Error handling strategies (covered elsewhere)
Authorization and permission logic (covered elsewhere)

4. Architectural Style

TestoQA is built as a single full-stack Next.js monolith using the App Router.

Key Characteristics

One deployable application
Frontend and backend logic live in the same codebase
Server-side rendering by default
Strong typing from database → services → boundaries → UI
Explicit separation between:
- UI concerns
- application boundaries
- domain logic
- data access

The architecture prioritizes:

clarity over cleverness,
explicitness over convenience, and
correctness over premature optimization.

5. Runtime Model

Execution Environments

TestoQA runs in two primary environments:

Server
- Server Components
- Server Actions
- Route Handlers
Client
- Client Components
- Browser-only state and effects

Only server-side code is trusted to:

access the database,
resolve authentication and tenant context,
perform authorization checks,
execute business logic.

Statelessness

The application is designed to be stateless at the container level:

No request relies on in-memory state for correctness
Requests may be handled concurrently
Server-side code must be re-entrant and side-effect aware

Long-running or heavy work must not block request/response cycles. Where such work is required, it is expected to move to background processing when available.

6. Core System Components

At a high level, the system is composed of the following components.

Web UI

React Server Components and Client Components
Responsible for rendering, user interaction, and local UI state
Never directly accesses the database
Never enforces security or authorization rules

Boundary Layer

The boundary layer represents system entry points:

App Router Pages (page.tsx, layout.tsx) as UI route entry points
Server Actions
Route Handlers (route.ts)

Responsibilities:

External input adaptation and validation
Authentication resolution
Tenant and request context resolution
Authorization enforcement (access control)
Orchestration of application and domain services

This layer forms the primary trust boundary between external input and internal logic.

Domain Services

Encapsulate business rules and workflows
Coordinate repositories and integrations
Framework-agnostic
Do not depend on Next.js primitives

Data Access Layer

Implemented using Prisma
Responsible for all database interaction
Applies tenant scoping structurally
Contains no business logic

External Integrations

Examples include:

Authentication provider
Email delivery
File storage
Realtime event provider

All external services are treated as untrusted and accessed through explicit integration boundaries.

7. Trust Boundaries

TestoQA explicitly defines where trust begins and ends.

Untrusted Inputs

Browser requests
Client-side state
External service responses
Uploaded files

All untrusted input must be:

validated,
authorized,
and scoped before use.

Trusted Zones

Server-side domain logic
Repository layer with enforced constraints
Database as the source of truth

Trust is never implicit and never client-derived.

8. Architectural Invariants (Golden Rules)

The following rules are non-negotiable across the entire system:

A RequestContext must be resolved at the system boundary before doing work.
All tenant-scoped data access must include a projectId.
Authorization must be enforced server-side before reading or mutating tenant data.
The server and database are the source of truth; client state is never authoritative.
Authorization or tenant-dependent data must not be cached unless explicitly scoped.
Prisma must never be accessed from UI components.
Missing tenant scoping is treated as a critical defect, not a recoverable error.

These invariants protect:

tenant isolation,
data correctness,
and system security.

All other architecture documents assume these rules hold.

9. Terminology & Shared Concepts

The following terms are used consistently throughout the architecture:

User An authenticated account.
Project (Tenant) The primary isolation boundary for data and permissions.
RequestContext A server-side object containing resolved identity and tenant information (e.g. userId, projectId).
Boundary A system entry point where validation, context resolution, and authorization occur.
Domain Service Business logic independent of framework and transport.
Repository A data access abstraction responsible for persistence and tenant scoping.

10. Relationship to Other Architecture Documents

This document defines global constraints and vocabulary.

Closing Note

This overview describes how the system is intended to work today.

If the architecture changes, this document must be updated to reflect reality—not aspiration.