Architecture Overview

System Architecture #

End-to-End Flow #

The following describes a single pipeline run from trigger to pull request.

1. Trigger. An external webhook (GitHub push event or explicit POST /runs API call) delivers repo_full_name, ref, and depth_level. A new run_id is provisioned via gen_random_uuid() and persisted to the runs table with status = 'pending'.
2. Rate-limit check. Before dispatching to Temporal, the application layer checks the sliding-window user rate limit and the per-repo concurrency counter in Valkey. If either limit is exceeded, the run is rejected immediately with no Temporal workflow start.
3. Temporal workflow start. The orchestrator starts a TestGenerationWorkflow carrying the run_id. All downstream state is loaded from Postgres; the workflow carries no domain payload in its event history beyond identifiers.
4. Stage 1 — Repo Crawler. The Temporal activity CrawlRepo invokes the Repo Crawler agent. The agent calls the GitHub MCP server to fetch the repository file tree, entry points, and detected stack. Responses are cached in Valkey under amtp:mcp:tree:{repo}:{ref}. The validated JSON output is persisted as artifacts.kind = 'repo_crawler_output'. The agent’s LLM session is then discarded.
5. Stage 2 — Test Case Generator. A new LLM session is opened. The orchestrator loads the repo_crawler_output artifact, validates it against the Test Case Generator’s input JSON Schema, and injects it as the first user message. The agent produces a structured list of test cases. Output is persisted as artifacts.kind = 'test_case_generator_output'. The session is discarded.
6. Stage 3 — Test Engineer. A new LLM session is opened with the validated test-case list. The agent generates framework-specific Playwright or Maestro code files. Output is persisted as artifacts.kind = 'test_engineer_output'. The session is discarded.
7. Pull request creation. The Temporal activity CreatePullRequest acquires the per-repo Valkey lock, creates a new Git Tree via the GitHub Trees API (non-destructive), opens a pull request targeting base_branch, and releases the lock. The runs.status transitions to 'passed'.

Stateless LLM Contract #

The LLM is invoked statelessly. Each agent boundary enforces a hard context reset:

• The worker process hosting the upstream agent is torn down before the downstream agent starts.
• No messages, tool-call history, or in-memory state cross the boundary.
• The downstream agent receives only its static system prompt and the upstream agent’s validated JSON output injected as the first user message.
• Conversation memory, summarization, and cross-agent shared state are explicitly prohibited.

This design ensures reproducibility: given identical inputs, a deterministic temperature (≤ 0.2) and the same JSON payload will produce equivalent outputs. It also isolates failure domains — a hallucination in Stage 2 cannot corrupt Stage 1’s persisted artifact.

System Boundary #

Supporting Infrastructure Summary #

The Observability plane is implemented and operational. LLM agents emit structured OpenTelemetry spans and token-count metrics through an OTel Collector, which routes traces to Grafana Tempo and metrics to Prometheus. A pre-built LLM Token Accounting dashboard in Grafana provides real-time token usage, P95 latency, and call-rate panels. See Observability for the full pipeline reference.