# mjangra356/clearview-backend architecture

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

- Interactive diagram: https://gitdiagram.com/mjangra356/clearview-backend
- Repository: https://github.com/mjangra356/clearview-backend

## Overview

ClearView is a FastAPI service for live UK company fraud and AML compliance assessments. A user searches Companies House or requests a company assessment; the API fetches and normalizes company, officer, appointment, and PSC data, then produces statutory checks, risk scoring, ownership views, and an executive summary for the UI. The main internal layers are the Companies House client, dossier aggregator, compliance rules, and response projections. The README is empty; links reflect the shown excerpts and source index, so unsampled subsystem details are not inferred.

Main entry points: [`app/api/routes.py`](https://github.com/mjangra356/clearview-backend/blob/main/app/api/routes.py) (Company Routes), [`app/services/ch_client.py`](https://github.com/mjangra356/clearview-backend/blob/main/app/services/ch_client.py) (Companies House Client), [`app/services/aggregator.py`](https://github.com/mjangra356/clearview-backend/blob/main/app/services/aggregator.py) (Dossier Aggregator), [`app/services/llm_service.py`](https://github.com/mjangra356/clearview-backend/blob/main/app/services/llm_service.py) (Summary Generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API"]
  node_app["FastAPI App<br/>[main.py]"]
  node_routes["Company Routes<br/>[routes.py]"]
  node_config["Service Settings<br/>[config.py]"]
end

subgraph group_ingest["Company Data"]
  node_ch_client["Companies House Client<br/>[ch_client.py]"]
  node_raw_models["API Schemas"]
  node_aggregator["Dossier Aggregator<br/>[aggregator.py]"]
  node_domain["Company Dossier<br/>[domain.py]"]
end

subgraph group_assessment["Risk Assessment"]
  node_reference_data["Risk Reference Data<br/>[reference_data.py]"]
  node_rules["Compliance Rules<br/>[rules_engine.py]"]
  node_ownership["Ownership Analysis"]
  node_llm["Summary Generator<br/>[llm_service.py]"]
end

subgraph group_presentation["Investigation Output"]
  node_dto["UI Response Models<br/>[dto.py]"]
end

node_user(("Analyst"))
node_companies_house["Companies House"]
node_llm_provider["LLM Providers"]

node_user -->|"requests assessment"| node_app
node_app -->|"mounts routes"| node_routes
node_app -->|"loads settings"| node_config
node_app -->|"closes client"| node_ch_client
node_routes -->|"searches companies"| node_ch_client
node_routes -->|"builds dossier"| node_aggregator
node_routes -->|"evaluates risk"| node_rules
node_routes -->|"builds ownership views"| node_ownership
node_routes -->|"generates summary"| node_llm
node_routes -->|"returns UI payload"| node_dto
node_ch_client -->|"fetches company data"| node_companies_house
node_ch_client -->|"reads API settings"| node_config
node_ch_client -->|"returns API schemas"| node_raw_models
node_aggregator -->|"fetches company records"| node_ch_client
node_aggregator -->|"normalizes API data"| node_raw_models
node_aggregator -->|"uses risk classifications"| node_reference_data
node_aggregator -->|"builds dossier"| node_domain
node_rules -->|"evaluates dossier"| node_domain
node_rules -->|"uses rule indicators"| node_reference_data
node_rules -->|"produces findings"| node_dto
node_ownership -->|"projects ownership"| node_domain
node_ownership -->|"builds ownership DTOs"| node_dto
node_llm -->|"summarizes dossier"| node_domain
node_llm -->|"uses risk flags"| node_dto
node_llm -->|"reads provider keys"| node_config
node_llm -.->|"requests generated text"| node_llm_provider

click node_app "https://github.com/mjangra356/clearview-backend/blob/main/app/main.py"
click node_routes "https://github.com/mjangra356/clearview-backend/blob/main/app/api/routes.py"
click node_ch_client "https://github.com/mjangra356/clearview-backend/blob/main/app/services/ch_client.py"
click node_raw_models "https://github.com/mjangra356/clearview-backend/blob/main/app/models/raw_companies_house.py"
click node_aggregator "https://github.com/mjangra356/clearview-backend/blob/main/app/services/aggregator.py"
click node_domain "https://github.com/mjangra356/clearview-backend/blob/main/app/models/domain.py"
click node_reference_data "https://github.com/mjangra356/clearview-backend/blob/main/app/core/reference_data.py"
click node_rules "https://github.com/mjangra356/clearview-backend/blob/main/app/services/rules_engine.py"
click node_ownership "https://github.com/mjangra356/clearview-backend/blob/main/app/services/ownership_builder.py"
click node_llm "https://github.com/mjangra356/clearview-backend/blob/main/app/services/llm_service.py"
click node_config "https://github.com/mjangra356/clearview-backend/blob/main/app/core/config.py"
click node_dto "https://github.com/mjangra356/clearview-backend/blob/main/app/models/dto.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_routes,node_config toneBlue
class node_ch_client,node_raw_models,node_aggregator,node_domain toneAmber
class node_reference_data,node_rules,node_ownership,node_llm toneMint
class node_dto toneRose
class node_user,node_companies_house,node_llm_provider toneIndigo
```

## Components

### API

- [FastAPI App](https://github.com/mjangra356/clearview-backend/blob/main/app/main.py): `app/main.py`
- [Company Routes](https://github.com/mjangra356/clearview-backend/blob/main/app/api/routes.py): `app/api/routes.py`
- [Service Settings](https://github.com/mjangra356/clearview-backend/blob/main/app/core/config.py): `app/core/config.py`

### Company Data

- [Companies House Client](https://github.com/mjangra356/clearview-backend/blob/main/app/services/ch_client.py): `app/services/ch_client.py`
- [API Schemas](https://github.com/mjangra356/clearview-backend/blob/main/app/models/raw_companies_house.py): `app/models/raw_companies_house.py`
- [Dossier Aggregator](https://github.com/mjangra356/clearview-backend/blob/main/app/services/aggregator.py): `app/services/aggregator.py`
- [Company Dossier](https://github.com/mjangra356/clearview-backend/blob/main/app/models/domain.py): `app/models/domain.py`

### Risk Assessment

- [Risk Reference Data](https://github.com/mjangra356/clearview-backend/blob/main/app/core/reference_data.py): `app/core/reference_data.py`
- [Compliance Rules](https://github.com/mjangra356/clearview-backend/blob/main/app/services/rules_engine.py): `app/services/rules_engine.py`
- [Ownership Analysis](https://github.com/mjangra356/clearview-backend/blob/main/app/services/ownership_builder.py): `app/services/ownership_builder.py`
- [Summary Generator](https://github.com/mjangra356/clearview-backend/blob/main/app/services/llm_service.py): `app/services/llm_service.py`

### Investigation Output

- [UI Response Models](https://github.com/mjangra356/clearview-backend/blob/main/app/models/dto.py): `app/models/dto.py`

### Other components

- **Analyst**
- **Companies House**
- **LLM Providers**

## Connections

- Analyst → FastAPI App: requests assessment (evidence: `app/main.py`)
- FastAPI App → Company Routes: mounts routes (evidence: `app/main.py`)
- FastAPI App → Service Settings: loads settings (evidence: `app/main.py`)
- FastAPI App → Companies House Client: closes client (evidence: `app/main.py`)
- Company Routes → Companies House Client: searches companies (evidence: `app/api/routes.py`)
- Company Routes → Dossier Aggregator: builds dossier (evidence: `app/api/routes.py`)
- Company Routes → Compliance Rules: evaluates risk (evidence: `app/api/routes.py`)
- Company Routes → Ownership Analysis: builds ownership views (evidence: `app/api/routes.py`)
- Company Routes → Summary Generator: generates summary (evidence: `app/api/routes.py`)
- Company Routes → UI Response Models: returns UI payload (evidence: `app/api/routes.py`)
- Companies House Client → Companies House: fetches company data (evidence: `app/services/ch_client.py`)
- Companies House Client → Service Settings: reads API settings (evidence: `app/services/ch_client.py`)
- Companies House Client → API Schemas: returns API schemas (evidence: `app/services/ch_client.py`)
- Dossier Aggregator → Companies House Client: fetches company records (evidence: `app/services/aggregator.py`)
- Dossier Aggregator → API Schemas: normalizes API data (evidence: `app/services/aggregator.py`)
- Dossier Aggregator → Risk Reference Data: uses risk classifications (evidence: `app/services/aggregator.py`)
- Dossier Aggregator → Company Dossier: builds dossier (evidence: `app/services/aggregator.py`)
- Compliance Rules → Company Dossier: evaluates dossier (evidence: `app/services/rules_engine.py`)
- Compliance Rules → Risk Reference Data: uses rule indicators (evidence: `app/services/rules_engine.py`)
- Compliance Rules → UI Response Models: produces findings (evidence: `app/services/rules_engine.py`)
- Ownership Analysis → Company Dossier: projects ownership (evidence: `app/services/ownership_builder.py`)
- Ownership Analysis → UI Response Models: builds ownership DTOs (evidence: `app/services/ownership_builder.py`)
- Summary Generator → Company Dossier: summarizes dossier (evidence: `app/services/llm_service.py`)
- Summary Generator → UI Response Models: uses risk flags (evidence: `app/services/llm_service.py`)
- Summary Generator → Service Settings: reads provider keys (evidence: `app/services/llm_service.py`)
- Summary Generator → LLM Providers: requests generated text (evidence: `app/services/llm_service.py`)
