# ravora0809/signalpost architecture

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

- Interactive diagram: https://gitdiagram.com/ravora0809/signalpost
- Repository: https://github.com/ravora0809/signalpost

## Overview

Signalpost researches Norwegian companies and collects public evidence about them. The main workflow validates an organization number, checks PostgreSQL first, and fetches from Brønnøysundregistrene only when the company is absent; verified company data is then persisted and returned. A separate source-collection workflow discovers candidate URLs, fetches and verifies their content, and stores source metadata and hashes. Source relationships follow the README and SOURCE INDEX; excerpts do not expose every route or service call, so uncertain connections are omitted.

Main entry points: [`app/api/routes.py`](https://github.com/ravora0809/signalpost/blob/main/app/api/routes.py) (HTTP routes), [`app/services/source.py`](https://github.com/ravora0809/signalpost/blob/main/app/services/source.py) (Source collection), [`app/sources/discovery.py`](https://github.com/ravora0809/signalpost/blob/main/app/sources/discovery.py) (Candidate discovery), [`app/config.py`](https://github.com/ravora0809/signalpost/blob/main/app/config.py) (Runtime settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_company_research["Company research"]
  node_http_api["HTTP routes<br/>[routes.py]"]
  node_company_schema["Company validation<br/>[company.py]"]
  node_company_service["Company lookup<br/>[company.py]"]
  node_brreg_client["Brreg client<br/>[brreg.py]"]
end

subgraph group_source_collection["Source collection"]
  node_source_service["Source collection<br/>[source.py]"]
  node_source_discovery["Candidate discovery<br/>[discovery.py]"]
  node_search_provider["Search provider<br/>[search.py]"]
  node_web_fetcher["Web fetching<br/>[web.py]"]
  node_identity_check["Identity verification<br/>[source_identity.py]"]
  node_source_schema["Source schemas<br/>[source.py]"]
end

subgraph group_data_layer["Data layer"]
  node_db_sessions["Database sessions<br/>[database.py]"]
  node_orm_models[("Company and source records<br/>[models.py]")]
end

subgraph group_runtime_config["Runtime configuration"]
  node_settings["Runtime settings<br/>[config.py]"]
end

node_caller(("API caller"))
node_brreg_api["Brreg registry"]
node_search_service["Configured search"]
node_public_web["Public websites"]

node_caller -->|"sends requests"| node_http_api
node_http_api -->|"validates input"| node_company_schema
node_http_api -->|"requests research"| node_company_service
node_company_service -->|"reads and persists"| node_orm_models
node_company_service -->|"fetches missing company"| node_brreg_client
node_brreg_client -->|"requests registry data"| node_brreg_api
node_http_api -->|"injects session"| node_db_sessions
node_db_sessions -->|"loads database URL"| node_settings
node_http_api -->|"collects sources"| node_source_service
node_http_api -->|"queries source records"| node_orm_models
node_source_service -->|"discovers candidates"| node_source_discovery
node_source_discovery -->|"adds registry candidate"| node_brreg_client
node_source_discovery -->|"searches candidates"| node_search_provider
node_search_provider -.->|"queries optionally"| node_search_service
node_source_discovery -->|"fetches candidates"| node_web_fetcher
node_web_fetcher -->|"retrieves pages"| node_public_web
node_source_service -->|"fetches candidate URLs"| node_web_fetcher
node_source_service -->|"verifies identity"| node_identity_check
node_source_service -->|"stores source evidence"| node_orm_models
node_source_service -->|"uses collection limits"| node_settings
node_source_discovery -->|"configures discovery"| node_settings
node_search_provider -->|"loads provider config"| node_settings

click node_http_api "https://github.com/ravora0809/signalpost/blob/main/app/api/routes.py"
click node_company_schema "https://github.com/ravora0809/signalpost/blob/main/app/schemas/company.py"
click node_company_service "https://github.com/ravora0809/signalpost/blob/main/app/services/company.py"
click node_brreg_client "https://github.com/ravora0809/signalpost/blob/main/app/sources/brreg.py"
click node_source_service "https://github.com/ravora0809/signalpost/blob/main/app/services/source.py"
click node_source_discovery "https://github.com/ravora0809/signalpost/blob/main/app/sources/discovery.py"
click node_search_provider "https://github.com/ravora0809/signalpost/blob/main/app/sources/search.py"
click node_web_fetcher "https://github.com/ravora0809/signalpost/blob/main/app/sources/web.py"
click node_identity_check "https://github.com/ravora0809/signalpost/blob/main/app/validation/source_identity.py"
click node_source_schema "https://github.com/ravora0809/signalpost/blob/main/app/schemas/source.py"
click node_db_sessions "https://github.com/ravora0809/signalpost/blob/main/app/database/database.py"
click node_orm_models "https://github.com/ravora0809/signalpost/blob/main/app/database/models.py"
click node_settings "https://github.com/ravora0809/signalpost/blob/main/app/config.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_http_api,node_company_schema,node_company_service,node_brreg_client toneBlue
class node_source_service,node_source_discovery,node_search_provider,node_web_fetcher,node_identity_check,node_source_schema toneAmber
class node_db_sessions,node_orm_models,node_caller toneMint
class node_settings toneRose
class node_brreg_api,node_search_service,node_public_web toneIndigo
```

## Components

### Company research

- [HTTP routes](https://github.com/ravora0809/signalpost/blob/main/app/api/routes.py): `app/api/routes.py`
- [Company validation](https://github.com/ravora0809/signalpost/blob/main/app/schemas/company.py): `app/schemas/company.py`
- [Company lookup](https://github.com/ravora0809/signalpost/blob/main/app/services/company.py): `app/services/company.py`
- [Brreg client](https://github.com/ravora0809/signalpost/blob/main/app/sources/brreg.py): `app/sources/brreg.py`

### Source collection

- [Source collection](https://github.com/ravora0809/signalpost/blob/main/app/services/source.py): `app/services/source.py`
- [Candidate discovery](https://github.com/ravora0809/signalpost/blob/main/app/sources/discovery.py): `app/sources/discovery.py`
- [Search provider](https://github.com/ravora0809/signalpost/blob/main/app/sources/search.py): `app/sources/search.py`
- [Web fetching](https://github.com/ravora0809/signalpost/blob/main/app/sources/web.py): `app/sources/web.py`
- [Identity verification](https://github.com/ravora0809/signalpost/blob/main/app/validation/source_identity.py): `app/validation/source_identity.py`
- [Source schemas](https://github.com/ravora0809/signalpost/blob/main/app/schemas/source.py): `app/schemas/source.py`

### Data layer

- [Database sessions](https://github.com/ravora0809/signalpost/blob/main/app/database/database.py): `app/database/database.py`
- [Company and source records](https://github.com/ravora0809/signalpost/blob/main/app/database/models.py): `app/database/models.py`

### Runtime configuration

- [Runtime settings](https://github.com/ravora0809/signalpost/blob/main/app/config.py): `app/config.py`

### Other components

- **API caller**
- **Brreg registry**
- **Configured search**
- **Public websites**

## Connections

- API caller → HTTP routes: sends requests (evidence: `README.md`)
- HTTP routes → Company validation: validates input (evidence: `app/api/routes.py`)
- HTTP routes → Company lookup: requests research (evidence: `app/api/routes.py`)
- Company lookup → Company and source records: reads and persists (evidence: `app/services/company.py`)
- Company lookup → Brreg client: fetches missing company (evidence: `app/services/company.py`)
- Brreg client → Brreg registry: requests registry data (evidence: `app/sources/brreg.py`)
- HTTP routes → Database sessions: injects session (evidence: `app/api/routes.py`)
- Database sessions → Runtime settings: loads database URL (evidence: `app/database/database.py`)
- HTTP routes → Source collection: collects sources (evidence: `app/api/routes.py`)
- HTTP routes → Company and source records: queries source records (evidence: `app/api/routes.py`)
- Source collection → Candidate discovery: discovers candidates (evidence: `app/services/source.py`)
- Candidate discovery → Brreg client: adds registry candidate (evidence: `app/sources/discovery.py`)
- Candidate discovery → Search provider: searches candidates (evidence: `app/sources/discovery.py`)
- Search provider → Configured search: queries optionally (evidence: `app/sources/search.py`)
- Candidate discovery → Web fetching: fetches candidates (evidence: `app/sources/discovery.py`)
- Web fetching → Public websites: retrieves pages (evidence: `app/sources/web.py`)
- Source collection → Web fetching: fetches candidate URLs (evidence: `app/services/source.py`)
- Source collection → Identity verification: verifies identity (evidence: `app/services/source.py`)
- Source collection → Company and source records: stores source evidence (evidence: `app/services/source.py`)
- Source collection → Runtime settings: uses collection limits (evidence: `app/services/source.py`)
- Candidate discovery → Runtime settings: configures discovery (evidence: `app/sources/discovery.py`)
- Search provider → Runtime settings: loads provider config (evidence: `app/sources/search.py`)
