Architecture Guide

Architecture Guide

This guide is for contributors who want to understand and work on the AgentCTX codebase.

Module Structure

AgentCTX follows a flat module architecture — every module lives at src/{name}/ with max depth of 1:

src/
├── ctx/            Core CTX parser, types, and grammar
├── gateway/        Middleware pipeline and request routing
├── sidecar/        Deterministic translation engine
├── storage/        Content-addressed store
├── memory/         5-layer memory manager
├── knowledge/      Semantic search and document indexing
├── skills/         Skill store and registry
├── crypto/         Ed25519 signing, AES-256-GCM encryption
├── auth/           JWT validation, OIDC, session management
├── sentinel/       Divergence detection and alignment monitoring
├── telemetry/      OpenTelemetry integration
├── economy/        Token budget tracking and cost reporting
├── cognition/      Reasoning trace capture
├── live/           SurrealDB LIVE SELECT subscriptions
├── obfuscation/    Constant-time index padding
├── ctxb/           Binary protocol encoder/decoder
├── dedup/          Convergent encryption deduplication
├── oprf/           Oblivious PRF key derivation
├── merkle/         Merkle tree proof of ownership
├── security/       Edge auth bridge, CH hierarchy
├── cli/            Command-line interface
├── mcp/            MCP protocol handler
├── entry/          HTTP and TCP entry points
├── orchestrator/   Multi-agent coordination
├── marketplace/    Plugin discovery and scoping
├── broker/         NATS queue worker processing
├── identity/       Agent identity, federation, trust weighting
├── graph/          SurrealDB graph memory traversal
├── dashboard/      Agent metrics and cost reporting
├── config/         Secrets resolution (op:// vault integration)
├── proxy/          Transparent MCP proxying
├── membus/         Internal memory event bus
├── pipeline/       Gateway middleware pipeline
├── observability/  SurrealDB telemetry logger
├── fs/             Filesystem patch utilities
└── protocol/       CLI↔Extension typed JSON protocol

Banned directories: src/core/, src/lib/, src/utils/, src/types/, src/helpers/ If code doesn’t belong in a named module, it doesn’t belong in the project.

Module Tiers

Modules are classified into 4 tiers (see src/MODULE_MAP.md):

Tier	Meaning	Treatment
Core	Foundation — everything depends on it (12 modules)	Optimize internals, thorough tests
Active	Completed, tested, consumed by core (21 modules)	Full test coverage, Node.js dependencies OK
Scaffolding	TypeScript prototypes targeting Rust migration (6 modules)	Clean interfaces, test against interface not internals
Deprecated	Superseded by surrealql emitter path (4 files)	Do NOT delete — fallback when surrealqlNative=false

Scaffolding Modules

These modules will be replaced by Rust crates:

• src/dedup/ → crates/dedup/
• src/oprf/ → crates/oprf/
• src/merkle/ → crates/merkle/
• src/obfuscation/ → crates/obfuscation/
• src/security/ → crates/security/
• src/llm/ → Rust FFI (provider adapters: OpenAI, Anthropic, DeepSeek, local)

Deprecated Modules

These 4 files are superseded by the surrealql emitter path but remain as fallback when surrealqlNative=false. They will be deleted after the TG-4 parity gate passes:

File	Replaced By
memory/decay.ts	fn::compute_decay + computed field in schema/memory.surql
memory/consensus-tier2.ts	HNSW KNN via surrealql/document.ts emitter
graph/relate.ts	surrealql/graph.ts emitter
graph/traverse.ts	surrealql/graph.ts emitter

When working on scaffolding modules:

• Keep interfaces clean (Rust will implement the same interface via FFI)
• Write tests against the interface, not internals
• Avoid Node.js-specific dependencies that tighten coupling

Design Principles

R1: Structured In, Structured Out

Every function returns a typed object, never a formatted string:

// ❌ Bad
return `Found 3 results for "${query}"`;

// ✅ Good
return { ok: true, count: 3, results: [...], ms: 12 };

R3: Token Cost Is a First-Class Metric

Before adding any field, ask: does the agent need this?

// ❌ 23 tokens of decoration
{ message: "Successfully searched", status: "ok", statusCode: 200 }

// ✅ 3 tokens
{ ok: true }

R6: Test From the Agent’s Perspective

// ❌ Human test
expect(result).toContain("Found 3 results");

// ✅ Agent test
expect(result.ok).toBe(true);
expect(result.count).toBe(3);

Phase Gate Process

Development follows a phase gate lifecycle:

prompt → implement → validate → audit → remediate → advance

No workstream ships without completing all 6 steps. See docs/phase-gate.md for current status.

See Also

• Testing — test conventions and running tests
• API Reference — module API documentation