# ricl3/alloy architecture

> Architecture diagram of the GitHub repository ricl3/alloy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ricl3/alloy
- Repository: https://github.com/ricl3/alloy

## Overview

1. **What this repo is**
   - Alloy is a **VS Code extension written in TypeScript**.
   - It is **local-first**: there is no Alloy backend service. The extension runs in the VS Code extension host, gathers local Git changes, and sends only the necessary redacted content to a user-selected model provider.

2. **Top-level runtime boundary**
   - The main entrypoint is `src/extension.ts`.
   - That module is responsible for wiring the extension into VS Code: command registration, editor/change listeners, and startup/shutdown lifecycle.
   - `src/config.ts` centralizes settings like provider choice, review mode, file limits, categories, severities, and debounce behavior.

3. **User-facing surfaces inside VS Code**
   - `src/panels/SetupPanel.ts` provides onboarding/configuration UI for provider setup.
   - `src/findingsTree.ts` exposes reviewed issues in a tree view.
   - `src/commentController.ts` manages inline review comments.
   - `src/codeActionProvider.ts` exposes quick fixes and applyable actions in the editor.
   - `src/diagnosticBuilder.ts` converts review results into VS Code diagnostics, which is the main “lint-like” feedback channel.

4. **Core orchestration pipeline**
   - `src/codeReviewService.ts` is the central coordinator.
   - It collects changed files, enforces limits, invokes parsing/context extraction, calls the model, and normalizes results back into editor-facing artifacts.
   - The README’s review modes map to this layer: `fast`, `deep`, and `architecture` change how much analysis is done and how results are aggregated.

5. **Diff and repository input layer**
   - `src/gitUtils.ts` and `src/diffParser.ts` are the source-of-truth for what changed.
   - Git state is read locally, then diffs are parsed into file/hunk/range structures that downstream components can reason about.
   - `src/ignore.ts` applies skip logic for generated files, dependency folders, lockfiles, `.alloyignore`, and configured skip paths.

6. **Context enrichment before calling the model**
   - `src/astContext.ts` adds syntax-aware local context from the file’s AST and nearby code.
   - `src/repoStyleIndexer.ts` appears to collect repository patterns or style signals so reviews can compare changes against local conventions.
   - These modules reduce shallow comments by giving the LLM more than just raw line diffs.

7. **Privacy and prompt safety boundary**
   - `src/redaction.ts` removes secrets and token-like literals before any prompt is sent out.
   - `src/secretManager.ts` handles provider credentials, with the README indicating VS Code SecretStorage is used for API keys.
   - This is an important architectural boundary: sensitive content is filtered locally before external model calls.

8. **Model-provider abstraction**
   - `src/llmRouter.ts` is the provider dispatch layer.
   - It routes requests to Groq, Gemini, OpenAI-compatible endpoints, or Ollama, matching the README’s supported providers.
   - This keeps the review pipeline provider-agnostic and allows either cloud or fully local inference.

9. **Review result structure and aggregation**
   - `src/reviewGraph.ts` and `src/vectorStore.ts` suggest internal structures for organizing findings, deduplication, and similarity-based retrieval/aggregation.
   - `src/customRules.ts` likely adds local policy or rule overlays on top of model output.
   - `src/diagnosticBuilder.ts` then translates the normalized findings into editor-native issue records with ranges, severities, and messages.

10. **Performance and reliability controls**
   - `src/rateLimiter.ts` constrains concurrency and request pressure.
   - `src/reviewCache.ts` caches review results to avoid recomputing identical work.
   - The benchmark suite in `src/test/benchmarks` emphasizes these concerns: diff parsing, redaction, deduplication, cache behavior, concurrency, and vector operations are all treated as first-class performance surfaces.

11. **Fix application and review workflow**
   - The README’s “one-click apply” behavior is reflected in the code action path and comment/diagnostic pipeline.
   - Only high-confidence, range-bound replacements are promoted to actionable fixes, which keeps the extension from applying broad or risky edits automatically.

12. **PR description generation and secondary outputs**
   - `src/prDescriptionGenerator.ts` indicates the review engine can also produce a synthesized summary suitable for pull-request text or change summaries.
   - `src/export.ts` likely serves as a shared surface for consuming review outputs outside the main extension flow.

13. **Testing and quality bar**
   - The repo has extensive unit tests around each boundary: config, diff parsing, redaction, provider routing, diagnostics, comments, code actions, cache, vector store, and secret handling.
   - The benchmark files show that architecture and performance claims are meant to be reproducible, with mocked LLM calls so pipeline overhead can be measured deterministically.

14. **How to diagram it**
   - A good architecture diagram should show: VS Code UI/events on the left, the local review pipeline in the center, the provider abstraction on the right, and persistent/local support services (cache, secrets, ignore rules, rate limiting) surrounding the pipeline.
   - The main data flow is: **editor/Git changes → diff + AST/context enrichment → redaction + filtering → LLM provider → structured findings → diagnostics/comments/code actions/tree view**.

Main entry points: [`src/codeReviewService.ts`](https://github.com/ricl3/alloy/blob/main/src/codeReviewService.ts) (Review service), [`src/extension.ts`](https://github.com/ricl3/alloy/blob/main/src/extension.ts) (Extension entry), [`src/diagnosticBuilder.ts`](https://github.com/ricl3/alloy/blob/main/src/diagnosticBuilder.ts) (Diagnostics), [`src/llmRouter.ts`](https://github.com/ricl3/alloy/blob/main/src/llmRouter.ts) (LLM router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_vscode["VS Code surface"]
  node_src_extension_ts["Extension entry<br/>activation/lifecycle<br/>[extension.ts]"]
  node_src_panels_setuppanel_ts["Setup panel<br/>onboarding UI<br/>[SetupPanel.ts]"]
  node_src_findings_tree_ts["Findings tree<br/>tree view<br/>[findingsTree.ts]"]
  node_src_comment_controller_ts["Comments<br/>inline review"]
  node_src_code_action_provider_ts["Quick fixes<br/>code actions"]
  node_src_diagnostic_builder_ts["Diagnostics<br/>lint adapter"]
end

subgraph group_group_pipeline["Review pipeline"]
  node_src_code_review_service_ts["Review service<br/>orchestrator"]
  node_src_git_utils_ts["Git input<br/>git reader<br/>[gitUtils.ts]"]
  node_src_diff_parser_ts["Diff parser<br/>diff model<br/>[diffParser.ts]"]
  node_src_ast_context_ts["AST context<br/>context enrich<br/>[astContext.ts]"]
  node_src_repo_style_indexer_ts["Style indexer<br/>style signals"]
  node_src_pr_description_generator_ts["PR summary<br/>secondary output"]
  node_src_export_ts["Export<br/>shared output<br/>[export.ts]"]
end

subgraph group_group_support["Local services"]
  node_src_redaction_ts["Redaction<br/>privacy filter<br/>[redaction.ts]"]
  node_src_ignore_ts["Ignore rules<br/>filtering<br/>[ignore.ts]"]
  node_src_review_cache_ts[("Review cache<br/>[reviewCache.ts]")]
  node_src_rate_limiter_ts["Rate limiter<br/>concurrency guard<br/>[rateLimiter.ts]"]
  node_src_custom_rules_ts["Custom rules<br/>policy overlay<br/>[customRules.ts]"]
  node_src_review_graph_ts{{"Review graph<br/>finding graph<br/>[reviewGraph.ts]"}}
  node_src_vector_store_ts[("Vector store<br/>similarity index<br/>[vectorStore.ts]")]
  node_src_secret_manager_ts[("Secrets<br/>credential store<br/>[secretManager.ts]")]
end

subgraph group_group_provider["Model providers"]
  node_src_llm_router_ts["LLM router<br/>provider dispatch<br/>[llmRouter.ts]"]
end

node_src_extension_ts -->|"starts review"| node_src_code_review_service_ts
node_src_extension_ts -->|"opens setup"| node_src_panels_setuppanel_ts
node_src_extension_ts -->|"registers tree"| node_src_findings_tree_ts
node_src_extension_ts -->|"registers comments"| node_src_comment_controller_ts
node_src_extension_ts -->|"registers fixes"| node_src_code_action_provider_ts
node_src_extension_ts -->|"publishes diagnostics"| node_src_diagnostic_builder_ts
node_src_code_review_service_ts -->|"reads changes"| node_src_git_utils_ts
node_src_code_review_service_ts -->|"parses diffs"| node_src_diff_parser_ts
node_src_code_review_service_ts -->|"adds context"| node_src_ast_context_ts
node_src_code_review_service_ts -->|"adds style"| node_src_repo_style_indexer_ts
node_src_code_review_service_ts -->|"filters scope"| node_src_ignore_ts
node_src_code_review_service_ts -->|"redacts content"| node_src_redaction_ts
node_src_code_review_service_ts -->|"checks cache"| node_src_review_cache_ts
node_src_code_review_service_ts -->|"throttles work"| node_src_rate_limiter_ts
node_src_code_review_service_ts -->|"applies rules"| node_src_custom_rules_ts
node_src_code_review_service_ts -->|"organizes findings"| node_src_review_graph_ts
node_src_code_review_service_ts -->|"requests review"| node_src_llm_router_ts
node_src_review_graph_ts -->|"similarity lookup"| node_src_vector_store_ts
node_src_llm_router_ts -->|"uses credentials"| node_src_secret_manager_ts
node_src_llm_router_ts -->|"returns findings"| node_src_diagnostic_builder_ts
node_src_diagnostic_builder_ts -->|"feeds tree"| node_src_findings_tree_ts
node_src_diagnostic_builder_ts -->|"feeds comments"| node_src_comment_controller_ts
node_src_diagnostic_builder_ts -->|"enables fixes"| node_src_code_action_provider_ts
node_src_code_review_service_ts -->|"summarizes change"| node_src_pr_description_generator_ts
node_src_code_review_service_ts -->|"exports output"| node_src_export_ts

click node_src_extension_ts "https://github.com/ricl3/alloy/blob/main/src/extension.ts"
click node_src_panels_setuppanel_ts "https://github.com/ricl3/alloy/blob/main/src/panels/SetupPanel.ts"
click node_src_findings_tree_ts "https://github.com/ricl3/alloy/blob/main/src/findingsTree.ts"
click node_src_comment_controller_ts "https://github.com/ricl3/alloy/blob/main/src/commentController.ts"
click node_src_code_action_provider_ts "https://github.com/ricl3/alloy/blob/main/src/codeActionProvider.ts"
click node_src_diagnostic_builder_ts "https://github.com/ricl3/alloy/blob/main/src/diagnosticBuilder.ts"
click node_src_code_review_service_ts "https://github.com/ricl3/alloy/blob/main/src/codeReviewService.ts"
click node_src_git_utils_ts "https://github.com/ricl3/alloy/blob/main/src/gitUtils.ts"
click node_src_diff_parser_ts "https://github.com/ricl3/alloy/blob/main/src/diffParser.ts"
click node_src_ast_context_ts "https://github.com/ricl3/alloy/blob/main/src/astContext.ts"
click node_src_repo_style_indexer_ts "https://github.com/ricl3/alloy/blob/main/src/repoStyleIndexer.ts"
click node_src_redaction_ts "https://github.com/ricl3/alloy/blob/main/src/redaction.ts"
click node_src_ignore_ts "https://github.com/ricl3/alloy/blob/main/src/ignore.ts"
click node_src_review_cache_ts "https://github.com/ricl3/alloy/blob/main/src/reviewCache.ts"
click node_src_rate_limiter_ts "https://github.com/ricl3/alloy/blob/main/src/rateLimiter.ts"
click node_src_custom_rules_ts "https://github.com/ricl3/alloy/blob/main/src/customRules.ts"
click node_src_review_graph_ts "https://github.com/ricl3/alloy/blob/main/src/reviewGraph.ts"
click node_src_vector_store_ts "https://github.com/ricl3/alloy/blob/main/src/vectorStore.ts"
click node_src_secret_manager_ts "https://github.com/ricl3/alloy/blob/main/src/secretManager.ts"
click node_src_llm_router_ts "https://github.com/ricl3/alloy/blob/main/src/llmRouter.ts"
click node_src_pr_description_generator_ts "https://github.com/ricl3/alloy/blob/main/src/prDescriptionGenerator.ts"
click node_src_export_ts "https://github.com/ricl3/alloy/blob/main/src/export.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_extension_ts,node_src_panels_setuppanel_ts,node_src_findings_tree_ts,node_src_comment_controller_ts,node_src_code_action_provider_ts,node_src_diagnostic_builder_ts toneBlue
class node_src_code_review_service_ts,node_src_git_utils_ts,node_src_diff_parser_ts,node_src_ast_context_ts,node_src_repo_style_indexer_ts,node_src_pr_description_generator_ts,node_src_export_ts toneAmber
class node_src_redaction_ts,node_src_ignore_ts,node_src_review_cache_ts,node_src_rate_limiter_ts,node_src_custom_rules_ts,node_src_review_graph_ts,node_src_vector_store_ts,node_src_secret_manager_ts toneMint
class node_src_llm_router_ts toneRose
```

## Components

### VS Code surface

Extension host entrypoint and editor-facing UI/integration points.

- [Extension entry](https://github.com/ricl3/alloy/blob/main/src/extension.ts): activation/lifecycle · Registers commands, listeners, and startup/shutdown wiring in the VS Code host. · `src/extension.ts`
- [Setup panel](https://github.com/ricl3/alloy/blob/main/src/panels/SetupPanel.ts): onboarding UI · Provider and configuration setup surface shown inside VS Code. · `src/panels/SetupPanel.ts`
- [Findings tree](https://github.com/ricl3/alloy/blob/main/src/findingsTree.ts): tree view · Displays review findings in a navigable VS Code sidebar tree. · `src/findingsTree.ts`
- [Comments](https://github.com/ricl3/alloy/blob/main/src/commentController.ts): inline review · Manages inline review comments and their lifecycle in the editor. · `src/commentController.ts`
- [Quick fixes](https://github.com/ricl3/alloy/blob/main/src/codeActionProvider.ts): code actions · Exposes applyable fixes and editor actions for actionable findings. · `src/codeActionProvider.ts`
- [Diagnostics](https://github.com/ricl3/alloy/blob/main/src/diagnosticBuilder.ts): lint adapter · Converts normalized findings into VS Code diagnostics and ranges. · `src/diagnosticBuilder.ts`

### Review pipeline

Local orchestration from git changes to structured findings.

- [Review service](https://github.com/ricl3/alloy/blob/main/src/codeReviewService.ts): orchestrator · Central coordinator that gathers inputs, enforces limits, calls the model, and normalizes results. · `src/codeReviewService.ts`
- [Git input](https://github.com/ricl3/alloy/blob/main/src/gitUtils.ts): git reader · Reads local repository state and changed files from Git. · `src/gitUtils.ts`
- [Diff parser](https://github.com/ricl3/alloy/blob/main/src/diffParser.ts): diff model · Turns raw diffs into file, hunk, and range structures for downstream analysis. · `src/diffParser.ts`
- [AST context](https://github.com/ricl3/alloy/blob/main/src/astContext.ts): context enrich · Adds syntax-aware local code context around changed lines. · `src/astContext.ts`
- [Style indexer](https://github.com/ricl3/alloy/blob/main/src/repoStyleIndexer.ts): style signals · Collects repository-local patterns and conventions for comparison during review. · `src/repoStyleIndexer.ts`
- [PR summary](https://github.com/ricl3/alloy/blob/main/src/prDescriptionGenerator.ts): secondary output · Generates pull-request style summaries or change descriptions from review output. · `src/prDescriptionGenerator.ts`
- [Export](https://github.com/ricl3/alloy/blob/main/src/export.ts): shared output · Shared surface for consuming review outputs outside the main extension flow. · `src/export.ts`

### Local services

Persistence, policy, and performance controls used by the pipeline.

- [Redaction](https://github.com/ricl3/alloy/blob/main/src/redaction.ts): privacy filter · Removes secrets and token-like content before any external prompt is sent. · `src/redaction.ts`
- [Ignore rules](https://github.com/ricl3/alloy/blob/main/src/ignore.ts): filtering · Skips generated files, dependencies, lockfiles, and configured excluded paths. · `src/ignore.ts`
- [Review cache](https://github.com/ricl3/alloy/blob/main/src/reviewCache.ts): cache · Stores prior review results to avoid recomputing identical work. · `src/reviewCache.ts`
- [Rate limiter](https://github.com/ricl3/alloy/blob/main/src/rateLimiter.ts): concurrency guard · Controls request pressure and concurrent review execution. · `src/rateLimiter.ts`
- [Custom rules](https://github.com/ricl3/alloy/blob/main/src/customRules.ts): policy overlay · Applies local policy or rule adjustments on top of model output. · `src/customRules.ts`
- [Review graph](https://github.com/ricl3/alloy/blob/main/src/reviewGraph.ts): finding graph · Organizes findings for deduplication, aggregation, and related-result handling. · `src/reviewGraph.ts`
- [Vector store](https://github.com/ricl3/alloy/blob/main/src/vectorStore.ts): similarity index · Supports similarity-based retrieval and deduplication across review artifacts. · `src/vectorStore.ts`
- [Secrets](https://github.com/ricl3/alloy/blob/main/src/secretManager.ts): credential store · Handles provider credentials via local secret storage. · `src/secretManager.ts`

### Model providers

Provider dispatch and external inference endpoints.

- [LLM router](https://github.com/ricl3/alloy/blob/main/src/llmRouter.ts): provider dispatch · Routes review requests to Groq, Gemini, OpenAI-compatible, or Ollama providers. · `src/llmRouter.ts`

## Connections

- Extension entry → Review service: starts review · Extension activation and command wiring invoke the core review pipeline.
- Extension entry → Setup panel: opens setup · Extension exposes onboarding/configuration UI.
- Extension entry → Findings tree: registers tree · Extension wires the findings sidebar into VS Code.
- Extension entry → Comments: registers comments · Extension enables inline review comment management.
- Extension entry → Quick fixes: registers fixes · Extension exposes code actions for actionable findings.
- Extension entry → Diagnostics: publishes diagnostics · Extension connects review results to the diagnostics channel.
- Review service → Git input: reads changes · Coordinator pulls local Git state and changed files.
- Review service → Diff parser: parses diffs · Coordinator converts raw diffs into structured change data.
- Review service → AST context: adds context · Coordinator enriches diffs with syntax-aware local context.
- Review service → Style indexer: adds style · Coordinator incorporates repository pattern signals.
- Review service → Ignore rules: filters scope · Coordinator skips excluded files and paths before review.
- Review service → Redaction: redacts content · Coordinator ensures sensitive content is filtered before model calls.
- Review service → Review cache: checks cache · Coordinator reuses prior results when possible.
- Review service → Rate limiter: throttles work · Coordinator constrains concurrency and request pressure.
- Review service → Custom rules: applies rules · Coordinator overlays local policy onto findings.
- Review service → Review graph: organizes findings · Coordinator groups and deduplicates review results.
- Review service → LLM router: requests review · Coordinator sends enriched, redacted review prompts to a provider.
- Review graph → Vector store: similarity lookup · Review graph can use vector similarity for related findings and deduplication.
- LLM router → Secrets: uses credentials · Provider dispatch reads stored API keys or local credentials.
- LLM router → Diagnostics: returns findings · Structured model output is normalized into editor-ready diagnostics.
- Diagnostics → Findings tree: feeds tree · Diagnostics are also surfaced in the findings sidebar.
- Diagnostics → Comments: feeds comments · Diagnostic ranges and messages back inline comments.
- Diagnostics → Quick fixes: enables fixes · Only actionable, range-bound findings become quick fixes.
- Review service → PR summary: summarizes change · Review output can be transformed into PR-style descriptions.
- Review service → Export: exports output · Normalized review artifacts can be consumed by other surfaces.