# qingyun1022/smart_contract_reviewer architecture

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

- Interactive diagram: https://gitdiagram.com/qingyun1022/smart_contract_reviewer
- Repository: https://github.com/qingyun1022/smart_contract_reviewer

## Overview

This is a Streamlit-based smart contract review system. Its intended user journey is upload a contract, follow analysis progress, and view a review report; however, the sampled upload handler explicitly leaves submission processing as a TODO, so no runtime link from upload to analysis is established. The repository includes clause parsing, specialized analysis agents, model routing, Chroma storage, and RabbitMQ connection support. README-described pricing, budget, and RAG capabilities lack corresponding source paths in the supplied tree, so they are noted without invented implementation links.

Main entry points: [`app/main.py`](https://github.com/qingyun1022/smart_contract_reviewer/blob/main/app/main.py) (Page router), [`agents/base/base_agent.py`](https://github.com/qingyun1022/smart_contract_reviewer/blob/main/agents/base/base_agent.py) (Agent base), [`agents/pipeline_agents/contract_analyst_agent.py`](https://github.com/qingyun1022/smart_contract_reviewer/blob/main/agents/pipeline_agents/contract_analyst_agent.py) (Contract analyst), [`app/main_pages/upload_page.py`](https://github.com/qingyun1022/smart_contract_reviewer/blob/main/app/main_pages/upload_page.py) (Contract upload)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_app["Page router<br/>[main.py]"]
  node_sidebar["Navigation<br/>[sidebar.py]"]
  node_upload["Contract upload<br/>[upload_page.py]"]
  node_other_pages["Analysis and report pages"]
end

subgraph group_analysis["Contract analysis"]
  node_parser["Clause parser<br/>[clause_parser.py]"]
  node_base_agent["Agent base<br/>[base_agent.py]"]
  node_contract_agent["Contract analyst"]
  node_legal_agent["Legal counsel"]
  node_risk_agent["Risk analyst"]
  node_report_agent["Report generator"]
  node_pricing["Price analysis and library"]
  node_knowledge[("Legal knowledge RAG")]
end

subgraph group_platform["Runtime services"]
  node_model_router["Model router<br/>[model_router.py]"]
  node_chroma[("Vector store client<br/>[chroma_client.py]")]
  node_broker_connection["Broker connection<br/>[connection.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_logger["Logging<br/>[logger.py]"]
  node_budget["Budget monitoring"]
end

subgraph group_reliability["Error handling"]
  node_dead_letter["Dead-letter handling"]
  node_retry["Retry strategy<br/>[retry_strategy.py]"]
  node_intervention["Human intervention"]
end

node_user(("Legal professional"))
node_rabbitmq["RabbitMQ"]

node_user -->|"uses"| node_app
node_app -->|"renders navigation"| node_sidebar
node_app -->|"routes to"| node_upload
node_app -->|"routes to"| node_other_pages
node_user -->|"selects contract"| node_upload
node_contract_agent -->|"inherits"| node_base_agent
node_legal_agent -->|"inherits"| node_base_agent
node_risk_agent -->|"inherits"| node_base_agent
node_report_agent -->|"inherits"| node_base_agent
node_broker_connection -->|"connects to"| node_rabbitmq
node_dead_letter -->|"notifies"| node_intervention
node_model_router -.->|"supports analysis"| node_knowledge
node_parser -.->|"provides clauses"| node_contract_agent

click node_app "https://github.com/qingyun1022/smart_contract_reviewer/blob/main/app/main.py"
click node_sidebar "https://github.com/qingyun1022/smart_contract_reviewer/blob/main/app/components/sidebar.py"
click node_upload "https://github.com/qingyun1022/smart_contract_reviewer/blob/main/app/main_pages/upload_page.py"
click node_parser "https://github.com/qingyun1022/smart_contract_reviewer/blob/main/core_services/contract_processor/clause_parser.py"
click node_base_agent "https://github.com/qingyun1022/smart_contract_reviewer/blob/main/agents/base/base_agent.py"
click node_contract_agent "https://github.com/qingyun1022/smart_contract_reviewer/blob/main/agents/pipeline_agents/contract_analyst_agent.py"
click node_legal_agent "https://github.com/qingyun1022/smart_contract_reviewer/blob/main/agents/pipeline_agents/legal_counsel_agent.py"
click node_risk_agent "https://github.com/qingyun1022/smart_contract_reviewer/blob/main/agents/pipeline_agents/risk_analyst_agent.py"
click node_report_agent "https://github.com/qingyun1022/smart_contract_reviewer/blob/main/agents/pipeline_agents/report_generator_agent.py"
click node_model_router "https://github.com/qingyun1022/smart_contract_reviewer/blob/main/model_services/model_router.py"
click node_chroma "https://github.com/qingyun1022/smart_contract_reviewer/blob/main/data_storage/chroma/chroma_client.py"
click node_broker_connection "https://github.com/qingyun1022/smart_contract_reviewer/blob/main/message_broker/core/connection.py"
click node_config "https://github.com/qingyun1022/smart_contract_reviewer/blob/main/common/config.py"
click node_logger "https://github.com/qingyun1022/smart_contract_reviewer/blob/main/common/logger.py"
click node_dead_letter "https://github.com/qingyun1022/smart_contract_reviewer/blob/main/agents/error_handling/dead_letter_handler.py"
click node_retry "https://github.com/qingyun1022/smart_contract_reviewer/blob/main/agents/error_handling/retry_strategy.py"
click node_intervention "https://github.com/qingyun1022/smart_contract_reviewer/blob/main/agents/error_handling/human_intervention.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_app,node_sidebar,node_upload,node_other_pages toneBlue
class node_parser,node_base_agent,node_contract_agent,node_legal_agent,node_risk_agent,node_report_agent,node_pricing,node_knowledge toneAmber
class node_model_router,node_chroma,node_broker_connection,node_config,node_logger,node_budget toneMint
class node_dead_letter,node_retry,node_intervention toneRose
class node_user,node_rabbitmq toneIndigo
```

## Components

### User interface

- [Page router](https://github.com/qingyun1022/smart_contract_reviewer/blob/main/app/main.py): `app/main.py`
- [Navigation](https://github.com/qingyun1022/smart_contract_reviewer/blob/main/app/components/sidebar.py): `app/components/sidebar.py`
- [Contract upload](https://github.com/qingyun1022/smart_contract_reviewer/blob/main/app/main_pages/upload_page.py): `app/main_pages/upload_page.py`
- **Analysis and report pages**

### Contract analysis

- [Clause parser](https://github.com/qingyun1022/smart_contract_reviewer/blob/main/core_services/contract_processor/clause_parser.py): `core_services/contract_processor/clause_parser.py`
- [Agent base](https://github.com/qingyun1022/smart_contract_reviewer/blob/main/agents/base/base_agent.py): `agents/base/base_agent.py`
- [Contract analyst](https://github.com/qingyun1022/smart_contract_reviewer/blob/main/agents/pipeline_agents/contract_analyst_agent.py): `agents/pipeline_agents/contract_analyst_agent.py`
- [Legal counsel](https://github.com/qingyun1022/smart_contract_reviewer/blob/main/agents/pipeline_agents/legal_counsel_agent.py): `agents/pipeline_agents/legal_counsel_agent.py`
- [Risk analyst](https://github.com/qingyun1022/smart_contract_reviewer/blob/main/agents/pipeline_agents/risk_analyst_agent.py): `agents/pipeline_agents/risk_analyst_agent.py`
- [Report generator](https://github.com/qingyun1022/smart_contract_reviewer/blob/main/agents/pipeline_agents/report_generator_agent.py): `agents/pipeline_agents/report_generator_agent.py`
- **Price analysis and library**
- **Legal knowledge RAG**

### Runtime services

- [Model router](https://github.com/qingyun1022/smart_contract_reviewer/blob/main/model_services/model_router.py): `model_services/model_router.py`
- [Vector store client](https://github.com/qingyun1022/smart_contract_reviewer/blob/main/data_storage/chroma/chroma_client.py): `data_storage/chroma/chroma_client.py`
- [Broker connection](https://github.com/qingyun1022/smart_contract_reviewer/blob/main/message_broker/core/connection.py): `message_broker/core/connection.py`
- [Configuration](https://github.com/qingyun1022/smart_contract_reviewer/blob/main/common/config.py): `common/config.py`
- [Logging](https://github.com/qingyun1022/smart_contract_reviewer/blob/main/common/logger.py): `common/logger.py`
- **Budget monitoring**

### Error handling

- [Dead-letter handling](https://github.com/qingyun1022/smart_contract_reviewer/blob/main/agents/error_handling/dead_letter_handler.py): `agents/error_handling/dead_letter_handler.py`
- [Retry strategy](https://github.com/qingyun1022/smart_contract_reviewer/blob/main/agents/error_handling/retry_strategy.py): `agents/error_handling/retry_strategy.py`
- [Human intervention](https://github.com/qingyun1022/smart_contract_reviewer/blob/main/agents/error_handling/human_intervention.py): `agents/error_handling/human_intervention.py`

### Other components

- **Legal professional**
- **RabbitMQ**

## Connections

- Legal professional → Page router: uses (evidence: `README.md`)
- Page router → Navigation: renders navigation (evidence: `app/main.py`)
- Page router → Contract upload: routes to (evidence: `app/main.py`)
- Page router → Analysis and report pages: routes to (evidence: `app/main.py`)
- Legal professional → Contract upload: selects contract (evidence: `app/main_pages/upload_page.py`)
- Contract analyst → Agent base: inherits (evidence: `agents/pipeline_agents/contract_analyst_agent.py`)
- Legal counsel → Agent base: inherits (evidence: `agents/pipeline_agents/legal_counsel_agent.py`)
- Risk analyst → Agent base: inherits (evidence: `agents/pipeline_agents/risk_analyst_agent.py`)
- Report generator → Agent base: inherits (evidence: `agents/pipeline_agents/report_generator_agent.py`)
- Broker connection → RabbitMQ: connects to (evidence: `message_broker/core/connection.py`)
- Dead-letter handling → Human intervention: notifies (evidence: `agents/error_handling/dead_letter_handler.py`)
- Model router → Legal knowledge RAG: supports analysis
- Clause parser → Contract analyst: provides clauses
