|
| 1 | +# FBP Integration with Constructive Functions |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +This document describes how [Flow-Based Programming](https://en.wikipedia.org/wiki/Flow-based_programming) (FBP) concepts map onto the Constructive Functions platform, enabling visual flow graphs where each registered platform function becomes a draggable node with typed ports. |
| 6 | + |
| 7 | +## Background |
| 8 | + |
| 9 | +### Platform Function Definitions |
| 10 | + |
| 11 | +Functions are registered in `constructive_infra_public.platform_function_definitions`: |
| 12 | + |
| 13 | +```sql |
| 14 | +CREATE TABLE platform_function_definitions ( |
| 15 | + name TEXT PRIMARY KEY, |
| 16 | + task_identifier TEXT NOT NULL, -- dispatch key, e.g. 'email:send_email' |
| 17 | + service_url TEXT, |
| 18 | + is_invocable BOOLEAN DEFAULT true, |
| 19 | + is_built_in BOOLEAN DEFAULT false, |
| 20 | + scope TEXT, -- e.g. 'platform', 'app' |
| 21 | + description TEXT, |
| 22 | + required_secrets composite[], -- (name, required) pairs |
| 23 | + required_configs composite[], -- (name, required) pairs |
| 24 | + namespace_id UUID REFERENCES platform_namespaces(id), |
| 25 | + created_at TIMESTAMPTZ, |
| 26 | + updated_at TIMESTAMPTZ |
| 27 | +); |
| 28 | +``` |
| 29 | + |
| 30 | +### handler.json Manifest |
| 31 | + |
| 32 | +Each function's source directory contains a `handler.json`: |
| 33 | + |
| 34 | +```json |
| 35 | +{ |
| 36 | + "name": "send-email", |
| 37 | + "version": "1.6.4", |
| 38 | + "type": "node-graphql", |
| 39 | + "port": 8081, |
| 40 | + "taskIdentifier": "email:send_email", |
| 41 | + "description": "Sends emails directly from job payload", |
| 42 | + "dependencies": { ... } |
| 43 | +} |
| 44 | +``` |
| 45 | + |
| 46 | +### FBP NodeDefinition (from `@fbp/types`) |
| 47 | + |
| 48 | +```typescript |
| 49 | +interface NodeDefinition { |
| 50 | + context: string; // namespace, e.g. "email" |
| 51 | + name: string; // e.g. "send-email" |
| 52 | + category?: string; // palette group |
| 53 | + inputs?: PortDef[]; // input ports |
| 54 | + outputs?: PortDef[]; // output ports |
| 55 | + props?: PropDef[]; // configuration properties |
| 56 | + description?: string; |
| 57 | + icon?: string; |
| 58 | +} |
| 59 | +``` |
| 60 | + |
| 61 | +## Mapping: platform_function_definitions → NodeDefinition |
| 62 | + |
| 63 | +### Direct Field Mapping |
| 64 | + |
| 65 | +| DB Column / handler.json | NodeDefinition Field | Transformation | |
| 66 | +|---|---|---| |
| 67 | +| `name` | `name` | Direct copy | |
| 68 | +| `task_identifier` | `context` | The `task_identifier` doubles as the FBP context (dispatch address) | |
| 69 | +| `scope` | `category` | Groups functions in the visual palette | |
| 70 | +| `description` | `description` | Direct copy | |
| 71 | +| `required_secrets[]` | `props[]` | Each `(secret_name, required)` → `{ name, type: 'secret', required }` | |
| 72 | +| `required_configs[]` | `props[]` | Each `(config_name, required)` → `{ name, type: 'config', required }` | |
| 73 | + |
| 74 | +### Port Model |
| 75 | + |
| 76 | +Every function has an identical port signature — one JSON input, one JSON output: |
| 77 | + |
| 78 | +``` |
| 79 | +┌────────────────────────┐ |
| 80 | +│ send-email │ |
| 81 | +│ │ |
| 82 | +payload ──►│ handler(params, ctx) │──► result |
| 83 | +│ │ |
| 84 | +└────────────────────────┘ |
| 85 | +``` |
| 86 | + |
| 87 | +```typescript |
| 88 | +const toNodeDefinition = (fn: PlatformFunction): NodeDefinition => ({ |
| 89 | + context: fn.task_identifier, |
| 90 | + name: fn.name, |
| 91 | + category: fn.scope || 'default', |
| 92 | + description: fn.description, |
| 93 | + inputs: [ |
| 94 | + { name: 'payload', type: 'json', description: 'Job payload object' } |
| 95 | + ], |
| 96 | + outputs: [ |
| 97 | + { name: 'result', type: 'json', description: 'Handler return value' } |
| 98 | + ], |
| 99 | + props: [ |
| 100 | + ...fn.required_secrets.map(s => ({ |
| 101 | + name: s.name, |
| 102 | + type: 'secret', |
| 103 | + required: s.required, |
| 104 | + description: `Secret: ${s.name}` |
| 105 | + })), |
| 106 | + ...fn.required_configs.map(c => ({ |
| 107 | + name: c.name, |
| 108 | + type: 'config', |
| 109 | + required: c.required, |
| 110 | + description: `Config: ${c.name}` |
| 111 | + })) |
| 112 | + ] |
| 113 | +}); |
| 114 | +``` |
| 115 | + |
| 116 | +### Edge Semantics |
| 117 | + |
| 118 | +An edge connects one function's output to another's input: |
| 119 | + |
| 120 | +```typescript |
| 121 | +// "Pipe result of send-email into log-result" |
| 122 | +{ |
| 123 | + src: { node: 'send-email-1', port: 'result' }, |
| 124 | + dst: { node: 'log-result-1', port: 'payload' } |
| 125 | +} |
| 126 | +``` |
| 127 | + |
| 128 | +At runtime this means: when the job for `send-email-1` completes, its return value is used as the `payload` for a new job dispatched to `log-result-1`. |
| 129 | + |
| 130 | +### Job Payload Flow |
| 131 | + |
| 132 | +``` |
| 133 | +User triggers flow |
| 134 | + │ |
| 135 | + ▼ |
| 136 | +Job A inserted into app_jobs.jobs |
| 137 | + │ task_identifier = fn_a.task_identifier |
| 138 | + │ payload = user-provided or upstream result |
| 139 | + │ |
| 140 | + ▼ |
| 141 | +Worker picks up Job A → calls fn_a handler |
| 142 | + │ |
| 143 | + ▼ |
| 144 | +fn_a returns { complete: true, data: {...} } |
| 145 | + │ |
| 146 | + ▼ |
| 147 | +For each outgoing edge from fn_a: |
| 148 | + │ Insert new job with: |
| 149 | + │ task_identifier = edge.dst function's task_identifier |
| 150 | + │ payload = fn_a's result (or mapped subset) |
| 151 | + │ |
| 152 | + ▼ |
| 153 | +Job B inserted → worker picks up → fn_b handler runs → ... |
| 154 | +``` |
| 155 | + |
| 156 | +## Flow Graph (UI Model) |
| 157 | + |
| 158 | +A flow is persisted as an FBP `Graph`: |
| 159 | + |
| 160 | +```typescript |
| 161 | +interface Flow { |
| 162 | + name: string; |
| 163 | + nodes: Array<{ |
| 164 | + name: string; // instance id, e.g. "send-email-1" |
| 165 | + type: string; // function name, e.g. "send-email" |
| 166 | + meta?: { x: number; y: number }; |
| 167 | + props?: Array<{ name: string; value?: any }>; |
| 168 | + }>; |
| 169 | + edges: Array<{ |
| 170 | + src: { node: string; port: string }; |
| 171 | + dst: { node: string; port: string }; |
| 172 | + }>; |
| 173 | + definitions: NodeDefinition[]; // populated from GET /api/functions |
| 174 | +} |
| 175 | +``` |
| 176 | + |
| 177 | +### Persistence Strategy |
| 178 | + |
| 179 | +| Phase | Storage | Notes | |
| 180 | +|---|---|---| |
| 181 | +| MVP | `localStorage` | Immediate, no backend changes needed | |
| 182 | +| Production | DB table `constructive_infra_public.platform_flows` | Content-addressable via merkle hashing (aligned with `@fbp/spec` design) | |
| 183 | + |
| 184 | +## Future Extensions |
| 185 | + |
| 186 | +- **Typed ports**: Parse handler signatures to generate richer port schemas (beyond generic JSON) |
| 187 | +- **Conditional routing**: Use FBP channels (`edge.channel`) for error vs. success paths |
| 188 | +- **Subnets**: Compose flows of flows using FBP's nested graph model |
| 189 | +- **Live execution**: Trigger a flow and watch job status propagate through the graph in real-time |
| 190 | +- **Flow evaluation**: Use `@fbp/evaluator` to validate graphs before execution |
0 commit comments