# qwirlex/aegis-croo architecture

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

- Interactive diagram: https://gitdiagram.com/qwirlex/aegis-croo
- Repository: https://github.com/qwirlex/aegis-croo

## Overview

Aegis is a paid smart-contract auditing agent: a buyer submits a contract through CROO, the provider accepts and processes the order, the engine resolves source and analyzes it, and the provider delivers a report whose hash is committed on-chain. The engine also exposes asynchronous audit jobs and quick scans; the web app renders reports and supports short links. The graph combines README-documented product flows with sampled code and SOURCE INDEX references; unsampled internals are represented only where documented or indexed.

Main entry points: [`engine/aegis_engine/deep_audit.py`](https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/deep_audit.py) (Deep audit), [`engine/aegis_engine/app.py`](https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/app.py) (Audit API), [`provider/src/listener.ts`](https://github.com/qwirlex/aegis-croo/blob/master/provider/src/listener.ts) (CAP event listener), [`engine/aegis_engine/audit.py`](https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/audit.py) (Single-pass audit)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_engine["Audit engine"]
  node_engine_api["Audit API<br/>[app.py]"]
  node_legacy_audit["Single-pass audit<br/>[audit.py]"]
  node_source_resolver["Source resolver<br/>[source.py]"]
  node_chain_catalog["Chain catalog<br/>[chains.py]"]
  node_slither["Slither analysis<br/>[static_analysis.py]"]
  node_deep_audit["Deep audit<br/>[deep_audit.py]"]
  node_inventory["Contract inventory<br/>[inventory.py]"]
  node_lenses["Focused LLM lenses<br/>[lenses.py]"]
  node_llm["LLM reasoning<br/>[llm.py]"]
  node_merge["Finding merge<br/>[merge.py]"]
  node_refute["Finding refutation<br/>[refute.py]"]
  node_scoring["Risk scoring<br/>[scoring.py]"]
  node_integrity["Report integrity<br/>[integrity.py]"]
  node_report_models["Report models<br/>[models.py]"]
  node_job_store[("Audit job store<br/>[jobs.py]")]
end

subgraph group_provider["CAP provider"]
  node_provider_listener["CAP event listener<br/>[listener.ts]"]
  node_engine_client["Engine client<br/>[engine.ts]"]
  node_report_link["Report link builder<br/>[report-link.ts]"]
end

subgraph group_web["Report web app"]
  node_report_api["Short-link API<br/>[route.ts]"]
  node_report_page["Report page"]
  node_report_view["Report renderer<br/>[ReportView.tsx]"]
  node_web_store[("Short-link store<br/>[store.ts]")]
end

subgraph group_integrations["External services"]
  node_cap{{"CROO CAP"}}
  node_explorer{{"Block explorer"}}
  node_gemini{{"Vertex AI Gemini"}}
  node_chain[("Base chain")]
end

node_buyer(("Buyer / agent"))

node_buyer -->|"places order"| node_cap
node_cap -->|"sends events"| node_provider_listener
node_provider_listener -->|"accepts and delivers"| node_cap
node_provider_listener -->|"requests audit"| node_engine_client
node_engine_client -->|"posts audit"| node_engine_api
node_engine_api -->|"runs single pass"| node_legacy_audit
node_engine_api -->|"runs deep audit"| node_deep_audit
node_engine_api -->|"tracks jobs"| node_job_store
node_engine_api -->|"runs quick scan"| node_slither
node_legacy_audit -->|"resolves source"| node_source_resolver
node_legacy_audit -->|"analyzes source"| node_slither
node_legacy_audit -->|"reasons findings"| node_llm
node_source_resolver -->|"validates chain"| node_chain_catalog
node_source_resolver -->|"fetches verified source"| node_explorer
node_slither -.->|"analyzes deployed target"| node_chain
node_deep_audit -->|"prepares target"| node_source_resolver
node_deep_audit -->|"runs static analysis"| node_slither
node_deep_audit -->|"builds inventory"| node_inventory
node_deep_audit -->|"runs focused checks"| node_lenses
node_deep_audit -->|"generates summary"| node_llm
node_deep_audit -->|"merges findings"| node_merge
node_deep_audit -->|"refutes findings"| node_refute
node_deep_audit -->|"scores risk"| node_scoring
node_deep_audit -->|"signs report"| node_integrity
node_deep_audit -->|"builds report"| node_report_models
node_lenses -->|"requests model output"| node_llm
node_llm -->|"generates content"| node_gemini
node_provider_listener -->|"builds deliverable"| node_report_link
node_provider_listener -->|"commits report hash"| node_cap
node_report_link -->|"stores report"| node_report_api
node_report_page -->|"renders report"| node_report_view
node_buyer -->|"views report"| node_report_page
node_report_api -.->|"stores short link"| node_web_store
node_chain -->|"anchors proof"| node_buyer

click node_engine_api "https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/app.py"
click node_legacy_audit "https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/audit.py"
click node_source_resolver "https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/source.py"
click node_chain_catalog "https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/chains.py"
click node_slither "https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/static_analysis.py"
click node_deep_audit "https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/deep_audit.py"
click node_inventory "https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/inventory.py"
click node_lenses "https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/lenses.py"
click node_llm "https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/llm.py"
click node_merge "https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/merge.py"
click node_refute "https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/refute.py"
click node_scoring "https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/scoring.py"
click node_integrity "https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/integrity.py"
click node_report_models "https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/models.py"
click node_job_store "https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/jobs.py"
click node_provider_listener "https://github.com/qwirlex/aegis-croo/blob/master/provider/src/listener.ts"
click node_engine_client "https://github.com/qwirlex/aegis-croo/blob/master/provider/src/engine.ts"
click node_report_link "https://github.com/qwirlex/aegis-croo/blob/master/provider/src/report-link.ts"
click node_report_api "https://github.com/qwirlex/aegis-croo/blob/master/web/src/app/api/r/route.ts"
click node_report_page "https://github.com/qwirlex/aegis-croo/blob/master/web/src/app/report/ReportPageClient.tsx"
click node_report_view "https://github.com/qwirlex/aegis-croo/blob/master/web/src/components/ReportView.tsx"
click node_web_store "https://github.com/qwirlex/aegis-croo/blob/master/web/src/lib/store.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_engine_api,node_legacy_audit,node_source_resolver,node_chain_catalog,node_slither,node_deep_audit,node_inventory,node_lenses,node_llm,node_merge,node_refute,node_scoring,node_integrity,node_report_models,node_job_store toneBlue
class node_provider_listener,node_engine_client,node_report_link toneAmber
class node_report_api,node_report_page,node_report_view,node_web_store toneMint
class node_cap,node_explorer,node_gemini,node_chain toneRose
class node_buyer toneIndigo
```

## Components

### Audit engine

- [Audit API](https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/app.py): `engine/aegis_engine/app.py`
- [Single-pass audit](https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/audit.py): `engine/aegis_engine/audit.py`
- [Source resolver](https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/source.py): `engine/aegis_engine/source.py`
- [Chain catalog](https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/chains.py): `engine/aegis_engine/chains.py`
- [Slither analysis](https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/static_analysis.py): `engine/aegis_engine/static_analysis.py`
- [Deep audit](https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/deep_audit.py): `engine/aegis_engine/deep_audit.py`
- [Contract inventory](https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/inventory.py): `engine/aegis_engine/inventory.py`
- [Focused LLM lenses](https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/lenses.py): `engine/aegis_engine/lenses.py`
- [LLM reasoning](https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/llm.py): `engine/aegis_engine/llm.py`
- [Finding merge](https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/merge.py): `engine/aegis_engine/merge.py`
- [Finding refutation](https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/refute.py): `engine/aegis_engine/refute.py`
- [Risk scoring](https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/scoring.py): `engine/aegis_engine/scoring.py`
- [Report integrity](https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/integrity.py): `engine/aegis_engine/integrity.py`
- [Report models](https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/models.py): `engine/aegis_engine/models.py`
- [Audit job store](https://github.com/qwirlex/aegis-croo/blob/master/engine/aegis_engine/jobs.py): `engine/aegis_engine/jobs.py`

### CAP provider

- [CAP event listener](https://github.com/qwirlex/aegis-croo/blob/master/provider/src/listener.ts): `provider/src/listener.ts`
- [Engine client](https://github.com/qwirlex/aegis-croo/blob/master/provider/src/engine.ts): `provider/src/engine.ts`
- [Report link builder](https://github.com/qwirlex/aegis-croo/blob/master/provider/src/report-link.ts): `provider/src/report-link.ts`

### Report web app

- [Short-link API](https://github.com/qwirlex/aegis-croo/blob/master/web/src/app/api/r/route.ts): `web/src/app/api/r/route.ts`
- [Report page](https://github.com/qwirlex/aegis-croo/blob/master/web/src/app/report/ReportPageClient.tsx): `web/src/app/report/ReportPageClient.tsx`
- [Report renderer](https://github.com/qwirlex/aegis-croo/blob/master/web/src/components/ReportView.tsx): `web/src/components/ReportView.tsx`
- [Short-link store](https://github.com/qwirlex/aegis-croo/blob/master/web/src/lib/store.ts): `web/src/lib/store.ts`

### External services

- **CROO CAP**
- **Block explorer**
- **Vertex AI Gemini**
- **Base chain**

### Other components

- **Buyer / agent**

## Connections

- Buyer / agent → CROO CAP: places order (evidence: `README.md`)
- CROO CAP → CAP event listener: sends events (evidence: `README.md`)
- CAP event listener → CROO CAP: accepts and delivers (evidence: `provider/src/listener.ts`)
- CAP event listener → Engine client: requests audit (evidence: `provider/src/listener.ts`)
- Engine client → Audit API: posts audit (evidence: `provider/src/engine.ts`)
- Audit API → Single-pass audit: runs single pass (evidence: `engine/aegis_engine/app.py`)
- Audit API → Deep audit: runs deep audit (evidence: `engine/aegis_engine/app.py`)
- Audit API → Audit job store: tracks jobs (evidence: `engine/aegis_engine/app.py`)
- Audit API → Slither analysis: runs quick scan (evidence: `engine/aegis_engine/app.py`)
- Single-pass audit → Source resolver: resolves source (evidence: `engine/aegis_engine/audit.py`)
- Single-pass audit → Slither analysis: analyzes source (evidence: `engine/aegis_engine/audit.py`)
- Single-pass audit → LLM reasoning: reasons findings (evidence: `engine/aegis_engine/audit.py`)
- Source resolver → Chain catalog: validates chain (evidence: `engine/aegis_engine/source.py`)
- Source resolver → Block explorer: fetches verified source (evidence: `engine/aegis_engine/source.py`)
- Slither analysis → Base chain: analyzes deployed target
- Deep audit → Source resolver: prepares target (evidence: `engine/aegis_engine/deep_audit.py`)
- Deep audit → Slither analysis: runs static analysis (evidence: `engine/aegis_engine/deep_audit.py`)
- Deep audit → Contract inventory: builds inventory (evidence: `engine/aegis_engine/deep_audit.py`)
- Deep audit → Focused LLM lenses: runs focused checks (evidence: `engine/aegis_engine/deep_audit.py`)
- Deep audit → LLM reasoning: generates summary (evidence: `engine/aegis_engine/deep_audit.py`)
- Deep audit → Finding merge: merges findings (evidence: `engine/aegis_engine/deep_audit.py`)
- Deep audit → Finding refutation: refutes findings (evidence: `engine/aegis_engine/deep_audit.py`)
- Deep audit → Risk scoring: scores risk (evidence: `engine/aegis_engine/deep_audit.py`)
- Deep audit → Report integrity: signs report (evidence: `engine/aegis_engine/deep_audit.py`)
- Deep audit → Report models: builds report (evidence: `engine/aegis_engine/deep_audit.py`)
- Focused LLM lenses → LLM reasoning: requests model output (evidence: `engine/aegis_engine/lenses.py`)
- LLM reasoning → Vertex AI Gemini: generates content (evidence: `engine/aegis_engine/llm.py`)
- CAP event listener → Report link builder: builds deliverable (evidence: `provider/src/listener.ts`)
- CAP event listener → CROO CAP: commits report hash (evidence: `README.md`)
- Report link builder → Short-link API: stores report (evidence: `provider/src/report-link.ts`)
- Report page → Report renderer: renders report (evidence: `web/src/app/report/ReportPageClient.tsx`)
- Buyer / agent → Report page: views report (evidence: `README.md`)
- Short-link API → Short-link store: stores short link
- Base chain → Buyer / agent: anchors proof (evidence: `README.md`)
