Backend Service
FluidGrids does not have a dedicated backend workspace module; it builds on top of the shared wspace-workflow-svc on the Burdenoff Workspaces platform. It runs on Burdenoff's managed Kubernetes platform in the India region and is federated into the workspace public gateway (wspace-public-gateway) and workspace internal gateway (wspace-int-gateway).
What it does
- Workflows — visual pipeline definition, versioning, and publishing
- Runs — run orchestration with traceability, logs, and retry; execution is dispatched to the
fluidgrids-workerstier (see Execution tier) - Triggers — five seeded types: manual/API, webhook, scheduled (cron), form, and error (platform and third-party event triggers are not available)
- Nodes — built-in node registry plus the store-node catalog; each node runs as its own sandboxed microservice
- Connections — node credential adapters resolve the workspace's connections (managed by the integrations service) at execution time
- Mappers — data transformation and mapping between nodes
- Context — multi-dimensional workspace/project/actor isolation
- Subscriptions — real-time GraphQL subscriptions for run status
Environment selection
The service reads its gateway and database endpoints from environment variables. In production it uses:
| Service | Prod endpoint |
|---|---|
| Workspace public gateway | https://graphqlworkspaces.burdenoff.com/workspaces/graphql |
| Workspace internal gateway | in-cluster only (http://wspace-int-gateway/workspaces/graphql), not reachable from outside |
| Global public gateway | https://graphql.burdenoff.com/global/graphql |
Local development uses localhost ports:
| Service | Local endpoint |
|---|---|
| Workspace public gateway | http://localhost:4003/workspaces/graphql |
| Global public gateway | http://localhost:4000/global/graphql |
Quick start (local development)
# Install dependencies
bun install
# Start state services (PostgreSQL + Valkey)
cd ../wspace-workflow-state
docker compose up -d
# Generate Prisma client and GraphQL types
cd ../wspace-workflow-svc
bun run gendb
bun run codegen
# Apply migrations
bun run migrate:deploy
# Start development server
bun run dev
Commands
Development
bun run dev # Start development server with watch mode
bun run start # Start production server
Database
bun run migrate # Create new migration
bun run migrate:deploy # Apply migrations
bun run reset # Reset database (force)
bun run db:push # Push schema changes
bun run gendb # Generate Prisma client
Code generation
bun run codegen # Generate GraphQL types
Quality checks
bun run lint # Lint code
bun run lint:fix # Lint and fix issues
bun run format # Format code
bun run format:check # Check code formatting
bun run type:check # TypeScript type checking
bun run test # Run tests
bun run test:watch # Run tests in watch mode
bun run test:coverage # Run tests with coverage
bun run knip # Check for unused dependencies
Build & deploy
bun run build # Build for production
bun run sanity # Run all quality checks
GraphQL Hive
bun run hive:schema # Generate Hive schema
bun run hive:check # Check schema compatibility
bun run hive:dev # Publish to development
bun run hive:publish # Publish to development
bun run hive:publish:staging # Publish to staging
bun run hive:publish:production # Publish to production
Technology stack
- Runtime: Bun 1.3.5+
- Language: TypeScript 5.9+
- Framework: Elysiajs + GraphQL Yoga
- GraphQL: Apollo Federation v2, GraphQL Hive Cloud
- Database: PostgreSQL 18+ + Prisma 7.x
- Cache / Events: managed Redis-compatible cache (TLS) via
@burdenoff/be-sdk; the job/event bus is Redis Streams - Execution:
fluidgrids-workers(Redis Streams consumer, per-node sandbox) - SDK:
@burdenoff/be-sdk
Environment variables
Key variables (see .env.example and .env.local.example for the full list):
DATABASE_URL— PostgreSQL connection string (TLS required)REDIS_URL— Redis-compatible cache connection string (TLS)WSPACE_INT_GATEWAY_URL— Internal gateway URLGLOBAL_PUBLIC_GATEWAY_URL— Cross-layer gateway URLSERVICE_LAYER— Service layer (wspace)
Architecture
Module structure
Each module contains:
schema/— GraphQL schema definitionsresolvers/— GraphQL resolversservices/— Business logic__tests__/— Unit tests
Execution tier
wspace-workflow-svc orchestrates workflows but does not execute node logic in-process. When a run is dispatched, jobs are published to a Redis Streams job/event bus (via @burdenoff/be-sdk) and consumed by fluidgrids-workers, a separate worker service. The worker drives the run and invokes each node over GraphQL. Nodes run as sandboxed per-node microservices (one container image per node/version), so integration code is isolated from the engine and from other nodes. See Custom Nodes for the node contract and image-build path.
Layer configuration
This service is part of the wspace (workspace) layer and uses:
- Internal Gateway:
wspace-int-gatewayfor same-layer calls - Cross-Layer Gateway:
global-public-gatewayfor cross-layer calls
Context field
All Prisma models include a context JSON field for multi-dimensional data isolation:
interface EntityContext {
workspace_id: string; // REQUIRED
project_id?: string; // Optional
actor_id?: string; // Optional
organization_id?: string; // Optional
}
Related repositories
- Service:
github.com/algoshred/wspace-workflow-svc - Workers (execution tier):
github.com/algoshred/fluidgrids-workers - State:
~/products/wspace/workflow/wspace-workflow-state - E2E Tests:
~/products/fluidgrids/fluidgrids-doctor/
Development workflow
- Start state services:
cd ../wspace-workflow-state && docker compose up -d - Generate types:
bun run codegen && bun run gendb - Apply migrations:
bun run migrate:deploy - Start dev server:
bun run dev - Run tests:
bun run test - Before commit:
bun run sanity
Source
- Repository:
github.com/algoshred/wspace-workflow-svc - Deployed continuously from
mainvia GitHub Actions (alpha, then production)