# djsebby/coporatemapper architecture

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

- Interactive diagram: https://gitdiagram.com/djsebby/coporatemapper
- Repository: https://github.com/djsebby/coporatemapper

## Overview

CorporateMapper maps an organisation’s public attack surface into a people directory and phishing-risk view. The main workflow is: a user submits a company website, a background job discovers and prioritises pages, crawls them, extracts people, and stores results in Neo4j; the web UI then presents organisations, profiles, findings, and risk information. Enrichment and demo-profile population are additional capabilities. Several API and enrichment runtime connections are not shown in the excerpts, so those links are marked unverified rather than inferred as definite calls.

Main entry points: [`frontend/src/App.tsx`](https://github.com/djsebby/coporatemapper/blob/main/frontend/src/App.tsx) (Directory UI), [`app/pipeline.py`](https://github.com/djsebby/coporatemapper/blob/main/app/pipeline.py) (Discovery pipeline), [`app/enrichment.py`](https://github.com/djsebby/coporatemapper/blob/main/app/enrichment.py) (Enrichment engine), [`app/crawler/discover.py`](https://github.com/djsebby/coporatemapper/blob/main/app/crawler/discover.py) (Site discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_frontend["Directory UI<br/>[App.tsx]"]
  node_graph["People graph<br/>[Graph.tsx]"]
  node_profile["Person profile<br/>[PersonPanel.tsx]"]
  node_discovery_ui["Discovery controls<br/>[Discovery.tsx]"]
  node_enrichment_ui["Enrichment controls<br/>[Enrichment.tsx]"]
  node_activity["Recent activity<br/>[RecentActivity.tsx]"]
end

subgraph group_discovery["Website discovery"]
  node_pipeline["Discovery pipeline<br/>[pipeline.py]"]
  node_discover["Site discovery<br/>[discover.py]"]
  node_robots["Robots policies<br/>[robots.py]"]
  node_sitemap["Sitemap parsing<br/>[sitemap.py]"]
  node_crawler["Page crawling<br/>[crawler.py]"]
  node_prioritiser["URL prioritiser<br/>[prioritiser.py]"]
end

subgraph group_people["People and risk"]
  node_extractor["Person extraction<br/>[extractor.py]"]
  node_risk["Phishing risk score<br/>[riskscore.py]"]
end

subgraph group_enrichment["Profile enrichment"]
  node_enrichment["Enrichment engine<br/>[enrichment.py]"]
  node_policy["Finding policy"]
  node_sources["Public sources"]
  node_enrich_store["Enrichment store"]
end

subgraph group_persistence["Jobs and storage"]
  node_jobs["Pipeline jobs<br/>[pipeline_jobs.py]"]
  node_database[("Neo4j connection<br/>[database.py]")]
end

node_user(("Operator"))
node_api["HTTP API<br/>[api.py]"]

node_user -->|"uses"| node_frontend
node_frontend -->|"renders"| node_graph
node_frontend -->|"opens"| node_profile
node_frontend -->|"renders"| node_discovery_ui
node_frontend -->|"renders"| node_enrichment_ui
node_frontend -->|"renders"| node_activity
node_frontend -.->|"requests"| node_api
node_api -.->|"dispatches"| node_jobs
node_jobs -->|"runs"| node_pipeline
node_pipeline -->|"discovers URLs"| node_discover
node_pipeline -->|"ranks URLs"| node_prioritiser
node_pipeline -->|"fetches pages"| node_crawler
node_pipeline -->|"processes pages"| node_extractor
node_discover -->|"checks policies"| node_robots
node_discover -->|"reads sitemaps"| node_sitemap
node_crawler -->|"uses ranking"| node_prioritiser
node_database -->|"constructs"| node_extractor
node_api -.->|"exposes operations"| node_enrichment
node_enrichment -->|"applies rules"| node_policy
node_enrichment -->|"queries sources"| node_sources
node_enrichment -->|"persists results"| node_enrich_store
node_profile -.->|"shows score"| node_risk

click node_frontend "https://github.com/djsebby/coporatemapper/blob/main/frontend/src/App.tsx"
click node_graph "https://github.com/djsebby/coporatemapper/blob/main/frontend/src/Graph.tsx"
click node_profile "https://github.com/djsebby/coporatemapper/blob/main/frontend/src/PersonPanel.tsx"
click node_discovery_ui "https://github.com/djsebby/coporatemapper/blob/main/frontend/src/Discovery.tsx"
click node_enrichment_ui "https://github.com/djsebby/coporatemapper/blob/main/frontend/src/Enrichment.tsx"
click node_activity "https://github.com/djsebby/coporatemapper/blob/main/frontend/src/RecentActivity.tsx"
click node_api "https://github.com/djsebby/coporatemapper/blob/main/app/api.py"
click node_jobs "https://github.com/djsebby/coporatemapper/blob/main/app/pipeline_jobs.py"
click node_pipeline "https://github.com/djsebby/coporatemapper/blob/main/app/pipeline.py"
click node_discover "https://github.com/djsebby/coporatemapper/blob/main/app/crawler/discover.py"
click node_robots "https://github.com/djsebby/coporatemapper/blob/main/app/crawler/robots.py"
click node_sitemap "https://github.com/djsebby/coporatemapper/blob/main/app/crawler/sitemap.py"
click node_crawler "https://github.com/djsebby/coporatemapper/blob/main/app/crawler/crawler.py"
click node_prioritiser "https://github.com/djsebby/coporatemapper/blob/main/app/crawler/prioritiser.py"
click node_extractor "https://github.com/djsebby/coporatemapper/blob/main/app/extractor.py"
click node_risk "https://github.com/djsebby/coporatemapper/blob/main/app/riskscore/riskscore.py"
click node_enrichment "https://github.com/djsebby/coporatemapper/blob/main/app/enrichment.py"
click node_policy "https://github.com/djsebby/coporatemapper/blob/main/app/enrichment_policy.py"
click node_sources "https://github.com/djsebby/coporatemapper/blob/main/app/enrichment_sources.py"
click node_enrich_store "https://github.com/djsebby/coporatemapper/blob/main/app/enrichment_store.py"
click node_database "https://github.com/djsebby/coporatemapper/blob/main/app/database.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_frontend,node_graph,node_profile,node_discovery_ui,node_enrichment_ui,node_activity toneBlue
class node_pipeline,node_discover,node_robots,node_sitemap,node_crawler,node_prioritiser toneAmber
class node_extractor,node_risk,node_api toneMint
class node_enrichment,node_policy,node_sources,node_enrich_store toneRose
class node_jobs,node_database,node_user toneIndigo
```

## Components

### Web application

- [Directory UI](https://github.com/djsebby/coporatemapper/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [People graph](https://github.com/djsebby/coporatemapper/blob/main/frontend/src/Graph.tsx): `frontend/src/Graph.tsx`
- [Person profile](https://github.com/djsebby/coporatemapper/blob/main/frontend/src/PersonPanel.tsx): `frontend/src/PersonPanel.tsx`
- [Discovery controls](https://github.com/djsebby/coporatemapper/blob/main/frontend/src/Discovery.tsx): `frontend/src/Discovery.tsx`
- [Enrichment controls](https://github.com/djsebby/coporatemapper/blob/main/frontend/src/Enrichment.tsx): `frontend/src/Enrichment.tsx`
- [Recent activity](https://github.com/djsebby/coporatemapper/blob/main/frontend/src/RecentActivity.tsx): `frontend/src/RecentActivity.tsx`

### Website discovery

- [Discovery pipeline](https://github.com/djsebby/coporatemapper/blob/main/app/pipeline.py): `app/pipeline.py`
- [Site discovery](https://github.com/djsebby/coporatemapper/blob/main/app/crawler/discover.py): `app/crawler/discover.py`
- [Robots policies](https://github.com/djsebby/coporatemapper/blob/main/app/crawler/robots.py): `app/crawler/robots.py`
- [Sitemap parsing](https://github.com/djsebby/coporatemapper/blob/main/app/crawler/sitemap.py): `app/crawler/sitemap.py`
- [Page crawling](https://github.com/djsebby/coporatemapper/blob/main/app/crawler/crawler.py): `app/crawler/crawler.py`
- [URL prioritiser](https://github.com/djsebby/coporatemapper/blob/main/app/crawler/prioritiser.py): `app/crawler/prioritiser.py`

### People and risk

- [Person extraction](https://github.com/djsebby/coporatemapper/blob/main/app/extractor.py): `app/extractor.py`
- [Phishing risk score](https://github.com/djsebby/coporatemapper/blob/main/app/riskscore/riskscore.py): `app/riskscore/riskscore.py`

### Profile enrichment

- [Enrichment engine](https://github.com/djsebby/coporatemapper/blob/main/app/enrichment.py): `app/enrichment.py`
- [Finding policy](https://github.com/djsebby/coporatemapper/blob/main/app/enrichment_policy.py): `app/enrichment_policy.py`
- [Public sources](https://github.com/djsebby/coporatemapper/blob/main/app/enrichment_sources.py): `app/enrichment_sources.py`
- [Enrichment store](https://github.com/djsebby/coporatemapper/blob/main/app/enrichment_store.py): `app/enrichment_store.py`

### Jobs and storage

- [Pipeline jobs](https://github.com/djsebby/coporatemapper/blob/main/app/pipeline_jobs.py): `app/pipeline_jobs.py`
- [Neo4j connection](https://github.com/djsebby/coporatemapper/blob/main/app/database.py): `app/database.py`

### Other components

- **Operator**
- [HTTP API](https://github.com/djsebby/coporatemapper/blob/main/app/api.py): `app/api.py`

## Connections

- Operator → Directory UI: uses (evidence: `README.md`)
- Directory UI → People graph: renders (evidence: `frontend/src/App.tsx`)
- Directory UI → Person profile: opens (evidence: `frontend/src/App.tsx`)
- Directory UI → Discovery controls: renders (evidence: `frontend/src/App.tsx`)
- Directory UI → Enrichment controls: renders (evidence: `frontend/src/App.tsx`)
- Directory UI → Recent activity: renders (evidence: `frontend/src/App.tsx`)
- Directory UI → HTTP API: requests
- HTTP API → Pipeline jobs: dispatches
- Pipeline jobs → Discovery pipeline: runs (evidence: `app/pipeline_jobs.py`)
- Discovery pipeline → Site discovery: discovers URLs (evidence: `app/pipeline.py`)
- Discovery pipeline → URL prioritiser: ranks URLs (evidence: `app/pipeline.py`)
- Discovery pipeline → Page crawling: fetches pages (evidence: `app/pipeline.py`)
- Discovery pipeline → Person extraction: processes pages (evidence: `app/pipeline.py`)
- Site discovery → Robots policies: checks policies (evidence: `app/crawler/discover.py`)
- Site discovery → Sitemap parsing: reads sitemaps (evidence: `app/crawler/discover.py`)
- Page crawling → URL prioritiser: uses ranking (evidence: `app/crawler/crawler.py`)
- Neo4j connection → Person extraction: constructs (evidence: `app/database.py`)
- HTTP API → Enrichment engine: exposes operations
- Enrichment engine → Finding policy: applies rules (evidence: `app/enrichment.py`)
- Enrichment engine → Public sources: queries sources (evidence: `app/enrichment.py`)
- Enrichment engine → Enrichment store: persists results (evidence: `app/enrichment.py`)
- Person profile → Phishing risk score: shows score
