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

Dependency Flow

• 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	RequestState(12) + NodeState(12) state machines, transition rules, derived logic
domain/types-and-enums.md	ChainFamily, TransportFamily, NodeKind, EdgeType, GraphShape, and more
domain/error-taxonomy.md	MovementError hierarchy, Temporary/Fatal/Ambiguous classification, executor error handling
domain/executor-signer-protocols.md	ExecutorProtocol, SignerProtocol, ExecutionContext, SignRequest/Result

Compiler

Document	Contents
compiler/plan-compilation.md	Graph validation, topological ordering, binding resolution, compiled_plan_hash

Executors

Document	Contents
executors/overview.md	Executor architecture: local/remote, registry, lifecycle
executors/cex-lane.md	CEX 3-node lane: withdrawal_action → withdrawal_observe → deposit_observe
executors/cctp-lane.md	CCTP 5-node lane: burn → attestation → mint → mint_receive_observe → mint_finality
executors/observe-probes.md	EVM chain probes, protocol probes, observe executor family

Signers

Document	Contents
signers/signer-protocol.md	Signer interface, NoopSigner, AwsKmsEvmSigner, RemoteSignerProxy, LocalPrivateKeySignerEvm, health, caller verification

Infrastructure

Document	Contents
infrastructure/data-model.md	DB schema: 8 tables, relationships, JSON field conventions
infrastructure/bootstrap.md	Runtime initialization, executor/probe registration order
infrastructure/auth-rollout.md	Caller inventory, seed, smoke test, and rollback checklist before switching MG_AUTH_ENABLED=true

API

Document	Contents
api/v3-endpoints.md	V3 REST API: movements, templates, registry, health

Workers

Document	Contents
workers/runtime-workers.md	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