# dynasmon/seagull architecture

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

- Interactive diagram: https://gitdiagram.com/dynasmon/seagull
- Repository: https://github.com/dynasmon/seagull

## Overview

Seagull is a security operations platform: endpoint and network telemetry enters through agent-facing APIs and ingestion workers, is analyzed by detection and intelligence workers, and becomes alerts, incidents, and investigation data for the analyst portal. Separate product branches cover fleet management, topology and exposure, vulnerability correlation, and behavioral analytics. The README documents the broad service and storage relationships; sampled source additionally confirms rule execution and alert-pipeline stages. Several feature internals were not sampled, so their links are limited to documented relationships.

Main entry points: [`backend/app/main.py`](https://github.com/dynasmon/seagull/blob/main/backend/app/main.py) (FastAPI control plane), [`backend/app/features/alerts/models.py`](https://github.com/dynasmon/seagull/blob/main/backend/app/features/alerts/models.py) (Alert triage), [`frontend/src/app/routes.tsx`](https://github.com/dynasmon/seagull/blob/main/frontend/src/app/routes.tsx) (Analyst portal), [`backend/app/workers/ingest/main.py`](https://github.com/dynasmon/seagull/blob/main/backend/app/workers/ingest/main.py) (Ingest workers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Collection and fleet"]
  node_agent_api["Agent API<br/>[api.py]"]
  node_ingest_api["Ingest API<br/>[api.py]"]
  node_ingest_worker["Ingest workers<br/>[main.py]"]
  node_agent_fleet["Fleet management"]
end

subgraph group_intelligence["Detection and intelligence"]
  node_detection_rules["Detection rules"]
  node_rule_worker["Rule evaluation<br/>[engine.py]"]
  node_rule_conditions["Rule conditions<br/>[conditions.py]"]
  node_rule_dedup["Alert deduplication<br/>[dedup.py]"]
  node_alert_pipeline["Alert pipeline<br/>[pipeline.py]"]
  node_correlations["Correlations<br/>[bootstrap.py]"]
  node_attack_chains["Attack chains<br/>[story_engine.py]"]
  node_ueba["Behavioral analytics"]
  node_topology_exposure["Topology and exposure"]
  node_vulnerability["Vulnerability detection"]
end

subgraph group_operations["Analyst operations"]
  node_portal["Analyst portal<br/>[routes.tsx]"]
  node_event_hunting["Event hunting<br/>[api.py]"]
  node_alert_triage["Alert triage<br/>[models.py]"]
  node_investigations["Investigations"]
  node_realtime["Realtime updates<br/>[api.py]"]
end

subgraph group_platform["Platform services"]
  node_backend["FastAPI control plane<br/>[main.py]"]
  node_db_lifecycle["Database lifecycle<br/>[lifecycle.py]"]
  node_db_engine["Database engine<br/>[engine.py]"]
  node_settings["Configuration<br/>[settings.py]"]
  node_observability["Observability"]
  node_postgres[("PostgreSQL")]
  node_clickhouse[("ClickHouse")]
  node_elasticsearch[("Elasticsearch")]
  node_redis[("Redis")]
end

node_agent(("Seagull Agent"))
node_analyst(("Security analyst"))

node_agent -->|"enrolls with"| node_agent_api
node_agent -->|"sends telemetry"| node_ingest_api
node_ingest_api -->|"buffers batches"| node_ingest_worker
node_ingest_worker -->|"queues through"| node_redis
node_ingest_worker -->|"writes analytics"| node_clickhouse
node_ingest_worker -->|"indexes events"| node_elasticsearch
node_agent_api -->|"supports enrollment"| node_agent_fleet
node_detection_rules -->|"evaluated by"| node_rule_worker
node_rule_worker -->|"evaluates with"| node_rule_conditions
node_rule_worker -->|"runs pipeline"| node_alert_pipeline
node_alert_pipeline -->|"uses deduplication"| node_rule_dedup
node_rule_worker -->|"creates alerts"| node_alert_triage
node_correlations -->|"groups detections"| node_alert_triage
node_attack_chains -->|"assembles activity"| node_alert_triage
node_ueba -->|"reports anomalies"| node_alert_triage
node_topology_exposure -->|"informs exposure"| node_alert_triage
node_vulnerability -->|"correlates host exposure"| node_topology_exposure
node_analyst -->|"uses"| node_portal
node_portal -->|"hunts events"| node_event_hunting
node_portal -->|"triages alerts"| node_alert_triage
node_portal -->|"tracks evidence"| node_investigations
node_portal -->|"explores topology"| node_topology_exposure
node_backend -->|"serves API"| node_agent_api
node_backend -->|"serves API"| node_ingest_api
node_backend -->|"uses operational state"| node_postgres
node_backend -->|"serves realtime API"| node_realtime
node_backend -->|"records telemetry"| node_observability
node_db_lifecycle -->|"uses engine"| node_db_engine
node_db_engine -->|"reads configuration"| node_settings
node_backend -->|"loads configuration"| node_settings

click node_agent_api "https://github.com/dynasmon/seagull/blob/main/backend/app/features/agents/api.py"
click node_ingest_api "https://github.com/dynasmon/seagull/blob/main/backend/app/features/ingest/api.py"
click node_ingest_worker "https://github.com/dynasmon/seagull/blob/main/backend/app/workers/ingest/main.py"
click node_agent_fleet "https://github.com/dynasmon/seagull/tree/main/backend/app/features/agents"
click node_detection_rules "https://github.com/dynasmon/seagull/tree/main/backend/app/features/detections/rules"
click node_rule_worker "https://github.com/dynasmon/seagull/blob/main/backend/app/workers/intelligence/rules/engine.py"
click node_rule_conditions "https://github.com/dynasmon/seagull/blob/main/backend/app/workers/intelligence/rules/conditions.py"
click node_rule_dedup "https://github.com/dynasmon/seagull/blob/main/backend/app/workers/intelligence/rules/dedup.py"
click node_alert_pipeline "https://github.com/dynasmon/seagull/blob/main/backend/app/features/detections/pipeline/pipeline.py"
click node_correlations "https://github.com/dynasmon/seagull/blob/main/backend/app/features/correlations/bootstrap.py"
click node_attack_chains "https://github.com/dynasmon/seagull/blob/main/backend/app/features/attack_chain/domain/story_engine.py"
click node_ueba "https://github.com/dynasmon/seagull/tree/main/backend/app/features/ueba"
click node_topology_exposure "https://github.com/dynasmon/seagull/tree/main/backend/app/features/network_topology"
click node_vulnerability "https://github.com/dynasmon/seagull/tree/main/backend/app/features/vuln"
click node_portal "https://github.com/dynasmon/seagull/blob/main/frontend/src/app/routes.tsx"
click node_event_hunting "https://github.com/dynasmon/seagull/blob/main/backend/app/features/events/api.py"
click node_alert_triage "https://github.com/dynasmon/seagull/blob/main/backend/app/features/alerts/models.py"
click node_investigations "https://github.com/dynasmon/seagull/tree/main/backend/app/features/investigations"
click node_realtime "https://github.com/dynasmon/seagull/blob/main/backend/app/features/realtime/api.py"
click node_backend "https://github.com/dynasmon/seagull/blob/main/backend/app/main.py"
click node_db_lifecycle "https://github.com/dynasmon/seagull/blob/main/backend/app/core/db/lifecycle.py"
click node_db_engine "https://github.com/dynasmon/seagull/blob/main/backend/app/core/db/engine.py"
click node_settings "https://github.com/dynasmon/seagull/blob/main/backend/app/core/config/settings.py"
click node_observability "https://github.com/dynasmon/seagull/tree/main/backend/app/core/observability"

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_agent_api,node_ingest_api,node_ingest_worker,node_agent_fleet toneBlue
class node_detection_rules,node_rule_worker,node_rule_conditions,node_rule_dedup,node_alert_pipeline,node_correlations,node_attack_chains,node_ueba,node_topology_exposure,node_vulnerability toneAmber
class node_portal,node_event_hunting,node_alert_triage,node_investigations,node_realtime toneMint
class node_backend,node_db_lifecycle,node_db_engine,node_settings,node_observability,node_postgres,node_clickhouse,node_elasticsearch,node_redis toneRose
class node_agent,node_analyst toneIndigo
```

## Components

### Collection and fleet

- [Agent API](https://github.com/dynasmon/seagull/blob/main/backend/app/features/agents/api.py): `backend/app/features/agents/api.py`
- [Ingest API](https://github.com/dynasmon/seagull/blob/main/backend/app/features/ingest/api.py): `backend/app/features/ingest/api.py`
- [Ingest workers](https://github.com/dynasmon/seagull/blob/main/backend/app/workers/ingest/main.py): `backend/app/workers/ingest/main.py`
- [Fleet management](https://github.com/dynasmon/seagull/tree/main/backend/app/features/agents): `backend/app/features/agents`

### Detection and intelligence

- [Detection rules](https://github.com/dynasmon/seagull/tree/main/backend/app/features/detections/rules): `backend/app/features/detections/rules`
- [Rule evaluation](https://github.com/dynasmon/seagull/blob/main/backend/app/workers/intelligence/rules/engine.py): `backend/app/workers/intelligence/rules/engine.py`
- [Rule conditions](https://github.com/dynasmon/seagull/blob/main/backend/app/workers/intelligence/rules/conditions.py): `backend/app/workers/intelligence/rules/conditions.py`
- [Alert deduplication](https://github.com/dynasmon/seagull/blob/main/backend/app/workers/intelligence/rules/dedup.py): `backend/app/workers/intelligence/rules/dedup.py`
- [Alert pipeline](https://github.com/dynasmon/seagull/blob/main/backend/app/features/detections/pipeline/pipeline.py): `backend/app/features/detections/pipeline/pipeline.py`
- [Correlations](https://github.com/dynasmon/seagull/blob/main/backend/app/features/correlations/bootstrap.py): `backend/app/features/correlations/bootstrap.py`
- [Attack chains](https://github.com/dynasmon/seagull/blob/main/backend/app/features/attack_chain/domain/story_engine.py): `backend/app/features/attack_chain/domain/story_engine.py`
- [Behavioral analytics](https://github.com/dynasmon/seagull/tree/main/backend/app/features/ueba): `backend/app/features/ueba`
- [Topology and exposure](https://github.com/dynasmon/seagull/tree/main/backend/app/features/network_topology): `backend/app/features/network_topology`
- [Vulnerability detection](https://github.com/dynasmon/seagull/tree/main/backend/app/features/vuln): `backend/app/features/vuln`

### Analyst operations

- [Analyst portal](https://github.com/dynasmon/seagull/blob/main/frontend/src/app/routes.tsx): `frontend/src/app/routes.tsx`
- [Event hunting](https://github.com/dynasmon/seagull/blob/main/backend/app/features/events/api.py): `backend/app/features/events/api.py`
- [Alert triage](https://github.com/dynasmon/seagull/blob/main/backend/app/features/alerts/models.py): `backend/app/features/alerts/models.py`
- [Investigations](https://github.com/dynasmon/seagull/tree/main/backend/app/features/investigations): `backend/app/features/investigations`
- [Realtime updates](https://github.com/dynasmon/seagull/blob/main/backend/app/features/realtime/api.py): `backend/app/features/realtime/api.py`

### Platform services

- [FastAPI control plane](https://github.com/dynasmon/seagull/blob/main/backend/app/main.py): `backend/app/main.py`
- [Database lifecycle](https://github.com/dynasmon/seagull/blob/main/backend/app/core/db/lifecycle.py): `backend/app/core/db/lifecycle.py`
- [Database engine](https://github.com/dynasmon/seagull/blob/main/backend/app/core/db/engine.py): `backend/app/core/db/engine.py`
- [Configuration](https://github.com/dynasmon/seagull/blob/main/backend/app/core/config/settings.py): `backend/app/core/config/settings.py`
- [Observability](https://github.com/dynasmon/seagull/tree/main/backend/app/core/observability): `backend/app/core/observability`
- **PostgreSQL**
- **ClickHouse**
- **Elasticsearch**
- **Redis**

### Other components

- **Seagull Agent**
- **Security analyst**

## Connections

- Seagull Agent → Agent API: enrolls with
- Seagull Agent → Ingest API: sends telemetry
- Ingest API → Ingest workers: buffers batches
- Ingest workers → Redis: queues through
- Ingest workers → ClickHouse: writes analytics
- Ingest workers → Elasticsearch: indexes events
- Agent API → Fleet management: supports enrollment
- Detection rules → Rule evaluation: evaluated by (evidence: `backend/app/workers/intelligence/rules/engine.py`)
- Rule evaluation → Rule conditions: evaluates with (evidence: `backend/app/workers/intelligence/rules/engine.py`)
- Rule evaluation → Alert pipeline: runs pipeline (evidence: `backend/app/workers/intelligence/rules/engine.py`)
- Alert pipeline → Alert deduplication: uses deduplication (evidence: `backend/app/features/detections/pipeline/pipeline.py`)
- Rule evaluation → Alert triage: creates alerts (evidence: `backend/app/workers/intelligence/rules/engine.py`)
- Correlations → Alert triage: groups detections
- Attack chains → Alert triage: assembles activity
- Behavioral analytics → Alert triage: reports anomalies
- Topology and exposure → Alert triage: informs exposure
- Vulnerability detection → Topology and exposure: correlates host exposure
- Security analyst → Analyst portal: uses
- Analyst portal → Event hunting: hunts events
- Analyst portal → Alert triage: triages alerts
- Analyst portal → Investigations: tracks evidence
- Analyst portal → Topology and exposure: explores topology
- FastAPI control plane → Agent API: serves API (evidence: `backend/app/main.py`)
- FastAPI control plane → Ingest API: serves API (evidence: `backend/app/main.py`)
- FastAPI control plane → PostgreSQL: uses operational state
- FastAPI control plane → Realtime updates: serves realtime API (evidence: `backend/app/main.py`)
- FastAPI control plane → Observability: records telemetry (evidence: `backend/app/main.py`)
- Database lifecycle → Database engine: uses engine (evidence: `backend/app/core/db/lifecycle.py`)
- Database engine → Configuration: reads configuration (evidence: `backend/app/core/db/engine.py`)
- FastAPI control plane → Configuration: loads configuration (evidence: `backend/app/main.py`)