System architecture

Seagull V2 separates the high-volume data plane from the administrative control plane. A durable broker boundary allows writers and security analysis to progress independently. The gateway does not synchronously call detection or write analytical tables.

Current implementation

The diagram shows implemented backend processes. Its producer is an authenticated client, such as the development probe. The agent's collection and delivery components are still planned.

Authenticated telemetry clientsuch as the development probe

OSV distribution exports

control-apicontrol plane

ingest-gatewayverified identity · durable ACK

advisory-importer

security.rulesets

security.agents

security.events.raw

security.inventory.raw

security.advisories

analysis-enginenormalize · detect

event-writer

inventory-projector

advisory-writer

security.detections

alert-writeralerts · incidents

detection-writer

PostgreSQLalerts · registry

ClickHouseevents · detections · inventory · advisories

query-apiread-only, tenant-scoped

mTLS · Protobufscoped reads

Connections: Authenticated telemetry client to ingest-gateway (mTLS · Protobuf); ingest-gateway to security.events.raw; ingest-gateway to security.inventory.raw; OSV distribution exports to advisory-importer; advisory-importer to security.advisories; control-api to security.rulesets; control-api to security.agents; security.agents to ingest-gateway; control-api to PostgreSQL; security.rulesets to analysis-engine; security.events.raw to analysis-engine; security.events.raw to event-writer; security.inventory.raw to inventory-projector; security.advisories to advisory-writer; analysis-engine to security.detections; security.detections to alert-writer; security.detections to detection-writer; alert-writer to PostgreSQL; detection-writer to ClickHouse; event-writer to ClickHouse; inventory-projector to ClickHouse; advisory-writer to ClickHouse; query-api to ClickHouse (scoped reads).

• External
• Seagull process
• Redpanda topic
• Data store
• Data flow
• Control-plane publication
• Hover or tap a box to highlight its connections

Read from top to bottom: producers, the gateway and importer that admit data, durable Redpanda topics, the consumers that process them, and the stores they write.

The agent admission roster is reconstructed from a compacted log before the gateway serves requests. The control plane persists registry changes in PostgreSQL and retries outstanding publications. An operator action and its arrival at every gateway are therefore distinct moments.

Target V2 architecture

The endpoint adds configured collectors, bounded local admission, a durable spool, and delivery over mTLS. Inventory remains separate from event telemetry. Signed policy, native packaging, verified updates, and a restricted response plane are later milestones. A generic internal event bus is an implementation option, not an architectural requirement.

The planned frontend presents query evidence and control workflows. There is no current V2 React router, API client, or authentication adapter to document. Vulnerability advisories and inventory are implemented inputs to future matching; their coexistence does not yet produce vulnerability findings.

Evolution path

1. Finish the agent foundation and authenticated delivery.
2. Prove the authentication collector through the existing gateway and detection path.
3. Add inventory collection with correct full-scan boundaries.
4. Extend typed contracts before introducing new event classes or control messages.
5. Address production constraints before claiming fleet readiness.

Use service responsibilities to locate an owner, event lifecycle to follow durability, and trust boundaries to understand authority.

Source evidence

Reviewed against the source baseline. Seagull-backend-v2/deploy/compose.yaml · Seagull-backend-v2/README.md · Seagull-agent-v2/cmd/seagull-agent/main.go.