Tiny Robot Lab Logo
Tiny Robot Lab Learning Project

System Design

System Architecture & Clean Boundaries

Tiny Robot Lab enforces Clean Architecture with strict inward dependency rules. External frameworks, transport brokers, and remote AI providers are adapters around stable domain rules and application use cases.

Visual Diagram

End-to-End System Topology

The full runtime architecture spanning the operator browser, Prototype Console SPA, Orchestrator service, Redis transport, General Worker, and Research Agent microservices.

Autonomous Agent Lab System Architecture Diagram showing Console, Orchestrator, Redis, General Worker, and Research Agent
Figure 1: Full system architecture — Capability routing, Redis queues & streams, and grounded inference. Open full vector SVG diagram ↗

Layer Isolation

The Four Architectural Layers

Dependencies point strictly inward: Presentation and Infrastructure depend on Application, which depends on Domain. The Domain depends on nothing.

Domain Layer

Pure entities and business invariants with zero framework dependencies. Contains data contracts like Task, AgentCapability, RoutingDecision, and the EvidenceEvaluator ranking logic. It can be tested instantly without network access or databases.

Application Layer

Coordinates workflows and orchestration use cases such as SubmitTask and FindCandidatesQuery. Defines abstract ports (interfaces like TaskDispatcher and StateReader) without knowing whether they are implemented by Redis, HTTP, or memory fakes.

Presentation Layer

The delivery mechanism: FastAPI routes (/api/tasks, /api/agents, /health) and the browser-based Prototype Console SPA. Never interacts directly with domain logic; it passes inputs to application use cases and renders returned views.

Infrastructure Layer

Houses concrete implementations of application ports: Redis list queues, Redis stream publishers, Tavily web search clients, and Cloudflare Workers AI inference connectors. Adapters can be replaced or mocked without modifying business rules.

Why This Matters for Autonomous Agents

AI frameworks frequently blur the line between model prompts, network transport, and business rules. By strictly enforcing Clean Architecture boundaries:

  • Replaceable AI Providers: We can switch from Cloudflare Workers AI to a local Ollama model or cloud API by writing an adapter—zero domain changes required.
  • Fast Deterministic Testing: Fast deterministic automated testing without requiring live infrastructure or external APIs, using lightweight in-memory fake ports.
  • Credential Isolation: All provider tokens remain strictly inside containerized infrastructure adapters and are never exposed to browser consoles or client payloads.