# openbmp/obmp-docker architecture

> Architecture diagram of the GitHub repository openbmp/obmp-docker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openbmp/obmp-docker
- Repository: https://github.com/openbmp/obmp-docker

## Overview

##### Project Type and Purpose
- This is a Docker-based deployment repo for the OpenBMP system: a BGP Monitoring Protocol (BMP) collector + pipeline.
- It provides Dockerfiles and orchestration (via docker-compose) to stand up collector(s), message broker (Kafka + ZooKeeper), a PostgreSQL database, a consumer/ingestor (psql-app), optional WhoIs enrichment, plus development and visualization services.

##### File-Structure Analysis
- Top-level:
- docker-compose.yml – defines all services and how they interconnect
- collector/ – BMP collector container
- postgres/ – PostgreSQL DB container + init scripts
- psql-app/ – Kafka→Postgres consumer container + schema-upgrade scripts
- whois/ – optional WhoIs lookup container
- dev-image/ – development/build environment container
- Patterns: each component is its own microservice container; persistent data is mounted via host volumes; schema upgrades are versioned in psql-app/upgrade.

##### README Insights
- Three primary “product” containers with their own README: collector, PostgreSQL, psql-app.
- Persistent volumes under OBMP_DATA_ROOT for config, Kafka data, zookeeper data/logs, Postgres data, Grafana dashboards.

- BMP Collector
- ZooKeeper
- Kafka Broker
- PSQL Consumer (psql-app)
- PostgreSQL Database
- Grafana UI
- WhoIs Lookup Service (optional)
- Dev-image build environment (optional)
- Collector → publishes BMP messages → Kafka
- PSQL Consumer → subscribes to Kafka → transforms & writes → PostgreSQL
- Grafana → queries → PostgreSQL
- WhoIs Service → REST/API calls → optional enrichment by Collector or PSQL Consumer
- All services communicate over the Docker-compose network
c. Architectural Patterns & Principles:
- Microservices / containerized components
- Pub/Sub messaging via Kafka
- Persistent state via host-mounted volumes
- Versioned schema migrations in psql-app
- Separation of concerns: data ingestion, storage, visualization, enrichment
d. Key Technologies & Frameworks:
- Docker & Docker Compose
- Apache Kafka & ZooKeeper
- PostgreSQL
- Go/Python/C (collector code) as per collector/README
- Grafana for dashboards
- Optional WhoIs lookup daemon

## Diagram (Mermaid)

```mermaid
flowchart TD
    Orch["Orchestration\n(docker-compose)"]:::tooling

    subgraph "docker-compose network: obmp"
        subgraph "Messaging Subsystem"
            ZK["ZooKeeper"]:::messaging
            Kafka["Kafka Broker"]:::messaging
            ZK --> Kafka
        end

        Collector["BMP Collector"]:::ingest
        PSQL["PSQL Consumer"]:::ingest
        DB["PostgreSQL Database"]:::storage
        Grafana["Grafana UI"]:::viz
        WhoIs["WhoIs Lookup"]:::tooling
        Dev["Dev-image"]:::tooling

        Vol_ZK["ZK Data/Logs"]:::volume
        Vol_Kafka["Kafka Data"]:::volume
        Vol_Postgres["Postgres Data"]:::volume
        Vol_Grafana["Grafana Dashboards"]:::volume

        Collector -->|"publishes BMP messages"| Kafka
        Kafka -->|"subscribed messages"| PSQL
        PSQL -->|"writes data"| DB
        Grafana -->|"queries"| DB
        WhoIs -->|"optional enrichment API"| Collector
        WhoIs -->|"optional enrichment API"| PSQL

        Kafka --- Vol_Kafka
        ZK --- Vol_ZK
        DB --- Vol_Postgres
        Grafana --- Vol_Grafana
    end

    classDef ingest fill:#D0E6FF,stroke:#3B70A7
    classDef messaging fill:#FFE5B4,stroke:#C77C02
    classDef storage fill:#D5E8D4,stroke:#82B366
    classDef viz fill:#E1D5E7,stroke:#8663A5
    classDef tooling fill:#E0E0E0,stroke:#757575
    classDef volume fill:#FFFFFF,stroke:#000000,stroke-dasharray:5 5

    click Collector "https://github.com/openbmp/obmp-docker/tree/main/collector/Dockerfile"
    click DB "https://github.com/openbmp/obmp-docker/tree/main/postgres/Dockerfile"
    click PSQL "https://github.com/openbmp/obmp-docker/tree/main/psql-app/Dockerfile"
    click WhoIs "https://github.com/openbmp/obmp-docker/tree/main/whois/Dockerfile"
    click Dev "https://github.com/openbmp/obmp-docker/tree/main/dev-image/Dockerfile"
    click Orch "https://github.com/openbmp/obmp-docker/blob/main/docker-compose.yml"
```
