# sipcapture/homer architecture

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

- Interactive diagram: https://gitdiagram.com/sipcapture/homer
- Repository: https://github.com/sipcapture/homer

## Overview

##### Project Type & Purpose
- HOMER 10 is a full-stack, headless observability platform for VoIP/RTC packet and event capture, built around the HEP/EEP protocol.
- It comprises capture agents (heplify), ingestion servers (heplify-server), API services (homer-app), a UI layer (homer-ui), and ancillary pieces (docker manifests, installer script).

##### File-Structure Analysis
- Top-level modules:
- heplify   – CLI-based packet-capture agent
- heplify-server – ingestion microservice(s)
- homer-app  – API/backend application
- homer-ui   – front-end/dashboard (Grafana-based)
- homer-docker – Docker Compose / container orchestration definitions
- homer-installer – setup automation script
- CI/CD: several GitHub Actions workflows for building each component.
- Submodules: shared libraries or protocol definitions.

##### README Insights
- Data types: SIP, RTP/RTCP, logs, metrics, traces, CDRs, syslog.
- Storage: “NoSQL” Observability APIs (qryn), Prometheus/InfluxDB (timeseries), Loki (logs).
- UI: Grafana dashboards, headless architecture, backwards-compatible HEP encapsulation.

1. Agents (“heplify” binaries)
2. Ingestion Cluster (“heplify-server” microservices)
3. Message/Events Bus (internal queue or direct write to qryn API)
4. Storage Backends
– Event store (qryn)
– Metrics store (Prometheus/InfluxDB)
– Logs store (Loki or syslog receivers)
5. API Layer (“homer-app”)
6. Visualization/UI (“homer-ui” via Grafana)
7. Orchestration / Deployment (Docker Compose / Kubernetes manifests from homer-docker, installer scripts)
8. External Integrations: SIP platforms, Kamailio/OpenSIPS/Asterisk clients, CDR producers

B. Relationships & Data Flows
– Agents capture traffic → encapsulate in HEP → send via UDP/TCP → heplify-server ingestion endpoint
– heplify-server parses HEP packets → publishes events/metrics/logs → writes to qryn, Prometheus, Loki
– homer-app queries storage backends (qryn for events, Prom/Influx for metrics, Loki for logs) → exposes REST/gRPC APIs
– homer-ui (Grafana) fetches via API → renders dashboards
– Docker/installer module deploys all services, wires internal networking

C. Architectural Patterns & Principles
– Microservices: separate capture, ingestion, API, and UI
– Event-driven pipeline: HEP ingestion → fan-out to multiple stores
– Headless observability: standardized API layer decoupled from UI
– Backwards compatibility: HEPv3 encapsulation preserved end-to-end

D. Key Technologies
– Protocol: HEP/EEP over UDP/TCP
– Ingestion: Go-based heplify-server
– Storage: qryn API (NoSQL for events), Prometheus/InfluxDB, Loki
– API: Node/Go (homer-app)
– UI: Grafana dashboards configured by homer-ui module
– Deployment: Docker Compose, bash installer

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Integrations
    SIPClients["SIP Platforms<br/>(Kamailio/OpenSIPS/Asterisk)"]:::external

    %% Capture & Ingestion Layer
    subgraph "Capture & Ingestion" 
        direction TB
        HEPAgents["HEP Capture Agents<br/>(heplify)"]:::capture
        IngService["Ingestion Service<br/>(heplify-server)"]:::capture
    end

    %% Storage Layer
    subgraph "Storage Backends" 
        direction TB
        Qryn["Event Store<br/>(qryn)"]:::store
        Prometheus["Metrics Store<br/>(Prometheus/InfluxDB)"]:::store
        Loki["Logs Store<br/>(Loki)"]:::store
    end

    %% API & UI Layer
    subgraph "API & UI" 
        direction TB
        API["API Layer<br/>(homer-app)"]:::api
        UI["UI Dashboard<br/>(homer-ui)"]:::api
    end

    %% Deployment & Orchestration
    subgraph "Deployment / Orchestration" 
        direction TB
        Docker["Orchestration<br/>(homer-docker)"]:::deploy
        Installer["Installer Script<br/>(homer-installer)"]:::deploy
    end

    %% CI/CD Pipeline
    subgraph "CI/CD (GitHub Actions)" 
        direction TB
        HFBuilder["heplify-server-builder.yml"]:::deploy
        AppBuilder["homer-app-builder.yml"]:::deploy
        SubmodCI["submodules.yml"]:::deploy
        GenericCI["star.yml"]:::deploy
        GitModules[".gitmodules"]:::deploy
    end

    %% Data Flows
    SIPClients -->|UDP/TCP HEP| HEPAgents
    HEPAgents -->|UDP:9060| IngService
    IngService -->|"qryn API"| Qryn
    IngService -->|"Prometheus Push"| Prometheus
    IngService -->|"Loki Push"| Loki
    Qryn -->|"Query"| API
    Prometheus -->|"Query"| API
    Loki -->|"Query"| API
    UI -->|"REST/gRPC"| API

    %% Deployment Flows
    Installer --> Docker
    Docker --> HEPAgents
    Docker --> IngService
    Docker --> API
    Docker --> UI

    %% CI/CD Flows
    HFBuilder --> Docker
    AppBuilder --> Docker
    SubmodCI --> Docker
    GenericCI --> Docker
    GitModules --> Docker

    %% Click Events
    click HEPAgents "https://github.com/sipcapture/homer/tree/homer10/heplify/"
    click IngService "https://github.com/sipcapture/homer/tree/homer10/heplify-server/"
    click API "https://github.com/sipcapture/homer/tree/homer10/homer-app/"
    click UI "https://github.com/sipcapture/homer/tree/homer10/homer-ui/"
    click Docker "https://github.com/sipcapture/homer/tree/homer10/homer-docker/"
    click Installer "https://github.com/sipcapture/homer/tree/homer10/homer-installer/"
    click HFBuilder "https://github.com/sipcapture/homer/blob/homer10/.github/workflows/heplify-server-builder.yml"
    click AppBuilder "https://github.com/sipcapture/homer/blob/homer10/.github/workflows/homer-app-builder.yml"
    click SubmodCI "https://github.com/sipcapture/homer/blob/homer10/.github/workflows/submodules.yml"
    click GenericCI "https://github.com/sipcapture/homer/blob/homer10/.github/workflows/star.yml"
    click GitModules "https://github.com/sipcapture/homer/blob/homer10/.gitmodules"

    %% Styles
    classDef capture fill:#FFA500,stroke:#333,stroke-width:1px
    classDef store fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef api fill:#008080,stroke:#333,stroke-width:1px
    classDef deploy fill:#800080,stroke:#FFF,stroke-width:1px
    classDef external fill:#F0E68C,stroke:#333,stroke-width:1px
```
