# 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.