pragent/docs/architecture.md

pragent current architecture

Status: pilot implementation, September 2026.

System shape

Gitea pull_request webhook
          │ signed HTTP
          ▼
webhook_server ── trusted base config ──► review_config
          │ bounded worker
          ▼
review_pr facade/orchestrator
   ├── entrypoints/gitea  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 top-level module is a compatibility shim; the implementation lives in review/ai_review.py.

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.
• entrypoints/gitea.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.
• review/diff, 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.