# Flowmaster Backend

> FlowMaster backend: 29 deployed services, REST APIs, Event Bus patterns, MCP integration

- Skill: `eron1703/flowmaster-backend` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add eron1703/flowmaster-backend`
- Raw SKILL.md: https://api.skillmd.com/api/skills/eron1703/flowmaster-backend/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: eron1703 (https://skillmd.com/u/eron1703)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/eron1703/flowmaster-backend

---


# FlowMaster Backend Architecture & APIs

> **SNAPSHOT: 2026-02-08 11:00 Dubai Time (07:00 UTC) — likely changing soon**

## Overview

FlowMaster is a modular microservices platform with **29 services deployed and running** on K3S (dev-02 server 65.21.52.58). All 79 requirements (R01-R79) have code deployed. **ALL services are UNTESTED** — no integration, health check, or e2e testing performed.

Each service owns its database and communicates via Event Bus (async) and REST APIs (sync).

---

## 13 Original Core Services

### 1. Process Design Service (Port 9003)
**Purpose:** Design, version, and manage process definitions
**Tech:** Python/FastAPI, ArangoDB
**Image:** r03 | **Reqs:** R03-R20
**Key Endpoints:**
- `POST /processes` — Create process definition
- `GET /processes/{id}` — Retrieve process
- `PUT /processes/{id}` — Update process
- `POST /processes/{id}/publish` — Publish version
- `GET /processes/{id}/versions` — List versions

### 2. Execution Engine (Port 9005)
**Purpose:** Execute processes, orchestrate tasks, manage state
**Tech:** Python/FastAPI, PostgreSQL + Redis
**Image:** r21-r24 | **Reqs:** R21-R24
**Key Endpoints:**
- `POST /executions` — Start execution
- `GET /executions/{id}` — Get execution state
- `PUT /executions/{id}/pause` — Pause
- `PUT /executions/{id}/resume` — Resume
- `GET /executions/{id}/history` — Event history

### 3. Human Task Service (Port 9006)
**Purpose:** Human-in-the-loop tasks for approvals, forms, decisions
**Tech:** Python/FastAPI, ArangoDB + Redis
**Image:** r24 | **Reqs:** R24
**Key Endpoints:**
- `POST /tasks` — Create task
- `GET /tasks/{id}` — Get task details
- `PUT /tasks/{id}/assign` — Assign
- `PUT /tasks/{id}/respond` — Submit response

### 4. AI Agent Orchestration (Port 9007)
**Purpose:** Central LLM/agent orchestrator with routing, caching, metering
**Tech:** Python + Express.js, PostgreSQL + Redis + ArangoDB
**Image:** latest
**Key Endpoints:**
- `POST /agents/{id}/invoke` — Call LLM
- `POST /agents/{id}/stream` — Stream response
**Port Assignment Note:** Canonical registry assigns port 9007 (conflict resolution H1)

### 5. Document Intelligence (Port 9002)
**Purpose:** Document → structured data, embeddings, searchable content
**Tech:** Python/FastAPI, ArangoDB
**Image:** r01 | **Reqs:** R01-R02
**Key Endpoints:**
- `POST /documents/upload` — Upload document
- `POST /documents/{id}/extract` — Extract entities

### 6. Authentication Service (Port 8002)
**Purpose:** JWT/OAuth auth with RBAC/ABAC
**Tech:** Python/FastAPI, PostgreSQL
**Image:** ghcr.io latest
**Key Endpoints:**
- `POST /auth/login` — Authenticate
- `POST /auth/refresh` — Refresh token
- `GET /auth/validate` — Validate token

### 7. API Gateway (Port 9000)
**Purpose:** Single entrypoint, dynamic routing, rate limiting
**Tech:** Python/FastAPI (NOT Node.js), Redis + ArangoDB
**Image:** latest
**Key Endpoints:** `*` (dynamic proxy routing)

### 8. Event Bus (Port 9013)
**Purpose:** Reliable event streaming with schema validation & replay
**Tech:** Python/FastAPI + Kafka
**Image:** latest
**Key Endpoints:**
- `POST /events` — Publish event
- `POST /subscriptions` — Subscribe
- `GET /events/replay` — Replay from timestamp

### 9. WebSocket Gateway (Port 9010)
**Purpose:** Real-time communication, presence, streaming
**Tech:** Node.js/TypeScript, Socket.io + Redis
**Image:** 8ef0412c (4 restarts)
**Key Endpoints:** `WS /connect`, `WS /channels/{id}/subscribe`

### 10. Notification Service (Port 9009)
**Purpose:** Email, SMS, push with templating & retry
**Tech:** Python/FastAPI, PostgreSQL
**Image:** r23-final
**Key Endpoints:**
- `POST /notifications/send` — Send notification
- `GET /notifications/{id}` — Get status

### 11. Scheduling Service (Port 9008)
**Purpose:** Cron triggers, time-based automation
**Tech:** Python/FastAPI, PostgreSQL (APScheduler)
**Image:** 192c806d
**Key Endpoints:**
- `POST /schedules` — Create schedule
- `POST /schedules/{id}/execute` — Trigger now

### 12. Service Registry (Port 8001)
**Purpose:** Service discovery and health monitoring
**Tech:** Python/FastAPI
**Image:** ghcr.io latest

### 13. SSO Service
**Purpose:** OAuth/SAML enterprise authentication
**Status:** Working on dev-02 server (no dedicated repo)

---

## 6 New Services (Built Feb 2026)

### 14. Process Analytics (Port 9014)
**Purpose:** Process performance metrics, bottleneck detection
**Tech:** Python/FastAPI
**Image:** latest | **Reqs:** R48-R50
**Key Endpoints:**
- `GET /analytics/processes/{id}` — Process metrics
- `GET /analytics/dashboard` — Overview dashboard
- `POST /analytics/reports` — Generate report

### 15. External Integration (Port 9015)
**Purpose:** External system connectors, webhook management
**Tech:** Python/FastAPI
**Image:** r51-fix3 | **Reqs:** R51-R53
**Key Endpoints:**
- `POST /integrations` — Register integration
- `POST /integrations/{id}/execute` — Execute connector
- `POST /webhooks` — Register webhook
**Port Assignment Note:** Canonical registry assigns port 9015 (conflict resolution H2)

### 16. FlowMaster MCP Server (Port 9000)
**Purpose:** Unified MCP gateway for AI agent access to FlowMaster + SDX
**Tech:** Python/FastAPI
**Image:** latest | **Reqs:** R54-R56
**Key Endpoints:** MCP protocol (tool listing, tool execution)
**Note:** Shares port with API Gateway (9000) when proxied through nginx

### 17. Legal Entity Service (Port 8014)
**Purpose:** Organizational structure, legal entities, relationships
**Tech:** Python/FastAPI
**Image:** r66-fix | **Reqs:** R66-R68
**Key Endpoints:**
- `POST /entities` — Create legal entity
- `GET /entities/{id}` — Get entity
- `GET /entities/{id}/relationships` — Get relationships

### 18. Business Rules Engine (Port 8018)
**Purpose:** DMN-style decision tables, rule evaluation
**Tech:** Python/FastAPI
**Image:** r69-fix | **Reqs:** R69-R72
**Key Endpoints:**
- `POST /rules` — Create rule set
- `POST /rules/{id}/evaluate` — Evaluate rules
- `GET /rules/{id}/versions` — Rule versions

### 19. BAC Marketplace (Port 9016)
**Purpose:** Process marketplace — publish, download, share processes
**Tech:** Python/FastAPI
**Image:** r73 | **Reqs:** R73-R76
**Key Endpoints:**
- `POST /marketplace/publish` — Publish process
- `GET /marketplace/search` — Search marketplace
- `POST /marketplace/{id}/install` — Install process
**Port Assignment Note:** Uses 9016; Agent Service uses 9016 (see port registry for clarification)

---

## 3 Rebuilt/Revived Services

### 20. Agent Service (Port 9016)
**Purpose:** Agent personas, skills, learning from feedback
**Tech:** Python/FastAPI
**Image:** r36-r47 | **Reqs:** R36-R38, R45-R47
**Key Endpoints:**
- `POST /agents` — Create agent persona
- `POST /agents/{id}/learn` — Submit learning data
- `GET /agents/{id}/skills` — Get agent skills

### 21. Prompt Engineering (Port 8012)
**Purpose:** Prompt templates, versioning, dynamic assembly
**Tech:** Python/FastAPI
**Image:** r39 | **Reqs:** R39-R41
**Key Endpoints:**
- `POST /prompts` — Create template
- `POST /prompts/{id}/render` — Render with context
- `GET /prompts/{id}/versions` — Template versions

### 22. Knowledge Hub (Port 8009)
**Purpose:** RAG, knowledge management, agent data access
**Tech:** Python/FastAPI (revived from 38K lines internal-data-hub)
**Image:** r42-r46 | **Reqs:** R42-R44, R46
**Key Endpoints:**
- `POST /knowledge/query` — RAG query
- `POST /knowledge/ingest` — Ingest documents
- `POST /api/v1/feedback` — Feedback capture (R45)

---

## 7 Frontend & Companion Apps

### 23. Frontend (Port 3000)
**Purpose:** Main admin UI, process management
**Tech:** Next.js, React, TypeScript
**Image:** ea2a29b

### 24. Engage App (Port 3001)
**Purpose:** Employee task execution with DXG + AI chat
**Tech:** Next.js, React, TypeScript
**Image:** r27-r45 | **Reqs:** R25-R29, R45
**Key Features:** DXG briefing, analytics widgets, AI chat, feedback capture

### 25. Manager App (Port 3005)
**Purpose:** Agent escalation handling dashboard
**Tech:** Next.js, React, TypeScript
**Image:** r30 | **Reqs:** R30-R33
**Port Assignment Note:** Canonical registry assigns port 3005 (conflict resolution H4)

### 26. Process Designer (Port 3002)
**Purpose:** Visio-quality drag-and-drop BPMN editor
**Tech:** Next.js, React, TypeScript, ReactFlow
**Image:** r77 | **Reqs:** R77-R79
**Key Features:** Swimlane views, inline AI assistant, drag-and-drop

### 27. DXG Service (Port 9011)
**Purpose:** Dynamic Experience Generator — AI-powered UI from workflow context
**Tech:** Python/FastAPI
**Image:** r34-r35 | **Reqs:** R34-R35
**Key Endpoints:**
- `POST /api/v1/analyze/{task_id}` — Context analysis
- `POST /api/v1/smart-form/{task_id}` — Pre-filled form
- `POST /api/v1/briefing/{task_id}` — Case summary

### 28. Process Views (Port 8019)
**Purpose:** Flow chart views, process visualization
**Tech:** Python/FastAPI
**Image:** r57-fix | **Reqs:** R57-R59

### 29. Process Versioning (Port 8020)
**Purpose:** Process version management, diff, branching
**Tech:** Python/FastAPI
**Image:** r60-fix | **Reqs:** R60-R62

### 30. Process Linking (Port 8021)
**Purpose:** Cross-process dependencies and linking
**Tech:** Python/FastAPI
**Image:** r63 | **Reqs:** R63-R65

---

## Cross-Service Patterns

### Authentication
All API calls must include:
```
Authorization: Bearer {accessToken}
X-Tenant-Id: {tenantId}
X-Service-Name: {serviceName} (service-to-service)
```

### Database Connectivity
- Each service owns its database
- Cross-service data via Event Bus (async) or REST APIs (sync)
- Shared infrastructure: ArangoDB (port 8529), PostgreSQL, Redis

### Service Structure (Standard)
```
src/
├── api/            # HTTP controllers
├── core/           # Business logic
├── domain/         # Entity models
├── infra/
│   ├── db/         # Database repository
│   ├── messaging/  # Event Bus integration
│   ├── cache/      # Redis adapter
│   └── http/       # External service clients
├── config/         # Environment & DI
├── security/       # Auth/RBAC
└── utils/          # Helpers
```

---

## Testing Status: ALL UNTESTED

**What was done:**
- Code written for all 79 requirements
- Docker images built (macOS arm64 → linux/amd64 cross-compile)
- Images transferred via docker save/gzip/scp/docker load
- Pushed to K3S local registry
- Pod status confirmed Running via kubectl

**What was NOT done:**
- No HTTP health check verification
- No integration testing
- No end-to-end workflow testing
- No database schema verification
- No API contract testing
- Code NOT pushed to GitLab

---

## Source Control
- **Primary:** GitLab (`flow-master` group, private)
- **Mirror:** GitHub (`HCB-Consulting-ME` org)

---

## Port Registry & Conflict Resolution

**IMPORTANT:** All port assignments have been canonicalized in PORT_REGISTRY.md to resolve conflicts:

### Conflicts Resolved

| Issue | Resolution | Status |
|-------|-----------|--------|
| **H1: Port 9006** | Human Task Service (9006) + AI Agent Service (9007) | ✅ Resolved |
| **H2: Port 9014** | Process Analytics (9014) + External Integration (9015) | ✅ Resolved |
| **H3: Port 9000** | API Gateway (9000) canonical assignment | ✅ Resolved |
| **H4: Port 3001** | Engage App (3001) + Manager App (3005) + Designer (3002) | ✅ Resolved |

### Quick Port Reference

**Core Services:**
- `9000` - API Gateway (entrypoint)
- `9002` - Document Intelligence
- `9003` - Process Design
- `9005` - Execution Engine
- `9006` - Human Task Service
- `9007` - AI Agent Service (NEW ASSIGNMENT)
- `9008` - Scheduling
- `9009` - Notifications
- `9010` - WebSocket Gateway
- `9011` - DXG Service
- `9013` - Event Bus
- `9014` - Process Analytics
- `9015` - External Integration (NEW ASSIGNMENT)
- `9016` - Agent Service

**Authentication & Infrastructure:**
- `8001` - Service Registry
- `8002` - Authentication
- `8009` - Knowledge Hub
- `8014` - Legal Entity Service
- `8018` - Business Rules Engine
- `8019` - Process Views
- `8020` - Process Versioning
- `8021` - Process Linking

**Frontends:**
- `3000` - Main Frontend
- `3001` - Engage App
- `3002` - Process Designer
- `3005` - Manager App

**See PORT_REGISTRY.md for complete details**

---

## When to Use This Skill

1. **Building MCP server interactions** with FlowMaster APIs
2. **Designing process workflows** — Process Design Service
3. **Handling execution logic** — Execution Engine
4. **Human tasks** — approval flows
5. **AI/LLM integration** — AI Agent Service (9007)
6. **Real-time updates** — WebSocket Gateway
7. **Authentication** — JWT patterns
8. **Event-driven architecture** — Event Bus topics
9. **Document processing** — Document Intelligence
10. **Process analytics** — dashboards and metrics (9014)
11. **External integrations** — connectors and webhooks (9015)
12. **Business rules** — DMN decision tables
13. **Process marketplace** — BAC publish/download

---

## Documentation References

- **PORT_REGISTRY.md** - Canonical port assignments (THIS FILE'S COMPANION)
- **CONFLICT RESOLUTIONS** - See PORT_REGISTRY.md sections H1-H4
- **Service Updates Needed:**
  - AI Agent Service: Update to port 9007
  - External Integration: Update to port 9015
  - Manager App: Update to port 3005