flowfish/docs/architecture/ARCHITECTURE_SIMPLE.md

Flowfish Architecture - Simple Overview

Data Flow Diagram

┌─────────────────────────────────────────────────────────────────────────────────────┐
│                                 FLOWFISH DATA FLOW                                   │
│                        eBPF-Based Kubernetes Observability                          │
└─────────────────────────────────────────────────────────────────────────────────────┘

                                    ┌─────────────┐
                                    │    USER     │
                                    │  (Browser)  │
                                    └──────┬──────┘
                                           │ HTTP
                                           ▼
┌──────────────────────────────────────────────────────────────────────────────────────┐
│  ┌─────────────────────────────────────────────────────────────────────────────┐    │
│  │                              frontend                                        │    │
│  │                         (React + TypeScript)                                 │    │
│  │                                                                              │    │
│  │   Dashboard │ Clusters │ Analysis Wizard │ Live Map │ Alerts                │    │
│  └──────────────────────────────────────┬──────────────────────────────────────┘    │
│                                          │ REST API                                  │
│                                          ▼                                           │
│  ┌─────────────────────────────────────────────────────────────────────────────┐    │
│  │                               backend                                        │    │
│  │                         (FastAPI + Python)                                   │    │
│  │                                                                              │    │
│  │   Auth │ Cluster CRUD │ Analysis API │ Query Proxy                          │    │
│  └──────────────────────────────────────┬──────────────────────────────────────┘    │
│                                          │ gRPC                                      │
│                                          ▼                                           │
│  ┌─────────────────────────────────────────────────────────────────────────────┐    │
│  │                        analysis-orchestrator                                 │    │
│  │                         (gRPC Server + Python)                               │    │
│  │                                                                              │    │
│  │   Analysis Lifecycle │ Task Distribution │ State Management                 │    │
│  └──────────────────────────────────────┬──────────────────────────────────────┘    │
│                                          │ gRPC                                      │
│  ┌───────────────────────────────────────┼──────────────────────────────────────┐   │
│  │                        cluster-manager│                                       │   │
│  │                     (gRPC Server :5003)                                       │   │
│  │                                       │                                       │   │
│  │   K8s API → Namespaces, Pods, Deployments, Labels (Cluster-wide access)      │   │
│  └───────────────────────────────────────┼──────────────────────────────────────┘   │
│                                          ▼                                           │
│  ┌─────────────────────────────────────────────────────────────────────────────┐    │
│  │                         ingestion-service                                    │    │
│  │                         (gRPC Server + Python)                               │    │
│  │                                                                              │    │
│  │   ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐        │    │
│  │   │  Trace Manager  │ ─► │  gRPC CLIENT    │ ─► │ RabbitMQ Pub    │        │    │
│  │   │  (Lifecycle)    │    │  (to Gadget)    │    │ (Event Publish) │        │    │
│  │   └─────────────────┘    └────────┬────────┘    └────────┬────────┘        │    │
│  └───────────────────────────────────┼─────────────────────┼───────────────────┘    │
│                                       │                     │                        │
└───────────────────────────────────────┼─────────────────────┼────────────────────────┘
                                        │                     │
                                        │ gRPC (Pull Events)  │ AMQP (Publish)
                                        ▼                     ▼
┌───────────────────────────────────────────────┐  ┌──────────────────────────────────┐
│           TARGET CLUSTER                       │  │           rabbitmq               │
│  ┌─────────────────────────────────────────┐  │  │        (Message Queue)           │
│  │          inspektor-gadget               │  │  │                                  │
│  │           (DaemonSet)                    │  │  │  flowfish.events.network ───┐   │
│  │                                          │  │  │  flowfish.events.dns    ───┼─► │
│  │   eBPF Programs → gRPC Server (:16060)  │  │  │  flowfish.events.tcp    ───┘   │
│  │                                          │  │  │                                  │
│  │   Events: network, dns, tcp, process    │  │  └──────────────┬───────────────────┘
│  └─────────────────────────────────────────┘  │                  │
└───────────────────────────────────────────────┘                  │ AMQP (Consume)
                                                                   │
                                                    ┌──────────────┴──────────────┐
                                                    │                             │
                                                    ▼                             ▼
                                  ┌─────────────────────────────┐  ┌─────────────────────────────┐
                                  │     timeseries-writer       │  │      graph-writer           │
                                  │    (RabbitMQ Consumer)      │  │    (RabbitMQ Consumer)      │
                                  │                             │  │                             │
                                  │  Batch Events → ClickHouse  │  │  Build Graph → Neo4j       │
                                  └──────────────┬──────────────┘  └──────────────┬──────────────┘
                                                 │                                │
                                                 ▼                                ▼
                                  ┌─────────────────────────────┐  ┌─────────────────────────────┐
                                  │         clickhouse          │  │           neo4j             │
                                  │    (Time-Series Database)   │  │     (Graph Database)        │
                                  │                             │  │                             │
                                  │  Tables:                    │  │  Nodes: Pod, Service, NS    │
                                  │   • network_flows           │  │  Edges: COMMUNICATES_WITH   │
                                  │   • dns_queries             │  │         BELONGS_TO          │
                                  │   • tcp_connections         │  │         DEPENDS_ON          │
                                  └──────────────┬──────────────┘  └──────────────┬──────────────┘
                                                 │                                │
                                                 └────────────────┬───────────────┘
                                                                  │ Query
                                                                  ▼
                                                    ┌─────────────────────────────┐
                                                    │        graph-query          │
                                                    │     (Query Service)         │
                                                    │                             │
                                                    │  Dependency Graph Queries   │
                                                    └──────────────┬──────────────┘
                                                                   │ gRPC
                                                                   ▼
                                                    ┌─────────────────────────────┐
                                                    │          backend            │
                                                    │      (Query Results)        │
                                                    └──────────────┬──────────────┘
                                                                   │ REST
                                                                   ▼
                                                    ┌─────────────────────────────┐
                                                    │         frontend            │
                                                    │      (Live Map / Dashboard) │
                                                    └─────────────────────────────┘


═══════════════════════════════════════════════════════════════════════════════════════
                              KEY COMMUNICATION PATTERNS
═══════════════════════════════════════════════════════════════════════════════════════

  ┌─────────────────────────────────────────────────────────────────────────────────┐
  │  PROTOCOL       │ SOURCE              │ TARGET               │ DIRECTION        │
  ├─────────────────┼─────────────────────┼──────────────────────┼──────────────────┤
  │  REST/HTTP      │ frontend            │ backend              │ Request/Response │
  │  gRPC           │ backend             │ analysis-orchestrator│ Request/Response │
  │  gRPC           │ analysis-orchestrator│ ingestion-service   │ Request/Response │
  │  gRPC           │ ingestion-service   │ inspektor-gadget     │ Stream (PULL)    │
  │  AMQP           │ ingestion-service   │ rabbitmq             │ Publish          │
  │  AMQP           │ rabbitmq            │ timeseries-writer    │ Consume          │
  │  AMQP           │ rabbitmq            │ graph-writer         │ Consume          │
  │  TCP/Native     │ timeseries-writer   │ clickhouse           │ Batch Insert     │
  │  Bolt           │ graph-writer        │ neo4j                │ Cypher Queries   │
  │  gRPC           │ backend             │ graph-query          │ Request/Response │
  └─────────────────────────────────────────────────────────────────────────────────┘

═══════════════════════════════════════════════════════════════════════════════════════
                                 CRITICAL POINT
═══════════════════════════════════════════════════════════════════════════════════════

  ⚠️  ingestion-service connects to Gadget as a CLIENT!
  
      Inspektor Gadget → gRPC SERVER (exposes API only; does not push anywhere)
      ingestion-service → gRPC CLIENT (PULLS events from Gadget)
      ingestion-service → PUBLISHES to RabbitMQ
      
      Thanks to this architecture:
      ✓ Gadget stays lightweight (eBPF + gRPC server only)
      ✓ Decoupled — queue failure does not affect Gadget
      ✓ Backpressure — ingestion-service can apply rate control
      ✓ Multi-cluster — different clusters can use different connection protocols

Service Summary

Pod Name	Port	Role	Technology
frontend	3000	Web UI	React, TypeScript, Ant Design
backend	8000	REST API Gateway	FastAPI, Python
change-detection-worker	8001	Change Detection (Scalable)	FastAPI, Python
analysis-orchestrator	5002	Analysis Lifecycle	gRPC, Python
cluster-manager	5003	Cluster Connections	gRPC, Python
ingestion-service	5000	Event Collection	gRPC, Python
timeseries-writer	-	ClickHouse Writer	Python, pika
graph-writer	-	Neo4j Writer	Python, aio_pika
graph-query	8001	Graph Queries	REST, Python
inspektor-gadget	16060	eBPF Data Source	DaemonSet, gRPC
rabbitmq	5672	Message Queue	RabbitMQ
clickhouse	9000	Time-Series DB	ClickHouse
neo4j	7687	Graph DB	Neo4j
postgresql	5432	Metadata DB	PostgreSQL
redis	6379	Cache (+ Leader Election)	Redis