> ## Documentation Index
> Fetch the complete documentation index at: https://jephalabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Architecture Overview
> QTG system architecture — domain, compiler, executors, signers, and workers
# QTG v3 — Implementation Reference
This directory contains the **implementation reference docs** for the QTG v3 movement orchestration framework.
Unlike the planning docs, this section documents the **current code-based structure, interfaces, and behavior**.
## Reading Order
```
1. This README (understand the overall structure)
2. domain/ Domain model — states, types, errors, protocols
3. compiler/ Plan compilation — graph validation, snapshots, hashing
4. executors/ Executor implementations — CEX lane, CCTP lane, observe probes
5. signers/ Signer protocol — remote signing, health, caller verification
6. infrastructure/ Data model, bootstrap
7. api/ V3 API endpoints
8. workers/ Runtime worker architecture
```
## Architecture Overview
```mermaid theme={null}
flowchart TB
subgraph interfaces["interfaces/ — Delivery Layer (thin)"]
I1[api/routes/
HTTP handlers → delegate to services]
I2[workers/
Loop wrappers → delegate to services]
end
subgraph application["application/services/ — Orchestration Layer"]
A1[movements.py
create/approve/reject/resume/retry/cancel]
A2[dispatch.py
READY node → preflight → prepare → sign]
A3[observe.py
SUBMITTED/OBSERVING → observe loop]
A4[recover.py
UNKNOWN node → reconciliation]
A5[advance.py
state derivation, frontier advancement]
end
subgraph domain["domain/ — Pure Rules (no I/O)"]
D1[states.py
RequestState, NodeState, transitions]
D2[types.py
ChainFamily, TransportFamily, NodeKind]
D3[errors.py
Temporary / Fatal / Ambiguous taxonomy]
D4[protocols.py
ExecutorProtocol, SignerProtocol contracts]
end
subgraph infrastructure["infrastructure/ — I/O Implementations"]
F1[executors/
CEX, CCTP, observe executors]
F2[signers/
Noop, Remote proxy signers]
F3[db/
SQLAlchemy ORM, repositories]
F4[callbacks/
Outbox, HMAC signing]
F5[bootstrap.py
Runtime initialization]
end
interfaces --> application
application --> domain
application --> infrastructure
```
## Dependency Flow
```mermaid theme={null}
flowchart LR
interfaces[interfaces/] --> application[application/]
application --> domain[domain/]
application --> infrastructure["infrastructure/
(domain types only)"]
```
* `domain/` has no external dependencies (pure Python)
* `infrastructure/` imports only domain types
* `application/` composes domain + infrastructure
* `interfaces/` delegates to application services
## Document Index
### Domain Layer
| Document | Contents |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| [domain/states-and-transitions.md](/reference/domain/states-and-transitions) | RequestState(12) + NodeState(12) state machines, transition rules, derived logic |
| [domain/types-and-enums.md](/reference/domain/types-and-enums) | ChainFamily, TransportFamily, NodeKind, EdgeType, GraphShape, and more |
| [domain/error-taxonomy.md](/reference/domain/error-taxonomy) | MovementError hierarchy, Temporary/Fatal/Ambiguous classification, executor error handling |
| [domain/executor-signer-protocols.md](/reference/domain/executor-signer-protocols) | ExecutorProtocol, SignerProtocol, ExecutionContext, SignRequest/Result |
### Compiler
| Document | Contents |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| [compiler/plan-compilation.md](/reference/compiler/plan-compilation) | Graph validation, topological ordering, binding resolution, compiled\_plan\_hash |
### Executors
| Document | Contents |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| [executors/overview.md](/reference/executors/overview) | Executor architecture: local/remote, registry, lifecycle |
| [executors/cex-lane.md](/reference/executors/cex-lane) | CEX 3-node lane: withdrawal\_action → withdrawal\_observe → deposit\_observe |
| [executors/cctp-lane.md](/reference/executors/bridges/cctp-lane) | CCTP 5-node lane: burn → attestation → mint → mint\_receive\_observe → mint\_finality |
| [executors/observe-probes.md](/reference/executors/observe-probes) | EVM chain probes, protocol probes, observe executor family |
### Signers
| Document | Contents |
| ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| [signers/signer-protocol.md](/reference/signers/signer-protocol) | Signer interface, NoopSigner, AwsKmsEvmSigner, RemoteSignerProxy, LocalPrivateKeySignerEvm, health, caller verification |
### Infrastructure
| Document | Contents |
| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| [infrastructure/data-model.md](/reference/infrastructure/data-model) | DB schema: 8 tables, relationships, JSON field conventions |
| [infrastructure/bootstrap.md](/reference/infrastructure/bootstrap) | Runtime initialization, executor/probe registration order |
| [infrastructure/auth-rollout.md](/reference/infrastructure/auth-rollout) | Caller inventory, seed, smoke test, and rollback checklist before switching `MG_AUTH_ENABLED=true` |
### API
| Document | Contents |
| -------------------------------------------------- | --------------------------------------------------- |
| [api/v3-endpoints.md](/reference/api/v3-endpoints) | V3 REST API: movements, templates, registry, health |
### Workers
| Document | Contents |
| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| [workers/runtime-workers.md](/reference/workers/runtime-workers) | Worker loops (8 always-on + 9 conditional), intervals, roles, and state progression flow |
## Source Statistics
Measured on the OSS build, 2026-07-31. These are a dated snapshot for sizing the
project, not a contract — recount rather than trust them if the number matters.
| Metric | Value | How it was counted |
| ------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Source files | 439 | `find src -name '*.py' \| wc -l` |
| Test files | 568 | `find tests -name 'test_*.py' \| wc -l` |
| Source LOC | \~85,600 | `find src -name '*.py' -exec cat {} + \| wc -l` |
| DB tables | 57 (9 `movement_*`) | `len(models.Base.metadata.tables)` |
| API endpoints | 44 (v3) | distinct `/v3` `APIRoute` paths on the built app |
| Builtin executor bindings | 22 | `len(_BUILTIN_EXECUTOR_MAPPING)` — binding metadata; two Stargate entries stay Free while their code is Pro, so an OSS build can run 20 of them |
| Workers | 17 (8 always-on + 9 conditional) | `core_workers` + `sidecar_workers` in `main.py` |