Skip to Content
🎉 TestoQA 1.0 is released
Developer GuideArchitectureRecommended domain model

Domain Model

1. Domain Modeling Principles

This document defines the conceptual domain model for TestoQA: the core business objects and how they relate.

It is intentionally not a database schema and not an exhaustive API reference. It exists to:

  • establish shared language,
  • clarify ownership and lifecycle,
  • and document invariants that must remain true as the system evolves.

Guiding principles

  • Tenant-first modeling: Most domain objects are owned by a Project (tenant).
  • Explicit ownership: Every tenant-scoped object has a clear owner (projectId).
  • Stable vocabulary: Prefer clear names that match how users and contributors talk about the system.
  • Workflows over tables: Model the system around user-facing workflows (test creation, runs, results, reporting).

Tenancy rules are specified in tenancy-model.mdx. This document focuses on domain concepts and relationships.

2. Core Domain Concepts

User

An authenticated account.

  • Users may belong to multiple Projects.
  • Users can perform actions within the scope of a Project based on membership and permissions.

Project (Tenant)

The primary isolation boundary.

  • A Project owns most domain data.
  • Membership and permissions are evaluated within a Project.
  • Almost all domain operations execute within a resolved projectId.

Membership

The association between a User and a Project.

Typical responsibilities:

  • defines whether the user belongs to the project
  • defines role or permission assignment within that project

Membership is the bridge between identity (User) and scope (Project).

TestCase

A persistent definition of a test artifact.

Conceptually:

  • what should be tested
  • input(s) / configuration(s)
  • expected behavior or evaluation rules (depending on feature set)

A TestCase is typically created once and executed many times.

TestRun

A grouped execution instance.

A TestRun represents:

  • a single “run” event or invocation
  • a collection of individual executions
  • shared configuration for the run (e.g., environment, model config, target version)

A TestRun is the primary unit for comparing outcomes over time.

Execution (or TestExecution)

An individual execution of a TestCase within a TestRun.

An Execution typically includes:

  • reference to the TestCase
  • reference to the TestRun
  • input used for that execution
  • produced output
  • evaluation status (pass/fail/unknown)
  • timing/metadata

Result / Evaluation

The interpretation of an Execution’s outcome.

Depending on system behavior, this might include:

  • computed verdict (pass/fail)
  • scoring information
  • failure reason(s)
  • reviewer notes / overrides (if applicable)

Report

A summarized view intended for human consumption.

Reports typically aggregate:

  • a TestRun’s overall health
  • pass/fail breakdowns
  • trends over time (if applicable)
  • top failures and diagnostics

Artifact

A persisted piece of supporting data associated with domain objects.

Examples:

  • uploaded files
  • logs captured for a run
  • generated output payloads too large to store inline
  • attachments used in evaluation

Artifacts must obey tenancy, authorization, and safe-access rules.

3. Conceptual Relationships

At a high level:

  • A User has many Memberships
  • A Project has many Memberships
  • A Project has many TestCases
  • A Project has many TestRuns
  • A TestRun has many Executions
  • An Execution belongs to exactly one TestCase
  • An Execution belongs to exactly one TestRun
  • A Report typically summarizes a TestRun (and may reference many executions)
  • Artifacts can be associated with TestCases, TestRuns, Executions, or Reports

Relationship diagram (conceptual)

This diagram is conceptual. The database schema may represent these associations differently, but the domain relationships should remain stable.

4. Ownership and Lifecycle Rules

Ownership rules

  • Most domain entities are tenant-scoped and owned by a Project.
  • Tenant ownership must be explicit and consistent: projectId is the canonical owner identifier.

Rule: If it is tenant-scoped, it must not exist without a Project owner.

Typical lifecycles

TestCase lifecycle

  • Created within a Project

  • Updated as the test evolves

  • Referenced by many Executions over time

  • Deletion (if supported) must consider:

    • historical runs
    • reports referencing past executions

TestRun lifecycle

  • Created when initiating a run

  • Accumulates executions as work proceeds

  • Transitions through statuses (conceptually):

    • created → running → completed (or failed/cancelled)

Execution lifecycle

  • Created as part of a run

  • Moves through statuses (conceptually):

    • queued → running → finished (or failed)

  • Produces outputs and evaluations

Report lifecycle

  • Generated for a run (or for a range of runs)
  • May be regenerated as more executions complete or as evaluation logic changes

5. Aggregates and Boundaries

TestoQA is not required to follow strict DDD, but the following boundaries are useful for reasoning:

Project as the outer boundary

Project provides:

  • tenancy scope
  • membership and permission context
  • ownership root for domain entities

TestRun as a workflow boundary

TestRun commonly serves as the unit for:

  • execution orchestration
  • status tracking
  • reporting aggregation
  • realtime updates

TestCase as a reusable definition boundary

TestCase represents:

  • stable definition + intent
  • reused across runs

Execution as an atomic work boundary

Execution is typically the smallest unit of:

  • scheduling
  • evaluation
  • logging
  • diagnostics

6. Domain Invariants

These invariants should remain true even as implementation evolves:

  • A TestRun cannot mix data across Projects.
  • An Execution cannot reference a TestCase from a different Project than the TestRun.
  • Reports must never aggregate cross-tenant data.
  • Artifacts must be accessible only within the owning Project and authorization scope.
  • Historical outcomes must remain attributable to a specific run and execution context.

7. Glossary

  • Tenant: A Project. The primary isolation boundary.
  • RequestContext: Server-side context that includes userId and projectId.
  • TestCase: A reusable test definition.
  • TestRun: A grouped execution event over one or more test cases.
  • Execution: One execution of a test case within a run.
  • Result/Evaluation: The interpreted outcome of an execution.
  • Artifact: Supporting stored data associated with domain objects.
  • Report: A human-friendly summary of run outcomes.

8. Review Checklist (Domain Model)

  • Does every tenant-scoped entity have an explicit Project owner?
  • Are cross-tenant relationships impossible by design?
  • Do workflow boundaries (Run, Execution) match how the system behaves?
  • Are artifacts treated as first-class, tenant-scoped data?
  • Does naming match how contributors and users talk about the system?
Last updated on
Design decisionsTenancy model