symphony-flow

Field	Value
Status	Active
Tier	T1 Critical
Kind	Software
Org	symphonycore-org
Infra Repo	sc-infrastructure
Last Reviewed	2026-02-22

Purpose

Workflow orchestration platform for automating multi-application business processes at Symphony Core. Handles employee onboarding (Google Workspace + ClickUp + email), client onboarding (GHL + Drive + Slack), meeting notes export (Fireflies.ai to Drive), and client knowledge graph consolidation (Discovery + SearchAtlas + GHL). Communicates with GHL bidirectionally via the ghl-data-sync API (not direct GHL API) -- reads contacts/location data, writes custom values/notes/workflow triggers.

Scope

This repo IS for:

• Workflow orchestration engine (executor, state, retry, compensation)
• Integration adapters (Google Workspace, ClickUp, GHL, Slack, Fireflies, Email, Symphony Platform)
• Admin UI for triggering and monitoring workflows
• Workflow configuration (YAML-based roles, tiers, templates)

This repo is NOT for:

• Direct GHL API access -> see ghl-data-sync
• Discovery/SearchAtlas intelligence services -> see symphony-platform
• Docker orchestration in production -> see sc-infrastructure

Related Repos

Relationship	Repo
Dependencies	ghl-data-sync, symphony-platform, sc-infrastructure
Dependents	N/A

---

Quick Start

# Clone and install
git clone <repo-url>
cd symphony-flow
npm install

# Start with Docker (recommended)
cp .env.example .env
docker-compose up -d

# Or run locally with mock adapters
USE_MOCK_ADAPTERS=true npm run dev

# Trigger a workflow via CLI
npm run cli -- trigger employee_onboarding --input examples/employee_input.json

# Check status
npm run cli -- status <run-id>

# Run tests
npm test

See .env.example for all required environment variables.

Getting Started (Full Setup)

# Install dependencies
npm install

# Start infrastructure
docker-compose up -d postgres redis

# Run migrations
npm run db:migrate

# Start development server
npm run dev

Technology Stack

Layer	Technology
Runtime	Node.js 20 LTS
Framework	Fastify
Queue/Jobs	BullMQ with Redis
Database	PostgreSQL 15
UI	React + TypeScript + Tailwind
Config	YAML files
Container	Docker + docker-compose

Implementation Status

All major features are complete. 750+ tests passing (43 suites).

Feature	Status	Key Capabilities
Employee Onboarding (MVP)	Complete	Google Workspace, ClickUp, email, compensation/rollback
Client Onboarding (Phase 2)	Complete	GHL webhooks, Slack channels, Drive provisioning, tier configs
Meeting Notes Export	Complete	Fireflies.ai polling, client auto-classification, Slack interactive
Client Knowledge Graph	Complete	Multi-source aggregation, priority merge, quality scoring, HTML views
Workflow Monitoring	Complete	Metrics, alerting, reporting, RBAC-enforced dashboard
Agency Export	Complete	Client data export with contractor management

Project Structure

.
├── config/                  # YAML configurations
│   ├── workflows/           # Workflow definitions (employee, client onboarding)
│   ├── roles/               # Role configs (developer, sales, operations, admin)
│   ├── tiers/               # Tier configs (starter, growth, professional)
│   ├── adapters/            # Adapter configs (google, clickup, ghl)
│   └── templates/emails/    # Email templates (Handlebars)
├── src/
│   ├── adapters/            # Integration adapters (GHL, Slack, Fireflies, etc.)
│   ├── api/                 # Fastify API (routes, middleware, plugins)
│   ├── cli/                 # CLI tool (trigger, status, health)
│   ├── db/                  # Schema and migrations
│   ├── engine/              # Orchestration engine (executor, state, retry)
│   ├── lib/                 # Shared utilities
│   ├── services/            # Business logic (meeting-notes, knowledge-graph, etc.)
│   ├── ui/                  # Admin dashboard (React)
│   └── workers/             # BullMQ workers (workflow, scheduled)
├── tests/
│   ├── unit/                # Unit tests
│   ├── integration/         # Integration tests
│   ├── e2e/                 # End-to-end tests
│   ├── fixtures/            # Test input data
│   └── data/                # Test reference data
├── docs/
│   ├── prds/                # Product requirement documents
│   ├── dev/                 # Developer documentation
│   ├── user/                # User guides
│   ├── guides/              # Setup guides
│   ├── sprints/             # Sprint plans
│   └── INDEX.md             # Documentation index
├── docker-compose.yaml      # Local development stack
├── Dockerfile               # Production container
├── ARCHITECTURE.md          # System design and architecture
└── CONTRIBUTING.md          # Contribution guidelines

Testing

Test Type	Location	Run With
Unit	tests/unit/	npm run test:unit
Integration	tests/integration/	npm run test:integration
E2E	tests/e2e/	npm run test:e2e
All	tests/	npm test
Coverage	tests/	npm run test:coverage

Integration tests require running infrastructure (use docker-compose up -d postgres redis).

Key Concepts

Adapter Interface

All adapters implement a common interface (see src/adapters/base-adapter.ts):

interface IntegrationAdapter {
  name: string;
  healthCheck(): Promise<HealthStatus>;
  execute(action: string, params: Record<string, any>): Promise<ActionResult>;
  compensate(action: string, params: Record<string, any>): Promise<ActionResult>;
  validateParams(action: string, params: Record<string, any>): ValidationResult;
}

Workflow Execution Flow

Trigger (API/Webhook)
  -> Load workflow + role/tier config
  -> Create workflow_run record
  -> Queue job (BullMQ)
  -> Worker executes steps (respecting depends_on, parallel_with)
  -> Success: update status, notify
  -> Failure: run compensation in reverse, alert

Error Handling

1. Validate inputs before any adapter calls
2. Check for duplicates before creating resources
3. Use idempotency keys to prevent double-processing
4. Log all errors with correlation IDs (run_id, step_id)
5. Compensation runs in reverse order of successful steps

Document Index

Document	Purpose
ARCHITECTURE.md	Technical architecture and system design
docs/INDEX.md	Full documentation index
docs/dev/setup.md	Developer setup guide
docs/dev/api-reference.md	API reference
docs/user/user-guide.md	User guide
docs/user/admin-guide.md	Admin guide
CONTRIBUTING.md	Contribution guidelines

Documentation Requirements

Each feature must include both user and developer documentation:

• User docs (docs/user/): Step-by-step procedures, no jargon
• Developer docs (docs/dev/): Technical details, API examples, config schemas