# asendz/ai-web3-security-course architecture

> Architecture diagram of the GitHub repository asendz/ai-web3-security-course, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/asendz/ai-web3-security-course
- Repository: https://github.com/asendz/ai-web3-security-course

## Overview

Lucid is a course-built Solidity security harness: an engineer points its CLI at contracts, which are loaded into a numbered source blob, audited by an LLM, and printed as validated findings. Optional Module 2 paths first build protocol context and can repeat the hunt while excluding earlier findings. The README also describes later specialist orchestration and measurement, but those capabilities are not evidenced as runtime components in the supplied tree. The agent excerpt is incomplete, so only documented call relationships are shown.

Main entry points: [`lucid/run.py`](https://github.com/asendz/ai-web3-security-course/blob/master/lucid/run.py) (Scan CLI), [`lucid/llm.py`](https://github.com/asendz/ai-web3-security-course/blob/master/lucid/llm.py) (LLM client), [`lucid/agent.py`](https://github.com/asendz/ai-web3-security-course/blob/master/lucid/agent.py) (Baseline hunt), [`lucid/schema.py`](https://github.com/asendz/ai-web3-security-course/blob/master/lucid/schema.py) (Finding validator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Scan workflow"]
  node_cli["Scan CLI<br/>[run.py]"]
  node_source["Solidity sources"]
  node_loader["Codebase loader<br/>[codebase.py]"]
  node_findings_output["Printed findings<br/>[run.py]"]
end

subgraph group_analysis["Audit logic"]
  node_protocol_context["Context builder<br/>[context.py]"]
  node_baseline_hunt["Baseline hunt<br/>[agent.py]"]
  node_context_hunt["Context-aware hunt<br/>[agent.py]"]
  node_exclusion_loop["Exclusion loop<br/>[agent.py]"]
  node_finding_schema["Finding validator<br/>[schema.py]"]
end

subgraph group_integration["Model boundary"]
  node_llm_client["LLM client<br/>[llm.py]"]
  node_model_service{{"Chat model API"}}
end

node_engineer(("Engineer"))

node_engineer -->|"starts scan"| node_cli
node_cli -->|"loads contracts"| node_loader
node_source -->|"reads Solidity"| node_loader
node_cli -.->|"builds context"| node_protocol_context
node_protocol_context -->|"requests context"| node_llm_client
node_cli -->|"runs hunt"| node_baseline_hunt
node_cli -.->|"runs contextual hunt"| node_context_hunt
node_cli -.->|"runs rounds"| node_exclusion_loop
node_baseline_hunt -->|"requests audit"| node_llm_client
node_context_hunt -.->|"requests audit"| node_llm_client
node_exclusion_loop -.->|"requests rounds"| node_llm_client
node_baseline_hunt -->|"validates findings"| node_finding_schema
node_context_hunt -.->|"validates findings"| node_finding_schema
node_exclusion_loop -.->|"validates findings"| node_finding_schema
node_llm_client -->|"sends prompts"| node_model_service
node_model_service -->|"returns replies"| node_llm_client
node_baseline_hunt -->|"returns findings"| node_cli
node_context_hunt -.->|"returns findings"| node_cli
node_exclusion_loop -.->|"returns findings"| node_cli
node_cli -->|"prints results"| node_findings_output

click node_cli "https://github.com/asendz/ai-web3-security-course/blob/master/lucid/run.py"
click node_source "https://github.com/asendz/ai-web3-security-course/tree/master/target/src"
click node_loader "https://github.com/asendz/ai-web3-security-course/blob/master/lucid/codebase.py"
click node_findings_output "https://github.com/asendz/ai-web3-security-course/blob/master/lucid/run.py"
click node_protocol_context "https://github.com/asendz/ai-web3-security-course/blob/master/lucid/context.py"
click node_baseline_hunt "https://github.com/asendz/ai-web3-security-course/blob/master/lucid/agent.py"
click node_context_hunt "https://github.com/asendz/ai-web3-security-course/blob/master/lucid/agent.py"
click node_exclusion_loop "https://github.com/asendz/ai-web3-security-course/blob/master/lucid/agent.py"
click node_finding_schema "https://github.com/asendz/ai-web3-security-course/blob/master/lucid/schema.py"
click node_llm_client "https://github.com/asendz/ai-web3-security-course/blob/master/lucid/llm.py"

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_cli,node_source,node_loader,node_findings_output toneBlue
class node_protocol_context,node_baseline_hunt,node_context_hunt,node_exclusion_loop,node_finding_schema toneAmber
class node_llm_client,node_model_service toneMint
class node_engineer toneIndigo
```

## Components

### Scan workflow

- [Scan CLI](https://github.com/asendz/ai-web3-security-course/blob/master/lucid/run.py): `lucid/run.py`
- [Solidity sources](https://github.com/asendz/ai-web3-security-course/tree/master/target/src): `target/src`
- [Codebase loader](https://github.com/asendz/ai-web3-security-course/blob/master/lucid/codebase.py): `lucid/codebase.py`
- [Printed findings](https://github.com/asendz/ai-web3-security-course/blob/master/lucid/run.py): `lucid/run.py`

### Audit logic

- [Context builder](https://github.com/asendz/ai-web3-security-course/blob/master/lucid/context.py): `lucid/context.py`
- [Baseline hunt](https://github.com/asendz/ai-web3-security-course/blob/master/lucid/agent.py): `lucid/agent.py`
- [Context-aware hunt](https://github.com/asendz/ai-web3-security-course/blob/master/lucid/agent.py): `lucid/agent.py`
- [Exclusion loop](https://github.com/asendz/ai-web3-security-course/blob/master/lucid/agent.py): `lucid/agent.py`
- [Finding validator](https://github.com/asendz/ai-web3-security-course/blob/master/lucid/schema.py): `lucid/schema.py`

### Model boundary

- [LLM client](https://github.com/asendz/ai-web3-security-course/blob/master/lucid/llm.py): `lucid/llm.py`
- **Chat model API**

### Other components

- **Engineer**

## Connections

- Engineer → Scan CLI: starts scan
- Scan CLI → Codebase loader: loads contracts
- Solidity sources → Codebase loader: reads Solidity
- Scan CLI → Context builder: builds context
- Context builder → LLM client: requests context
- Scan CLI → Baseline hunt: runs hunt
- Scan CLI → Context-aware hunt: runs contextual hunt
- Scan CLI → Exclusion loop: runs rounds
- Baseline hunt → LLM client: requests audit
- Context-aware hunt → LLM client: requests audit
- Exclusion loop → LLM client: requests rounds
- Baseline hunt → Finding validator: validates findings
- Context-aware hunt → Finding validator: validates findings
- Exclusion loop → Finding validator: validates findings
- LLM client → Chat model API: sends prompts
- Chat model API → LLM client: returns replies
- Baseline hunt → Scan CLI: returns findings
- Context-aware hunt → Scan CLI: returns findings
- Exclusion loop → Scan CLI: returns findings
- Scan CLI → Printed findings: prints results