refactor: split pilot architecture

Remove the obsolete dashboard now that Langfuse is the analytics surface.\nIntroduce focused transport, model, and configuration modules while preserving the ai_review facade, and document the current runtime architecture.
2026-09-01 00:17:16 +00:00
parent 5b8be61e2f
commit b4041f6892
20 changed files with 290 additions and 2337 deletions
@@ -0,0 +1,68 @@
+# pragent current architecture
+
+Status: pilot implementation, September 2026.
+
+## System shape
+
+```text
+Gitea pull_request webhook
+          │ signed HTTP
+          ▼
+webhook_server ── trusted base config ──► review_config
+          │ bounded worker
+          ▼
+review_pr facade/orchestrator
+   ├── gitea_client       fetch diff, reviews, config; publish review
+   ├── diff_compress      reduce prompt context
+   ├── opencode_review     isolated checkout + agent execution
+   │       └── model / repo factory (.opencode)
+   ├── review parsing      normalize findings + validate anchors
+   ├── feedback            persist reactions and derive scores
+   └── langfuse_trace      usage, cost, evaluation telemetry
+```
+
+## Seams and responsibilities
+
+The external seam is `ai_review.review_pr(...)`: one call represents one review
+attempt and returns success/skip status. The module is retained as a facade for
+the CI and webhook callers that already import it.
+
+The internal seams are deliberately narrower:
+
+- `review_config.repo_enabled(get, ...)` owns the security-sensitive opt-in
+  decision. It receives a transport function, so malformed configuration and
+  failure behavior are deterministic in tests.
+- `gitea_client.request()` and `GiteaClient` own HTTP authentication, JSON
+  request encoding, timeout, and Gitea URL construction.
+- `model_client.complete()` owns the legacy Anthropic-compatible request shape.
+  `opencode_review` is the preferred agent adapter and keeps Gitea I/O out of
+  the autonomous process.
+- `diff_compress`, finding parsing, config filtering, and rendering remain
+  pure transformations. Their callers do not need to know how model or Gitea
+  transport works.
+- `langfuse_trace` is an optional sink. It is fail-open and cannot change the
+  review result.
+
+## Trust model
+
+The review config is read from the PR base branch, never the PR head. The agent
+checkout is treated as hostile: instruction files are removed, credentials are
+not inherited, and the agent only returns text to the Python publisher. Python
+validates finding paths and post-change line anchors before sending comments.
+
+## Observability
+
+Langfuse is the operational analytics surface. A trace groups runs by
+`owner/repo#PR`; generations carry usage and cost basis; evaluation scores and
+human-feedback scores are attached later. The former SQLite-backed dashboard
+was removed. SQLite remains only as the feedback/evaluation ingestion store.
+
+## Removed surface
+
+The dashboard server, dashboard data module, dashboard tests, dashboard README,
+and dashboard Kubernetes manifest are intentionally gone. Operators use the
+Langfuse UI for review trends and cost analysis, and Gitea for review details
+and configuration changes.
+
+Historical design/implementation plans under `docs/plans/` describe the
+earlier TypeScript framework proposal and are not the runtime architecture.