# mmansii/builderr-signalpost architecture

> Architecture diagram of the GitHub repository mmansii/builderr-signalpost, 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/mmansii/builderr-signalpost
- Repository: https://github.com/mmansii/builderr-signalpost

## Overview

Signalpost is a Norwegian-company research agent that turns organisation-number batches into auditable company profiles and terminal JSONL envelopes. Its main workflow selects or accepts companies, anchors them in the Brønnøysund registry, gathers official and website evidence, checks exact-entity identity, and emits results with provenance and run telemetry. Separate capabilities cover replaying profile changes, screening and evidence-bounded questions, and collecting external-footprint signals. The graph reflects documented workflow and indexed imports; some connector implementations and runtime wiring were not sampled, so uncertain links are omitted.

Main entry points: [`src/norway_company_agent/batch.py`](https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/batch.py) (Competition batch), [`src/norway_company_agent/official.py`](https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/official.py) (Official records), [`src/norway_company_agent/website.py`](https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/website.py) (Company website), [`src/norway_company_agent/evidence.py`](https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/evidence.py) (Evidence records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Input and registry"]
  node_batch_input["Batch input<br/>[batch.py]"]
  node_sampling["Company sampling<br/>[sampling.py]"]
end

subgraph group_research["Evidence gathering"]
  node_registry["BRREG registry<br/>[official.py]"]
  node_official_data["Official records<br/>[official.py]"]
  node_http["HTTP fetching<br/>[http.py]"]
  node_website["Company website<br/>[website.py]"]
  node_discovery["Site discovery<br/>[discovery.py]"]
  node_crawl_events["Crawl extraction<br/>[crawl_events.py]"]
  node_scrapy["Resumable crawler<br/>[scrapy_crawler.py]"]
end

subgraph group_validation["Identity and evidence"]
  node_identity["Entity identity gate<br/>[identity.py]"]
  node_evidence["Evidence records<br/>[evidence.py]"]
end

subgraph group_outputs["Profiles and analysis"]
  node_batch_run["Competition batch<br/>[batch.py]"]
  node_refresh["Refresh replay<br/>[refresh.py]"]
  node_snapshots["Saved snapshots<br/>[snapshots.py]"]
  node_research_agent["Research and screening<br/>[research.py]"]
  node_workspace["Research workspace<br/>[workspace.py]"]
end

subgraph group_extensions["External signals"]
  node_external["Footprint validation"]
  node_external_control["Coverage evaluation"]
  node_sentiment["Sentiment analysis<br/>[sentiment.py]"]
  node_connectors["External connectors"]
end

node_operator(("Research operator"))
node_company_sources(("Company data sources"))

node_operator -->|"selects sample"| node_sampling
node_operator -->|"submits batch"| node_batch_input
node_batch_input -->|"provides companies"| node_batch_run
node_sampling -.->|"produces batch"| node_batch_input
node_batch_run -->|"anchors identity"| node_registry
node_registry -->|"fetches records"| node_official_data
node_official_data -->|"fetches JSON"| node_http
node_batch_run -->|"visits listed site"| node_website
node_website -->|"finds site candidates"| node_discovery
node_scrapy -->|"emits page events"| node_crawl_events
node_crawl_events -->|"records website evidence"| node_evidence
node_batch_run -->|"checks entity match"| node_identity
node_identity -->|"gates publication"| node_evidence
node_batch_run -->|"records provenance"| node_evidence
node_batch_run -->|"emits envelopes"| node_operator
node_refresh -->|"replays snapshots"| node_snapshots
node_research_agent -->|"uses workspace"| node_workspace
node_operator -->|"asks or screens"| node_research_agent
node_connectors -.->|"supplies observations"| node_external
node_external_control -->|"scores footprint"| node_external
node_sentiment -.->|"enriches observations"| node_external
node_company_sources -->|"provides records"| node_official_data
node_company_sources -->|"hosts company site"| node_website
node_company_sources -.->|"provides public signals"| node_connectors

click node_batch_input "https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/batch.py"
click node_sampling "https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/sampling.py"
click node_registry "https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/official.py"
click node_official_data "https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/official.py"
click node_http "https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/http.py"
click node_website "https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/website.py"
click node_discovery "https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/discovery.py"
click node_crawl_events "https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/crawl_events.py"
click node_scrapy "https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/scrapy_crawler.py"
click node_identity "https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/identity.py"
click node_evidence "https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/evidence.py"
click node_batch_run "https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/batch.py"
click node_refresh "https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/refresh.py"
click node_snapshots "https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/snapshots.py"
click node_research_agent "https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/research.py"
click node_workspace "https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/workspace.py"
click node_external "https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/external_footprint.py"
click node_external_control "https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/external_control.py"
click node_sentiment "https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/sentiment.py"
click node_connectors "https://github.com/mmansii/builderr-signalpost/tree/main/scripts"

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_batch_input,node_sampling toneBlue
class node_registry,node_official_data,node_http,node_website,node_discovery,node_crawl_events,node_scrapy toneAmber
class node_identity,node_evidence toneMint
class node_batch_run,node_refresh,node_snapshots,node_research_agent,node_workspace toneRose
class node_external,node_external_control,node_sentiment,node_connectors,node_operator,node_company_sources toneIndigo
```

## Components

### Input and registry

- [Batch input](https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/batch.py): `src/norway_company_agent/batch.py`
- [Company sampling](https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/sampling.py): `src/norway_company_agent/sampling.py`

### Evidence gathering

- [BRREG registry](https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/official.py): `src/norway_company_agent/official.py`
- [Official records](https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/official.py): `src/norway_company_agent/official.py`
- [HTTP fetching](https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/http.py): `src/norway_company_agent/http.py`
- [Company website](https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/website.py): `src/norway_company_agent/website.py`
- [Site discovery](https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/discovery.py): `src/norway_company_agent/discovery.py`
- [Crawl extraction](https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/crawl_events.py): `src/norway_company_agent/crawl_events.py`
- [Resumable crawler](https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/scrapy_crawler.py): `src/norway_company_agent/scrapy_crawler.py`

### Identity and evidence

- [Entity identity gate](https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/identity.py): `src/norway_company_agent/identity.py`
- [Evidence records](https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/evidence.py): `src/norway_company_agent/evidence.py`

### Profiles and analysis

- [Competition batch](https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/batch.py): `src/norway_company_agent/batch.py`
- [Refresh replay](https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/refresh.py): `src/norway_company_agent/refresh.py`
- [Saved snapshots](https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/snapshots.py): `src/norway_company_agent/snapshots.py`
- [Research and screening](https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/research.py): `src/norway_company_agent/research.py`
- [Research workspace](https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/workspace.py): `src/norway_company_agent/workspace.py`

### External signals

- [Footprint validation](https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/external_footprint.py): `src/norway_company_agent/external_footprint.py`
- [Coverage evaluation](https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/external_control.py): `src/norway_company_agent/external_control.py`
- [Sentiment analysis](https://github.com/mmansii/builderr-signalpost/blob/main/src/norway_company_agent/sentiment.py): `src/norway_company_agent/sentiment.py`
- [External connectors](https://github.com/mmansii/builderr-signalpost/tree/main/scripts): `scripts`

### Other components

- **Research operator**
- **Company data sources**

## Connections

- Research operator → Company sampling: selects sample
- Research operator → Batch input: submits batch
- Batch input → Competition batch: provides companies (evidence: `src/norway_company_agent/batch.py`)
- Company sampling → Batch input: produces batch (evidence: `src/norway_company_agent/batch.py`)
- Competition batch → BRREG registry: anchors identity (evidence: `src/norway_company_agent/batch.py`)
- BRREG registry → Official records: fetches records (evidence: `src/norway_company_agent/official.py`)
- Official records → HTTP fetching: fetches JSON (evidence: `src/norway_company_agent/official.py`)
- Competition batch → Company website: visits listed site
- Company website → Site discovery: finds site candidates (evidence: `src/norway_company_agent/discovery.py`)
- Resumable crawler → Crawl extraction: emits page events (evidence: `src/norway_company_agent/scrapy_crawler.py`)
- Crawl extraction → Evidence records: records website evidence (evidence: `src/norway_company_agent/crawl_events.py`)
- Competition batch → Entity identity gate: checks entity match
- Entity identity gate → Evidence records: gates publication (evidence: `src/norway_company_agent/identity.py`)
- Competition batch → Evidence records: records provenance (evidence: `src/norway_company_agent/batch.py`)
- Competition batch → Research operator: emits envelopes
- Refresh replay → Saved snapshots: replays snapshots (evidence: `src/norway_company_agent/snapshots.py`)
- Research and screening → Research workspace: uses workspace (evidence: `scripts/evaluate_research_agent.py`)
- Research operator → Research and screening: asks or screens
- External connectors → Footprint validation: supplies observations (evidence: `scripts/evaluate_external_footprint.py`)
- Coverage evaluation → Footprint validation: scores footprint (evidence: `src/norway_company_agent/external_control.py`)
- Sentiment analysis → Footprint validation: enriches observations
- Company data sources → Official records: provides records
- Company data sources → Company website: hosts company site
- Company data sources → External connectors: provides public signals
