# jangidc/watchdesk architecture

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

- Interactive diagram: https://gitdiagram.com/jangidc/watchdesk
- Repository: https://github.com/jangidc/watchdesk

## Overview

Watchdesk is a self-hosted threat-intelligence platform for collecting, normalizing, correlating, and triaging indicators of compromise. Feed connectors fetch from ThreatFox, URLhaus, and optional AbuseIPDB; ingestion merges sightings and records feed-run health in SQLite. A scheduled job and the dashboard’s manual refresh both trigger ingestion. Analysts use the dashboard to search and filter indicators and inspect severity, corroboration, and feed health. The README documents the overall pipeline; some template and URLhaus implementation details were not excerpted.

Main entry points: [`app/ingest.py`](https://github.com/jangidc/watchdesk/blob/main/app/ingest.py) (Normalize and correlate), [`app/routes.py`](https://github.com/jangidc/watchdesk/blob/main/app/routes.py) (Dashboard and JSON API), [`app/static/app.js`](https://github.com/jangidc/watchdesk/blob/main/app/static/app.js) (Dashboard interactions), [`app/__init__.py`](https://github.com/jangidc/watchdesk/blob/main/app/__init__.py) (Refresh scheduler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Feed collection"]
  node_threatfox["ThreatFox connector<br/>[threatfox.py]"]
  node_urlhaus["URLhaus connector<br/>[urlhaus.py]"]
  node_abuseipdb["AbuseIPDB connector<br/>[abuseipdb.py]"]
end

subgraph group_pipeline["Ingestion and storage"]
  node_ingestion["Normalize and correlate<br/>[ingest.py]"]
  node_models["IOC and feed-run records<br/>[models.py]"]
  node_sqlite[("SQLite database<br/>[__init__.py]")]
end

subgraph group_service["Application service"]
  node_scheduler["Refresh scheduler<br/>[__init__.py]"]
  node_routes["Dashboard and JSON API<br/>[routes.py]"]
end

subgraph group_dashboard["Analyst dashboard"]
  node_dashboard_page["Dashboard page<br/>[dashboard.html]"]
  node_dashboard_ui["Dashboard interactions<br/>[app.js]"]
end

node_analyst(("SOC analyst"))
node_threatfox_service{{"ThreatFox API"}}
node_urlhaus_service{{"URLhaus API"}}
node_abuseipdb_service{{"AbuseIPDB API"}}

node_threatfox -->|"fetches from"| node_threatfox_service
node_urlhaus -.->|"fetches from"| node_urlhaus_service
node_abuseipdb -->|"fetches from"| node_abuseipdb_service
node_ingestion -->|"calls fetch"| node_threatfox
node_ingestion -->|"calls fetch"| node_urlhaus
node_ingestion -->|"calls fetch"| node_abuseipdb
node_ingestion -->|"upserts and audits"| node_models
node_scheduler -->|"schedules runs"| node_ingestion
node_scheduler -->|"configures storage"| node_sqlite
node_routes -->|"queries records"| node_models
node_routes -->|"triggers refresh"| node_ingestion
node_routes -->|"renders page"| node_dashboard_page
node_dashboard_ui -->|"fetches API data"| node_routes
node_dashboard_page -.->|"presents dashboard"| node_dashboard_ui
node_analyst -.->|"uses"| node_dashboard_ui

click node_threatfox "https://github.com/jangidc/watchdesk/blob/main/app/feeds/threatfox.py"
click node_urlhaus "https://github.com/jangidc/watchdesk/blob/main/app/feeds/urlhaus.py"
click node_abuseipdb "https://github.com/jangidc/watchdesk/blob/main/app/feeds/abuseipdb.py"
click node_ingestion "https://github.com/jangidc/watchdesk/blob/main/app/ingest.py"
click node_models "https://github.com/jangidc/watchdesk/blob/main/app/models.py"
click node_sqlite "https://github.com/jangidc/watchdesk/blob/main/app/__init__.py"
click node_scheduler "https://github.com/jangidc/watchdesk/blob/main/app/__init__.py"
click node_routes "https://github.com/jangidc/watchdesk/blob/main/app/routes.py"
click node_dashboard_page "https://github.com/jangidc/watchdesk/blob/main/app/templates/dashboard.html"
click node_dashboard_ui "https://github.com/jangidc/watchdesk/blob/main/app/static/app.js"

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_threatfox,node_urlhaus,node_abuseipdb toneBlue
class node_ingestion,node_models,node_sqlite toneAmber
class node_scheduler,node_routes,node_threatfox_service,node_urlhaus_service,node_abuseipdb_service toneMint
class node_dashboard_page,node_dashboard_ui toneRose
class node_analyst toneIndigo
```

## Components

### Feed collection

- [ThreatFox connector](https://github.com/jangidc/watchdesk/blob/main/app/feeds/threatfox.py): `app/feeds/threatfox.py`
- [URLhaus connector](https://github.com/jangidc/watchdesk/blob/main/app/feeds/urlhaus.py): `app/feeds/urlhaus.py`
- [AbuseIPDB connector](https://github.com/jangidc/watchdesk/blob/main/app/feeds/abuseipdb.py): `app/feeds/abuseipdb.py`

### Ingestion and storage

- [Normalize and correlate](https://github.com/jangidc/watchdesk/blob/main/app/ingest.py): `app/ingest.py`
- [IOC and feed-run records](https://github.com/jangidc/watchdesk/blob/main/app/models.py): `app/models.py`
- [SQLite database](https://github.com/jangidc/watchdesk/blob/main/app/__init__.py): `app/__init__.py`

### Application service

- [Refresh scheduler](https://github.com/jangidc/watchdesk/blob/main/app/__init__.py): `app/__init__.py`
- [Dashboard and JSON API](https://github.com/jangidc/watchdesk/blob/main/app/routes.py): `app/routes.py`

### Analyst dashboard

- [Dashboard page](https://github.com/jangidc/watchdesk/blob/main/app/templates/dashboard.html): `app/templates/dashboard.html`
- [Dashboard interactions](https://github.com/jangidc/watchdesk/blob/main/app/static/app.js): `app/static/app.js`

### Other components

- **SOC analyst**
- **ThreatFox API**
- **URLhaus API**
- **AbuseIPDB API**

## Connections

- ThreatFox connector → ThreatFox API: fetches from (evidence: `app/feeds/threatfox.py`)
- URLhaus connector → URLhaus API: fetches from (evidence: `README.md`)
- AbuseIPDB connector → AbuseIPDB API: fetches from (evidence: `app/feeds/abuseipdb.py`)
- Normalize and correlate → ThreatFox connector: calls fetch (evidence: `app/ingest.py`)
- Normalize and correlate → URLhaus connector: calls fetch (evidence: `app/ingest.py`)
- Normalize and correlate → AbuseIPDB connector: calls fetch (evidence: `app/ingest.py`)
- Normalize and correlate → IOC and feed-run records: upserts and audits (evidence: `app/ingest.py`)
- Refresh scheduler → Normalize and correlate: schedules runs (evidence: `app/__init__.py`)
- Refresh scheduler → SQLite database: configures storage (evidence: `app/__init__.py`)
- Dashboard and JSON API → IOC and feed-run records: queries records (evidence: `app/routes.py`)
- Dashboard and JSON API → Normalize and correlate: triggers refresh (evidence: `app/routes.py`)
- Dashboard and JSON API → Dashboard page: renders page (evidence: `app/routes.py`)
- Dashboard interactions → Dashboard and JSON API: fetches API data (evidence: `app/static/app.js`)
- Dashboard page → Dashboard interactions: presents dashboard (evidence: `README.md`)
- SOC analyst → Dashboard interactions: uses
