Architecture

This page documents the shipped public PatchPatrol runtime model for the GitLab artifact-first path.

Public path scope: this document describes current runtime behavior in the ai-review run pipeline, plus how failures are surfaced.

What happens when ai-review run starts

The pipeline is shaped like a set of explicit stages:

1. Read effective configuration from environment and command flags.
2. Resolve a diff plan (auto, mr, branch, staged, working-tree).
3. Build a bounded review scope:
   • file include/exclude filtering,
   • file-level and total-size guardrails,
   • chunking and omission tracking.
4. Run trust checks before any provider call.
5. Run optional semantic precheck (only in diff+semantic context mode).
6. Collect repository overview signals.
7. Execute provider review and validate the structured output.
8. Emit artifacts (ai-review.json, ai-review.md, optional code_quality output).
9. Optionally run GitLab MR feedback, depending on AI_REVIEW_FEEDBACK_MODE and environment.

Input and Output Boundaries

Inputs

• Working tree/diff data from the selected git context.
• Run configuration and runtime limits from flags/environment.
• Optional repository overview evidence (file structure + detected tooling signals).
• Optional local semantic diagnostics when AI_REVIEW_CONTEXT_MODE=diff+semantic.

Processing boundaries

• Diff scope is bounded by fail-fast limits before provider execution.
• Review inputs are filtered into bounded chunks before provider review.
• If provider output is invalid for schema, PatchPatrol retries once and then emits an explicit fallback report.

Outputs

• ai-review.json is the machine-readable structured payload.
• ai-review.md is the operator-readable summary artifact.
• gl-code-quality-report.json is written when code-quality export is enabled in runtime config.
• Optional GitLab summary note and inline discussions are written only when delivery is configured.

Trust Gate and Redaction

Before any provider call, PatchPatrol evaluates:

• Provider endpoint allowlist enforcement.
• Secret-like pattern redaction on review chunk content.

If trust checks fail, the run exits with trust-fail artifacts and does not continue provider review.

For non-mock providers, an empty AI_REVIEW_PROVIDER_ALLOWLIST_BASE_URLS is considered a hard failure. That means provider review stops early (exit 11) unless an allowlist is explicitly configured. See the Configuration reference for details and required defaults.

Review execution behavior

• The review phase builds prompts from bounded diff content and repository context.
• Prompts may include bounded supporting context under AI_REVIEW_MAX_SUPPORTING_CONTEXT_BYTES. When present, that context is packed in priority order: matched repo-local review rules, deterministic preflight review hints, chunk-local supporting code evidence, relevant semantic diagnostics, and repository overview.
• Deterministic preflight hints can highlight duplicate added code-like text, dependency additions, risky import additions, and missing test-counterpart signals before provider review. They are prompt evidence only: the provider must verify the signal against diff/context evidence before reporting a finding, and hints do not become automatic findings or fail gates.
• Review prompts may annotate added and context lines with prompt-only L<number>: labels to help providers anchor findings to new/right-side lines. Final line_start and line_end artifact fields remain normal integer file line numbers; the prompt labels are not persisted.
• The default review-call output mode remains JSON-object/JSON compatible.
• When AI_REVIEW_STRUCTURED_OUTPUT_MODE=json_schema or auto is used with an OpenAI-compatible provider, PatchPatrol can request strict JSON-schema output for review calls and fall back to JSON-object mode if the endpoint rejects schema mode.
• On invalid provider output, PatchPatrol attempts a fallback validation strategy.
• All report content is still validated against the shipped artifacts schema before writing.
• Usage and runtime metadata are attached to the JSON report for transparency.
• Structured-output mode decisions are recorded only as compact meta.limits.structured_output_* metadata; raw prompts and provider request payloads are not persisted in artifacts.
• Preflight hint metadata is also compact; raw prompt bodies, raw hint evidence, and provider chain-of-thought are not available in artifacts.

For exact command flags and environment variables, see:

• CLI reference
• Configuration reference

Why the architecture is constrained this way

The default sequence is optimized for predictable, auditable review signal in CI:

• strict scope controls before remote calls,
• explicit boundary checks before provider interactions,
• artifact-first output for human verification,
• deterministic schema-validated payloads for downstream tooling.

This keeps the first deployment path lightweight while still making it clear where control points are.

Next steps

• Security and privacy model
• First review output
• Reference section