Developer Appendix

---

title: "Developer Appendix" tier: "dev" status: "verified" version: "1.2.0" last-verified: "2026-06-17" commit: "b1c347b1" network-badge: "none" risk-tags: ["RISK: MEDIUM"]

🛠️ Developer Appendix

This appendix is for core developers and contributors working on the Tadpole OS codebase. It provides an overview of the architecture, extension points, and testing infrastructure.

Note

This page is a summary reference. For the full architectural specification, see ARCHITECTURE.md in the main repository.

---

1. Architecture Overview

Tadpole OS follows a 4-Pillar architecture:

Pillar	Responsibility	Key Components
Gateway	HTTP/WebSocket API surface	server-rs/src/router.rs, Axum framework
Registry	Agent, provider, and skill management	RegistryHub, GovernanceHub, ResourceHub
Engine	Autonomous mission execution	AgentRunner, RunContext, ToolOrchestrator
Security Root	Audit, budget, and access control	SecurityHub, MerkleAuditTrail, BudgetGuard

1.1 State Architecture (AppState)

The Glossary#appstate struct is the central coordination hub, containing five sub-hubs:

AppState
├── comms: CommunicationHub     (real-time events, oversight, WebSocket)
├── governance: GovernanceHub   (limits, policies, privacy mode)
├── registry: RegistryHub      (agents, providers, skills, MCP)
├── security: SecurityHub      (audit, budget, shell scanner)
├── resources: ResourceHub     (DB pool, HTTP client, audio, graphs)
└── base_dir: PathBuf          (root data directory)

---

2. Backend (Rust / Axum)

2.1 Source Structure

server-rs/
├── src/
│   ├── router.rs          # Axum route definitions (Gateway Pillar)
│   ├── state/             # AppState and Hub definitions
│   │   └── hubs/          # comms.rs, gov.rs, reg.rs, res.rs
│   ├── routes/            # HTTP handler implementations
│   ├── agent/             # AgentRunner, provider integrations
│   │   ├── runner/        # Core execution loop & swarm orchestration
│   │   │   ├── a2a_ledger.rs   # Agent payment ledger
│   │   │   ├── a2a_mailbox.rs  # Agent communication mailboxes
│   │   │   ├── a2a_router.rs   # Financial router for agent requests
│   │   │   ├── conductor.rs    # DAG plan generator & topological scheduler
│   │   │   └── mod.rs
│   │   ├── anthropic.rs   # Anthropic provider
│   │   ├── gemini.rs      # Google Gemini provider
│   │   └── groq.rs        # Groq provider
│   ├── security/          # Audit trails, budget guards
│   └── telemetry/         # OTel tracing, pulse types
├── data/                  # Runtime data (skills, workflows, DB)
└── migrations/            # SQL migration files

2.2 Route Registration

All routes are nested under /v1 in create_router(). The Parity Guard validates that every /v1 route has a corresponding entry in docs/openapi.yaml.

2.3 Error Handling

The engine uses RFC 9457 compliant Glossary#problemdetails for all API error responses, with unified error types via Glossary#apperror.

---

3. Frontend (React / Vite)

3.1 Key Hooks & Stores

Hook/Store	Purpose
useEngineStatus	Real-time engine connection status
use_vault_store	Client-side credential vault management
useLayoutNavigation	Tab navigation and keyboard shortcuts

3.2 Build Configuration

• Framework: Vite + React
• Config: vite.config.ts in project root
• Dev Server: npm run dev → http://localhost:5173

---

4. Extension Points

4.1 Custom Skills

Create a JSON manifest in data/skills/ with the following structure:

{
  "name": "my-custom-skill",
  "description": "Description of the skill",
  "execution_command": "python execution/my_script.py"
}

The Parity-Guard validates that the referenced execution script exists.

4.2 MCP Integration

The engine hosts a Model Context Protocol (MCP) server for external tool aggregation via RegistryHub::mcp_host.

4.3 Lifecycle Hooks

Pre/post tool execution hooks are managed by RegistryHub::hooks (HooksManager).

4.4 Provider SDK

Developers can implement the LlmProvider trait defined in provider_trait.rs to integrate new LLM backends (e.g. Anthropic, Gemini, OpenAI). The new provider must be registered in provider.rs.

4.5 Custom Tool Adapters

Custom tools run through the central dispatch system in dispatcher.rs. New static or dynamic tools can be mapped here.

4.6 Workflow Engine Extensions

The long-running workflow scheduling engine, Continuity, executes asynchronous tasks. Extensions to scheduling logic can be made in the Continuity scheduler scheduler.rs and the executor executor.rs.

4.7 Authentication Plugins [UI-MISSING]

Future extensions for multi-tenant and OAuth-based authentication will hook into the Axum request lifecycle. Currently restricted to local single-tenant vault authentication.

4.8 Vault & Crypto Extensions

Client-side cryptography (key derivation and encryption) is offloaded to a Web Worker in crypto.worker.ts. Custom encryption formats or key-stretching parameters can be configured there.

4.9 Agent-to-Agent (A2A) Payments & Mailboxes

Tadpole OS enables agents to pay peer agents for invoking sub-tasks. Developers can extend payment behaviors by working with:

• A2aLedger: Interacts with the local SQLite agent_transactions database to create, commit, or roll back pending allocations.
• A2aMailbox: Standardized buffer for inter-agent messages and payment challenges.
• A2aRouter: Coordinates the routing of requests to target agent providers and handles payment gateway mappings.

For transaction safety, developers should wrap payments in the Two-Phase Commit (2PC) pattern (Prepare $\rightarrow$ Commit / Rollback) to ensure zero balance leakage on failure.

---

5. Testing

5.1 Running Tests

# Frontend tests
npm test

# Backend tests
cd server-rs
cargo test

# Parity Guard (drift detection)
python execution/parity_guard.py .

# End-to-end (Playwright)
npx playwright test

5.2 Null Provider Mode

For CI/testing without real LLM calls:

TADPOLE_NULL_PROVIDERS=true

This routes all LLM calls through a NullProvider that returns mock responses.

---

6. Contributing

• See CONTRIBUTING.md for contribution guidelines.
• See DEVELOPMENT.md for development setup details.
• See CODE_OF_CONDUCT.md for community standards.

---

7. Symbol Graph Intelligence

For non-trivial code changes, use the scriptable symbol graph to inspect blast radius:

npm run graph:lookup -- --name SymbolName
npm run graph:file -- --path src/pages/Neural_Map.tsx
npm run graph:blast -- --path server-rs/src/routes/intelligence.rs --name get_blast_radius
npm run graph:export

---

Complete Lexicon: For the authoritative technical breakdown, see the main repository GLOSSARY.md. Every [[Glossary#term|term]] link on this page resolves to an entry there.