v0.3.0

Developer Guide

Technical documentation for FacilFlow developers.

Overview

FacilFlow is built with:

  • Frontend: React 19, TypeScript, shadcn/ui + Radix UI + TailwindCSS, @xyflow/react, Zustand, TanStack Query, Socket.IO
  • Backend: Node.js 20, Express.js, TypeScript, Drizzle ORM, Socket.IO, Vitest
  • Data: PostgreSQL, InfluxDB 3 (Arrow Flight SQL), MinIO/S3/Azure/GCS, Redis
  • External: Firebase Auth, Claude AI (Claude Code CLI), FacilEdge agents, MLflow, PyAirbyte

Sections

Section Description
Architecture System architecture, component diagrams, data flow
Backend API routes, services, middleware, testing
Frontend Pages, components, state management, theming

Repository Structure

facilflow/
├── src/renderer/              # React frontend
│   ├── App.tsx                # Root component, routing, providers
│   ├── pages/                 # 28 page components
│   │   ├── LoginPage.tsx
│   │   ├── PipelinesPage.tsx
│   │   ├── AgentsPage.tsx
│   │   ├── DataExplorerPage.tsx
│   │   ├── DashboardPage.tsx
│   │   ├── ClustersPage.tsx
│   │   ├── MLModelsPage.tsx
│   │   ├── AlertsPage.tsx
│   │   └── ...
│   ├── components/            # Shared UI components
│   │   ├── pipeline/          # Pipeline builder, nodes, palette
│   │   ├── agents/            # Agent cards, status
│   │   ├── dashboard/         # Dashboard widgets
│   │   ├── data/              # Data explorer, quality, lineage
│   │   └── ui/                # shadcn/ui primitives
│   ├── hooks/                 # Custom React hooks + TanStack Query
│   ├── services/              # API client modules
│   ├── stores/                # Zustand stores
│   └── lib/                   # Utilities, constants
├── backend/
│   └── src/
│       ├── server.ts          # Express app, middleware, Socket.IO
│       ├── routes/            # 42 route modules
│       ├── services/          # Business logic services
│       ├── middleware/         # Auth, RBAC, validation
│       ├── db/                # Drizzle schema and migrations
│       └── utils/             # Shared utilities
├── docs-site/                 # Documentation (custom build.mjs)
├── docker/                    # Docker Compose, Dockerfiles
└── docs/                      # Architecture diagrams
Section Pages
Connect Connectors, Edge Agents, Data Sources
Infrastructure Clusters
Build Pipelines, ML Models, Schemas
Analyze Data Explorer, Dashboards, Data Quality, Lineage
Operate Alerts, Scheduler, Storage, Audit Logs, Governance

Development Workflow

  1. Create feature branch from dev (prefix: yousef-dev/)
  2. Implement changes with tests
  3. Run linting and tests (npm run lint, npm test)
  4. Create pull request
  5. Code review
  6. Merge and delete feature branch

Quick Start

# Frontend
npm install && npm run dev        # Webpack dev server @ localhost:3001

# Backend
cd backend && npm install && npm run dev  # Express @ localhost:3002

# Tests
npm test                          # Frontend (Jest)
cd backend && npm test            # Backend (Vitest)
esc