# forth-ics-inspire/artemis architecture

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

- Interactive diagram: https://gitdiagram.com/forth-ics-inspire/artemis
- Repository: https://github.com/forth-ics-inspire/artemis

## Overview

1. **What this repo is**
   ARTEMIS is a modular BGP hijack detection and mitigation system built as a multi-container application. The repository is split into service-specific Python components, deployment manifests, and test/demonstration environments.

2. **Top-level architectural shape**
   The system is organized around three planes:
   - **Monitoring/ingestion**: collectors that consume BGP updates from live feeds, historical feeds, or local routers.
   - **Detection/decision**: services that compare updates against configured prefixes, origin ASes, and routing rules.
   - **Control/UI/mitigation**: services that expose configuration, persist state, notify operators, and optionally trigger mitigation actions.

3. **Ingress sources**
   The monitoring layer includes separate tap services for different sources:
   - `bgpstreamlivetap`, `bgpstreamhisttap`, `bgpstreamkafkatap` for CAIDA/BGPStream live, historical, and Kafka-based inputs.
   - `riperistap` for RIPE RIS live data.
   - `exabgptap` for local ExaBGP feeds.
   - `fileobserver` for file-based update observation.
   These are the main external data entry points into the system.

4. **Detection core**
   The main decision logic lives in `backend-services/detection`, backed by a `prefixtree` service for fast prefix/rule matching. Detection consumes incoming BGP events, checks them against the configured “ground truth” and ARTEMIS rules, and classifies hijack-related conditions such as exact-prefix, sub-prefix, squatting, and policy violations.

5. **Configuration and startup control**
   `backend-services/configuration` is the control plane for loading, validating, and serving ARTEMIS configuration. `autostarter` orchestrates service startup, while `autoignore` handles automatic suppression/ignoring of events under certain conditions. These services form the “operational policy” boundary of the system.

6. **Persistence and backend data model**
   The `backend-services/database` component owns the persistent store and schema lifecycle. It includes SQL migrations, initialization metadata, and Hasura metadata files, indicating that the database is a central system-of-record for configuration, alerts, and operational state. The chart also includes `postgres`, `mongodb`, `redis`, `rabbitmq`, `pg-amqp-bridge`, and `postgrest`, showing that persistence is split between relational state, queueing, and auxiliary datastores.

7. **Messaging and async coordination**
   ARTEMIS relies on asynchronous service-to-service communication rather than a single monolith. RabbitMQ is the primary queueing backbone, with Redis used for coordination/cache-like runtime state. The presence of a `pg-amqp-bridge` deployment suggests database events are bridged into the message bus so downstream services can react without tight coupling.

8. **Notifications and mitigation**
   `backend-services/notifier` emits operator-facing alerts, while `backend-services/mitigation` is the action boundary for active response. The README notes mitigation is supported but still limited in scope compared with detection, so this is a distinct subsystem rather than the core path.

9. **Visualization and API layer**
   The repository includes `frontend`, `graphql`, and Hasura-related deployment artifacts, which together form the user-facing and API-access layer. The UI is used to inspect events, edit configuration, and control modules. The API boundary is important: operator actions enter through the UI/API layer and then flow to configuration, database, and control services.

10. **Deployment model**
   The system is designed to run either with `docker-compose` for single-host use or on Kubernetes via `artemis-chart`. The Helm chart packages each microservice as its own deployment, with shared services and config maps for runtime configuration. That makes the deployment topology a key architectural concern: services are independently scaled and can be selectively enabled.

11. **Operational configuration and runtime assets**
   The repo contains shared config templates for logging, Redis, Nginx, ExaBGP, SQL schema/init scripts, and service-specific environment files. This indicates a configuration-heavy architecture where behavior is shaped by mounted files and container startup scripts rather than hardcoded defaults.

12. **Testing and validation boundaries**
   There are dedicated integration-style test harnesses under `testing/` for detection, autoignore, autoconf, and RPKI scenarios, plus entrypoint tests for service startup contracts. These tests mirror the service boundaries, which is useful when drawing the architecture: the repo is structured around independently verifiable microservices.

13. **External dependencies that materially shape the architecture**
   The main external technologies are BGPStream/RIPE RIS/ExaBGP for telemetry, PostgreSQL/Hasura for persistent state and API exposure, RabbitMQ/Redis for runtime coordination, and Kubernetes/Docker for deployment. Grafana dashboards are included for monitoring the system itself and the detected events.

14. **Overall data flow to diagram**
   A practical diagram should show: BGP feeds enter the tap services; those feed detection and prefix-matching logic; detection reads configuration/state from the database-backed control plane; alerts and events are published through the async bus; notifier/UI consume the resulting state; mitigation can send outbound routing actions back through ExaBGP or other configured control paths.

Main entry points: [`backend-services/detection`](https://github.com/forth-ics-inspire/artemis/tree/master/backend-services/detection) (Detection), [`backend-services/database`](https://github.com/forth-ics-inspire/artemis/tree/master/backend-services/database) (Database), [`artemis-chart/templates/rabbitmq-deployment.yaml`](https://github.com/forth-ics-inspire/artemis/blob/master/artemis-chart/templates/rabbitmq-deployment.yaml) (RabbitMQ), [`backend-services/configuration`](https://github.com/forth-ics-inspire/artemis/tree/master/backend-services/configuration) (Configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_monitoring["Monitoring"]
  node_bgpstreamlivetap["BGPStream Live<br/>tap service"]
  node_bgpstreamhisttap["BGPStream Hist<br/>tap service"]
  node_bgpstreamkafkatap["BGPStream Kafka<br/>tap service"]
  node_riperistap["RIPE RIS<br/>tap service"]
  node_exabgptap["ExaBGP Tap<br/>tap service"]
  node_fileobserver["File Observer<br/>file watcher"]
end

subgraph group_decision["Detection"]
  node_detection["Detection<br/>analysis service"]
  node_prefixtree["Prefix Tree<br/>match service"]
end

subgraph group_control["Control Plane"]
  node_configuration["Configuration<br/>control service"]
  node_autostarter["Autostarter<br/>orchestrator"]
  node_autoignore["Autoignore<br/>policy filter"]
  node_notifier["Notifier<br/>alert service"]
  node_mitigation["Mitigation<br/>response service"]
end

subgraph group_platform["Platform"]
  node_database[("Database<br/>state service")]
  node_postgres[("Postgres<br/>relational store")]
  node_mongodb[("MongoDB<br/>aux store")]
  node_redis[("Redis<br/>coordination store")]
  node_rabbitmq["RabbitMQ<br/>message bus"]
  node_pgamqpbridge["PG-AMQP Bridge"]
  node_graphql["GraphQL<br/>api layer"]
  node_frontend["Frontend<br/>ui"]
  node_postgrest["PostgREST<br/>api service"]
  node_helmchart["Helm Chart<br/>deployment package"]
end

node_bgpstreamlivetap -->|"updates"| node_detection
node_bgpstreamhisttap -->|"updates"| node_detection
node_bgpstreamkafkatap -->|"updates"| node_detection
node_riperistap -->|"updates"| node_detection
node_exabgptap -->|"updates"| node_detection
node_fileobserver -->|"events"| node_detection
node_detection -->|"match"| node_prefixtree
node_detection -->|"rules"| node_configuration
node_configuration -->|"persist"| node_database
node_autostarter -->|"boot"| node_configuration
node_autostarter -->|"boot"| node_detection
node_autoignore -->|"suppress"| node_detection
node_detection -->|"publish"| node_rabbitmq
node_database -->|"events"| node_pgamqpbridge
node_pgamqpbridge -->|"bridge"| node_rabbitmq
node_rabbitmq -->|"deliver"| node_notifier
node_rabbitmq -->|"deliver"| node_mitigation
node_database -->|"api data"| node_graphql
node_frontend -->|"queries"| node_graphql
node_frontend -->|"rest"| node_postgrest
node_graphql -->|"read/write"| node_database
node_postgrest -->|"read/write"| node_database
node_mitigation -->|"control"| node_exabgptap

click node_bgpstreamlivetap "https://github.com/forth-ics-inspire/artemis/tree/master/monitor-services/bgpstreamlivetap"
click node_bgpstreamhisttap "https://github.com/forth-ics-inspire/artemis/tree/master/monitor-services/bgpstreamhisttap"
click node_bgpstreamkafkatap "https://github.com/forth-ics-inspire/artemis/tree/master/monitor-services/bgpstreamkafkatap"
click node_riperistap "https://github.com/forth-ics-inspire/artemis/tree/master/monitor-services/riperistap"
click node_exabgptap "https://github.com/forth-ics-inspire/artemis/tree/master/monitor-services/exabgptap"
click node_fileobserver "https://github.com/forth-ics-inspire/artemis/tree/master/backend-services/fileobserver"
click node_detection "https://github.com/forth-ics-inspire/artemis/tree/master/backend-services/detection"
click node_prefixtree "https://github.com/forth-ics-inspire/artemis/tree/master/backend-services/prefixtree"
click node_configuration "https://github.com/forth-ics-inspire/artemis/tree/master/backend-services/configuration"
click node_autostarter "https://github.com/forth-ics-inspire/artemis/tree/master/backend-services/autostarter"
click node_autoignore "https://github.com/forth-ics-inspire/artemis/tree/master/backend-services/autoignore"
click node_notifier "https://github.com/forth-ics-inspire/artemis/tree/master/backend-services/notifier"
click node_mitigation "https://github.com/forth-ics-inspire/artemis/tree/master/backend-services/mitigation"
click node_database "https://github.com/forth-ics-inspire/artemis/tree/master/backend-services/database"
click node_postgres "https://github.com/forth-ics-inspire/artemis/blob/master/artemis-chart/templates/postgres-deployment.yaml"
click node_mongodb "https://github.com/forth-ics-inspire/artemis/blob/master/artemis-chart/templates/mongodb-deployment.yaml"
click node_redis "https://github.com/forth-ics-inspire/artemis/blob/master/artemis-chart/templates/redis-deployment.yaml"
click node_rabbitmq "https://github.com/forth-ics-inspire/artemis/blob/master/artemis-chart/templates/rabbitmq-deployment.yaml"
click node_pgamqpbridge "https://github.com/forth-ics-inspire/artemis/blob/master/artemis-chart/templates/pg-amqp-bridge-deployment.yaml"
click node_graphql "https://github.com/forth-ics-inspire/artemis/blob/master/artemis-chart/templates/graphql-deployment.yaml"
click node_frontend "https://github.com/forth-ics-inspire/artemis/blob/master/artemis-chart/templates/frontend-deployment.yaml"
click node_postgrest "https://github.com/forth-ics-inspire/artemis/blob/master/artemis-chart/templates/postgrest-deployment.yaml"
click node_helmchart "https://github.com/forth-ics-inspire/artemis/tree/master/artemis-chart"

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_bgpstreamlivetap,node_bgpstreamhisttap,node_bgpstreamkafkatap,node_riperistap,node_exabgptap,node_fileobserver toneBlue
class node_detection,node_prefixtree toneAmber
class node_configuration,node_autostarter,node_autoignore,node_notifier,node_mitigation toneMint
class node_database,node_postgres,node_mongodb,node_redis,node_rabbitmq,node_pgamqpbridge,node_graphql,node_frontend,node_postgrest,node_helmchart toneRose
```

## Components

### Monitoring

External BGP feeds and tap services that ingest updates.

- [BGPStream Live](https://github.com/forth-ics-inspire/artemis/tree/master/monitor-services/bgpstreamlivetap): tap service · Consumes live BGPStream updates. · `monitor-services/bgpstreamlivetap`
- [BGPStream Hist](https://github.com/forth-ics-inspire/artemis/tree/master/monitor-services/bgpstreamhisttap): tap service · Consumes historical BGPStream data. · `monitor-services/bgpstreamhisttap`
- [BGPStream Kafka](https://github.com/forth-ics-inspire/artemis/tree/master/monitor-services/bgpstreamkafkatap): tap service · Consumes BGPStream data from Kafka. · `monitor-services/bgpstreamkafkatap`
- [RIPE RIS](https://github.com/forth-ics-inspire/artemis/tree/master/monitor-services/riperistap): tap service · Consumes RIPE RIS updates. · `monitor-services/riperistap`
- [ExaBGP Tap](https://github.com/forth-ics-inspire/artemis/tree/master/monitor-services/exabgptap): tap service · Consumes local ExaBGP feeds. · `monitor-services/exabgptap`
- [File Observer](https://github.com/forth-ics-inspire/artemis/tree/master/backend-services/fileobserver): file watcher · Watches files for update events. · `backend-services/fileobserver`

### Detection

Core analysis and rule-matching services.

- [Detection](https://github.com/forth-ics-inspire/artemis/tree/master/backend-services/detection): analysis service · Classifies hijack-related conditions from incoming BGP events. · `backend-services/detection`
- [Prefix Tree](https://github.com/forth-ics-inspire/artemis/tree/master/backend-services/prefixtree): match service · Provides fast prefix and rule matching. · `backend-services/prefixtree`

### Control Plane

Configuration, orchestration, notification, and mitigation services.

- [Configuration](https://github.com/forth-ics-inspire/artemis/tree/master/backend-services/configuration): control service · Loads, validates, and serves ARTEMIS configuration. · `backend-services/configuration`
- [Autostarter](https://github.com/forth-ics-inspire/artemis/tree/master/backend-services/autostarter): orchestrator · Coordinates service startup sequencing. · `backend-services/autostarter`
- [Autoignore](https://github.com/forth-ics-inspire/artemis/tree/master/backend-services/autoignore): policy filter · Suppresses or ignores events under configured conditions. · `backend-services/autoignore`
- [Notifier](https://github.com/forth-ics-inspire/artemis/tree/master/backend-services/notifier): alert service · Emits operator-facing alerts and notifications. · `backend-services/notifier`
- [Mitigation](https://github.com/forth-ics-inspire/artemis/tree/master/backend-services/mitigation): response service · Executes limited active response actions. · `backend-services/mitigation`

### Platform

Persistence, messaging, API, UI, and deployment packaging.

- [Database](https://github.com/forth-ics-inspire/artemis/tree/master/backend-services/database): state service · Owns persistent schema and operational state. · `backend-services/database`
- [Postgres](https://github.com/forth-ics-inspire/artemis/blob/master/artemis-chart/templates/postgres-deployment.yaml): relational store · Primary relational backing store. · `artemis-chart/templates/postgres-deployment.yaml`
- [MongoDB](https://github.com/forth-ics-inspire/artemis/blob/master/artemis-chart/templates/mongodb-deployment.yaml): aux store · Auxiliary document datastore. · `artemis-chart/templates/mongodb-deployment.yaml`
- [Redis](https://github.com/forth-ics-inspire/artemis/blob/master/artemis-chart/templates/redis-deployment.yaml): coordination store · Runtime cache and coordination state. · `artemis-chart/templates/redis-deployment.yaml`
- [RabbitMQ](https://github.com/forth-ics-inspire/artemis/blob/master/artemis-chart/templates/rabbitmq-deployment.yaml): message bus · Primary asynchronous messaging backbone. · `artemis-chart/templates/rabbitmq-deployment.yaml`
- [PG-AMQP Bridge](https://github.com/forth-ics-inspire/artemis/blob/master/artemis-chart/templates/pg-amqp-bridge-deployment.yaml): bridge · Bridges database events into the message bus. · `artemis-chart/templates/pg-amqp-bridge-deployment.yaml`
- [GraphQL](https://github.com/forth-ics-inspire/artemis/blob/master/artemis-chart/templates/graphql-deployment.yaml): api layer · API boundary for frontend and operator actions. · `artemis-chart/templates/graphql-deployment.yaml`
- [Frontend](https://github.com/forth-ics-inspire/artemis/blob/master/artemis-chart/templates/frontend-deployment.yaml): ui · Operator UI for inspection and control. · `artemis-chart/templates/frontend-deployment.yaml`
- [PostgREST](https://github.com/forth-ics-inspire/artemis/blob/master/artemis-chart/templates/postgrest-deployment.yaml): api service · REST API over the relational backend. · `artemis-chart/templates/postgrest-deployment.yaml`
- [Helm Chart](https://github.com/forth-ics-inspire/artemis/tree/master/artemis-chart): deployment package · Kubernetes packaging for the multi-service system. · `artemis-chart`

## Connections

- BGPStream Live → Detection: updates · Live BGP updates flow into detection.
- BGPStream Hist → Detection: updates · Historical BGP updates feed analysis.
- BGPStream Kafka → Detection: updates · Kafka-sourced BGP updates feed analysis.
- RIPE RIS → Detection: updates · RIPE RIS updates feed analysis.
- ExaBGP Tap → Detection: updates · Local ExaBGP updates feed analysis.
- File Observer → Detection: events · File-based events can enter the detection path.
- Detection → Prefix Tree: match · Detection relies on prefix/rule matching.
- Detection → Configuration: rules · Detection reads current configuration and policy.
- Configuration → Database: persist · Configuration is stored and served from persistent state.
- Autostarter → Configuration: boot · Autostarter brings control-plane services up in order.
- Autostarter → Detection: boot · Autostarter coordinates detection startup.
- Autoignore → Detection: suppress · Autoignore filters events before operator action.
- Detection → RabbitMQ: publish · Detection emits results onto the async bus.
- Database → PG-AMQP Bridge: events · Database changes are bridged to messaging.
- PG-AMQP Bridge → RabbitMQ: bridge · Bridges relational events into RabbitMQ.
- RabbitMQ → Notifier: deliver · Notifications consume async events.
- RabbitMQ → Mitigation: deliver · Mitigation consumes async control events.
- Database → GraphQL: api data · GraphQL exposes persisted state to the UI.
- Frontend → GraphQL: queries · Frontend uses GraphQL as its API boundary.
- Frontend → PostgREST: rest · Frontend can access REST-backed views and actions.
- GraphQL → Database: read/write · Operator actions flow through the API to state.
- PostgREST → Database: read/write · PostgREST exposes relational state through REST.
- Mitigation → ExaBGP Tap: control · Mitigation can send outbound routing actions through ExaBGP paths.