Claude
b4041f6892
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.
69 lines
2.9 KiB
Markdown
69 lines
2.9 KiB
Markdown
# 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.
|