Architecture Overview

FacilFlow is a full-stack data pipeline platform for industrial analytics. It bridges OT (plant floor) and IT (analytics) with a self-service, no-code approach.

System Architecture

graph TB
    subgraph Client["Client Layer"]
        Browser[Web Browser]
        Mobile[Mobile/Tablet]
    end

    subgraph Frontend["Frontend (React 19)"]
        UI[React UI + shadcn/ui]
        Store[Zustand Stores]
        TQ[TanStack Query]
        WS[Socket.IO Client]
    end

    subgraph Backend["Backend (Express.js + TypeScript)"]
        API[REST API Routes]
        Socket[Socket.IO Server]
        Services[Business Services]
        MW[Middleware]
        Sidecar[PyAirbyte Sidecar]
    end

    subgraph Data["Data Layer"]
        PG[(PostgreSQL)]
        Influx[(InfluxDB 3)]
        Storage[(MinIO/S3/Azure/GCS)]
        Redis[(Redis)]
    end

    subgraph ML["ML Platform"]
        MLflow[MLflow]
    end

    subgraph External["External Services"]
        Firebase[Firebase Auth]
        Claude[Claude AI]
        Edge[FacilEdge Agents]
    end

    Browser --> UI
    Mobile --> UI
    UI --> Store
    UI --> TQ
    TQ --> API
    Store --> WS

    API --> Services
    Socket --> Services
    Services --> MW
    MW --> Firebase

    Services --> PG
    Services --> Influx
    Services --> Storage
    Services --> Redis
    Services --> MLflow
    Services --> Sidecar

    Services --> Claude
    Services --> Edge

    style Client fill:#0D9488,color:#fff
    style Frontend fill:#3B82F6,color:#fff
    style Backend fill:#8B5CF6,color:#fff
    style Data fill:#F59E0B,color:#fff
    style ML fill:#EC4899,color:#fff
    style External fill:#1E293B,color:#fff

Technology Stack

Frontend

Backend

Data Storage

External Services

Component Relationships

graph LR
    subgraph Connect["Connect"]
        P1[ConnectorsPage]
        P2[AgentsPage]
        P3[DataSourcesPage]
    end

    subgraph Infrastructure["Infrastructure"]
        P4[ClustersPage]
    end

    subgraph Build["Build"]
        P5[PipelinesPage]
        P6[MLModelsPage]
        P7[SchemaRegistryPage]
    end

    subgraph Analyze["Analyze"]
        P8[DataExplorerPage]
        P9[DashboardPage]
        P10[DataQualityPage]
        P11[LineageExplorerPage]
    end

    subgraph Operate["Operate"]
        P12[AlertsPage]
        P13[SchedulerPage]
        P14[StoragePage]
        P15[AuditLogsPage]
        P16[GovernancePage]
    end

    subgraph Hooks["Hooks + TanStack Query"]
        H1[usePipelines]
        H2[useAgents]
        H3[useQuery]
        H4[useStorage]
        H5[useClusters]
        H6[useML]
    end

    subgraph Services["API Services"]
        S1[pipelineService]
        S2[agentService]
        S3[queryService]
        S4[storageService]
        S5[clusterService]
        S6[mlService]
    end

    P5 --> H1 --> S1
    P2 --> H2 --> S2
    P8 --> H3 --> S3
    P14 --> H4 --> S4
    P4 --> H5 --> S5
    P6 --> H6 --> S6

    style Connect fill:#0D9488,color:#fff
    style Infrastructure fill:#6366F1,color:#fff
    style Build fill:#3B82F6,color:#fff
    style Analyze fill:#8B5CF6,color:#fff
    style Operate fill:#F59E0B,color:#fff
    style Hooks fill:#EC4899,color:#fff
    style Services fill:#EF4444,color:#fff

API Structure

The backend exposes 42 route modules:

Real-time Communication

sequenceDiagram
    participant Client
    participant Socket.IO
    participant Backend
    participant Database

    Client->>Socket.IO: Connect
    Socket.IO->>Backend: Authenticate
    Backend-->>Socket.IO: Authenticated
    Socket.IO-->>Client: Connected

    loop Pipeline Updates
        Backend->>Database: Query status
        Database-->>Backend: Status data
        Backend->>Socket.IO: Emit 'pipeline:status'
        Socket.IO->>Client: Status update
    end

    loop Agent Heartbeats
        Backend->>Socket.IO: Emit 'agent:heartbeat'
        Socket.IO->>Client: Heartbeat data
    end

    loop Dashboard Refresh
        Backend->>Socket.IO: Emit 'dashboard:data'
        Socket.IO->>Client: Widget data update
    end

Security Architecture

Authentication Flow

sequenceDiagram
    participant User
    participant Frontend
    participant Firebase
    participant Backend

    User->>Frontend: Login credentials
    Frontend->>Firebase: signInWithEmailAndPassword()
    Firebase-->>Frontend: ID Token
    Frontend->>Backend: Request + Authorization header
    Backend->>Firebase: Verify token
    Firebase-->>Backend: Decoded claims
    Backend-->>Frontend: Response + user data

Authorization (RBAC)

Deployment Architecture

graph TB
    subgraph Production["Production (Docker Compose)"]
        FE[Frontend Container]
        BE[Backend Container]
        PG[PostgreSQL Container]
        INF[InfluxDB Container]
        MIN[MinIO Container]
        RD[Redis Container]
        ML[MLflow Container]
        AB[PyAirbyte Sidecar]
    end

    subgraph External["External Services"]
        FB[Firebase]
        CL[Claude AI]
        EDGE[FacilEdge Agents]
    end

    LB[Traefik Reverse Proxy] --> FE
    LB --> BE
    BE --> PG
    BE --> INF
    BE --> MIN
    BE --> RD
    BE --> ML
    BE --> AB
    BE --> FB
    BE --> CL
    EDGE --> BE

    style Production fill:#0D9488,color:#fff
    style External fill:#1E293B,color:#fff

Related Documentation

• Multi-Cloud Storage - Storage provider architecture
• API Reference - REST API documentation
• Developer Guide - Development setup and guides