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

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