FlowFrame

FlowFrame

FlowFrame DSL Specifications v2.0.0

FlowFrame Architecture DSL Reference

FlowFrame Domain Specific Language (.flow) is a declarative infrastructure-as-code language built to design, compile, visualize, and simulate complex distributed systems and microservices architectures in real time.

System Simulation Rules & Runtime Behavior

Every topology in FlowFrame executes according to these 8 deterministic engine rules:

8 Engine Rules

01Cache-First Precedence (Redis + Postgres)

Data Access

When a Server node is connected to both a Redis cache and a PostgreSQL database, the engine always queries Redis first. If the key exists (CACHE_HIT), it returns immediately. Only on CACHE_MISS does the server forward to Postgres.

02Postgres TCP Connection Pool Limits

Database

Each server maintains a bounded connection pool defined by tcpConnectionsToPostgres. When concurrent requests exceed the pool size, excess queries enter a POSTGRES_POOL_WAIT queue state until active connections free up.

03Load Balancer Health Verification

Traffic Balancing

Load balancers inspect downstream server capacity. If all server nodes in a pool are exhausted, the load balancer rejects the request with a 503 Service Unavailable error.

04Endpoint & Method Matching Contracts

REST Routing

Servers validate that incoming requests match declared acceptedEndpoints and HTTP verbs (GET, POST, PUT, DELETE). Unmatched paths trigger 404 Not Found or 405 Method Not Allowed.

05Async Message Queue Ack

Publishing to a MessageQueue sends an immediate 202 Accepted ack back to the client while worker servers process messages in the background.

06PubSub Event Fan-Out

PubSub brokers broadcast published event messages to all subscribed servers registered with the matching topic channel.

07Valet Key Pre-Signed Uploads

When valet: true, the client first requests an upload token from the server, then streams data directly to cloud storage.

08Queue Overflow Controls

MessageQueue buffers that exceed queueSize adhere to BLOCK (producer waits) or REJECT (503 error).

Syntax & Token Rules

The DSL follows a concise declarative structure with loose keyword tolerances.

Node Declarations

1// Optional define keyword & flexible casing
2define CLIENT c1 {
3 label: "Mobile Client",
4 requests: [{ endpoint: "/api/v1/posts", key: "rohan" }]
5}
  • The define keyword is optional.
  • Node types can be uppercase or lowercase (e.g. CLIENT or client).
  • Identifiers are unique string names (e.g. c1, s1, lb1).

Connection Syntax

1// Option 1: Direct arrow chaining
2c1 -> gw1 -> lb1 -> s1
3
4// Option 2: Connect keyword
5connect lb1 -> s2
  • Chained connections (a -> b -> c) split into directed edges (a -> b and b -> c).
  • The connect keyword is optional.

Supported Node Schemas (8 Components)

FlowFrame supports 8 core infrastructure component types: clients, servers, gateways, balancers, caches, databases, message queues, and pubsub brokers.

1. CLIENT & 2. SERVER

Core Runtimes
1// Client definition with HTTP request payload
2define CLIENT c1 {
3 label: "Mobile Client",
4 requests: [
5 { endpoint: "/api/v1/orders", allowedMethods: ["POST"], key: "rohan" }
6 ]
7}
8
9// Server definition with capacity and endpoint configuration
10define SERVER s1 {
11 label: "Order Server Instance 1",
12 capacity: 50,
13 prefetchLimit: 10,
14 acceptedEndpoints: [
15 { endpoint: "/api/v1/orders", allowedMethod: ["POST"] }
16 ],
17 registeredTopics: ["post.created"]
18}

3. GATEWAY & 4. LOADBALANCER

Traffic Management
1// API Gateway with path-based LoadBalancer routing
2define GATEWAY gw1 {
3 label: "AWS API Gateway",
4 strategy: "ROUND_ROBIN",
5 routes: [
6 { path: "/api/v1/orders", target: lb1 },
7 { path: "/api/v1/posts", target: s3 }
8 ]
9}
10
11// Load Balancer with Round-Robin strategy
12define LOADBALANCER lb1 {
13 label: "Order Service LoadBalancer",
14 strategy: "ROUND_ROBIN"
15}

5. REDIS & 6. POSTGRES

State & Storage
1// Redis in-memory cache pre-populated data
2define REDIS r1 {
3 label: "Redis Cache 1",
4 data: [{ key: "rohan", value: "cached data for rohan" }]
5}
6
7// PostgreSQL database relational table data
8define POSTGRES db1 {
9 label: "Postgres Database 1",
10 table: "users",
11 data: [{ key: "rohan", value: "db record data" }]
12}

7. MESSAGEQUEUE & 8. PUBSUB

Asynchronous Messaging
1// Asynchronous RabbitMQ message queue broker
2define MESSAGEQUEUE mq1 {
3 label: "Post Queue",
4 processingType: "FIFO",
5 queueSize: 50,
6 overflowBehavior: "REJECT"
7}
8
9// Redis PubSub event broker for broadcast channels
10define PUBSUB postPubsub {
11 label: "PostPubSub 1",
12 topic: "post.created"
13}

Flagship Enterprise Microservices Blueprint

Full-scale microservices system with API Gateway, 2 Load Balancers, 7 Servers, RabbitMQ Queue, PubSub, Redis, and PostgreSQL.

1// ==========================================
2// FLOWFRAME ARCHITECTURE DSL v2.0.0
3// Flagship Enterprise Microservices Blueprint
4// ==========================================
5
6// 1. End-User Mobile Client Definition
7define CLIENT c1 {
8 label: "Mobile Client",
9 requests: [
10 {
11 endpoint: "/api/v1/orders",
12 allowedMethods: ["POST"],
13 key: "rohan"
14 },
15 {
16 endpoint: "/api/v1/orders",
17 allowedMethods: ["POST"],
18 key: "rohan"
19 },
20 {
21 endpoint: "/api/v1/users",
22 allowedMethods: ["POST"],
23 key: "rohan",
24 body: {
25 topic: "post.created"
26 }
27 },
28 {
29 endpoint: "/api/v1/users",
30 allowedMethods: ["POST"],
31 key: "rohan",
32 body: {
33 topic: "post.created"
34 }
35 },
36 {
37 endpoint: "/api/v1/posts",
38 allowedMethods: ["POST"],
39 key: "rohan"
40 }
41 ]
42}
43
44// 2. Central API Gateway Routing Definition
45define GATEWAY gw1 {
46 label: "AWS API Gateway",
47 strategy: "ROUND_ROBIN",
48 routes: [
49 {
50 path: "/api/v1/orders",
51 target: lb1
52 },
53 {
54 path: "/api/v1/posts",
55 target: s3
56 },
57 {
58 path: "/api/v1/users",
59 target: lb2
60 }
61 ]
62}
63
64// 3. Service Cluster Load Balancers
65define LOADBALANCER lb1 {
66 label: "Order Service LoadBalancer",
67 strategy: "ROUND_ROBIN"
68}
69
70define LOADBALANCER lb2 {
71 label: "User Service LoadBalancer",
72 strategy: "ROUND_ROBIN"
73}
74
75// 4. Order Microservice Application Servers
76define SERVER s1 {
77 label: "Order Server Instance 1",
78 capacity: 50,
79 acceptedEndpoints: [
80 {
81 endpoint: "/api/v1/orders",
82 allowedMethod: ["POST"]
83 }
84 ]
85}
86
87define SERVER s2 {
88 label: "Order Server Instance 2",
89 capacity: 50,
90 acceptedEndpoints: [
91 {
92 endpoint: "/api/v1/orders",
93 allowedMethod: ["POST"]
94 }
95 ]
96}
97
98// 5. Post & User Microservice Servers
99define SERVER s3 {
100 label: "Post Service Instance",
101 capacity: 50,
102 acceptedEndpoints: [
103 {
104 endpoint: "/api/v1/posts",
105 allowedMethod: ["POST"]
106 }
107 ]
108}
109
110define SERVER s4 {
111 label: "User Auth Instance 1",
112 capacity: 50,
113 acceptedEndpoints: [
114 {
115 endpoint: "/api/v1/users",
116 allowedMethod: ["POST"]
117 }
118 ]
119}
120
121define SERVER s5 {
122 label: "User Auth Instance 2",
123 capacity: 50,
124 acceptedEndpoints: [
125 {
126 endpoint: "/api/v1/users",
127 allowedMethod: ["POST"]
128 }
129 ]
130}
131
132// 6. Asynchronous Messaging & Queue Pipelines
133define MESSAGEQUEUE mq1 {
134 label: "Post Processing RabbitMQ",
135 processingType: "FIFO",
136 queueSize: 100,
137 overflowBehavior: "REJECT"
138}
139
140define PUBSUB postPubsub {
141 label: "User Events PubSub Broker",
142 topic: "post.created"
143}
144
145// 7. Databases & Caching Layer
146define POSTGRES db1 {
147 label: "Order PostgreSQL Cluster",
148 table: "orders",
149 data: [
150 { key: "rohan", value: "orders_database_record_payload" }
151 ]
152}
153
154define REDIS r1 {
155 label: "Order Redis Cache",
156 data: [
157 { key: "rohan", value: "order_cached_hit" }
158 ]
159}
160
161define POSTGRES db2 {
162 label: "Analytics PostgreSQL Database",
163 table: "analytics",
164 data: [
165 { key: "rohan", value: "analytics_database_record_payload" }
166 ]
167}
168
169define REDIS r2 {
170 label: "Analytics Redis Cache",
171 data: [
172 { key: "rohan", value: "analytics_cached_hit" }
173 ]
174}
175
176// 8. Background Workers & Consumers
177define SERVER producerPostQueue1 {
178 label: "Post Queue Consumer 1",
179 capacity: 100,
180 acceptedEndpoints: [
181 {
182 endpoint: "/api/v1/posts",
183 allowedMethod: ["GET", "POST"]
184 }
185 ],
186 prefetchLimit: 10
187}
188
189define SERVER producerPostQueue2 {
190 label: "Post Queue Consumer 2",
191 capacity: 100,
192 acceptedEndpoints: [
193 {
194 endpoint: "/api/v1/posts",
195 allowedMethod: ["GET", "POST"]
196 }
197 ],
198 prefetchLimit: 10
199}
200
201define SERVER pubsubConsumer1 {
202 label: "PubSub Consumer 1",
203 capacity: 100,
204 acceptedEndpoints: [
205 {
206 endpoint: "/api/v1/posts",
207 allowedMethod: ["GET", "POST"]
208 }
209 ],
210 registeredTopics: ["post.created"]
211}
212
213define SERVER pubsubConsumer2 {
214 label: "PubSub Consumer 2",
215 capacity: 100,
216 acceptedEndpoints: [
217 {
218 endpoint: "/api/v1/posts",
219 allowedMethod: ["GET", "POST"]
220 }
221 ],
222 registeredTopics: ["post.created"]
223}
224
225// ==========================================
226// TOPOLOGY NETWORK CONNECTIONS & DATA FLOWS
227// ==========================================
228
229// Client to API Gateway and Load Balancers
230connect c1 -> gw1 -> lb1 -> s1
231connect lb1 -> s2
232connect gw1 -> s3
233connect gw1 -> lb2
234connect lb2 -> s4
235connect lb2 -> s5
236
237// Order Servers to Message Queue & Consumers
238s1 -> mq1
239s2 -> mq1
240mq1 -> producerPostQueue1
241mq1 -> producerPostQueue2
242producerPostQueue1 -> db1
243producerPostQueue1 -> r1
244producerPostQueue2 -> db1
245producerPostQueue2 -> r1
246
247// User Servers to PubSub Broker & Subscribers
248s4 -> postPubsub
249s5 -> postPubsub
250postPubsub -> pubsubConsumer2
251postPubsub -> pubsubConsumer1
252pubsubConsumer1 -> r2
253pubsubConsumer1 -> db2
254pubsubConsumer2 -> db2
255pubsubConsumer2 -> r2

Video Deep Dive — Event-Driven Architecture from Scratch

Watch the full-stack walkthrough building and simulating this production-grade microservices system.

Error Diagnostics & Open Source License

The FlowFrame compiler performs strict Lexer, Parser, and Semantic checks prior to visual rendering or simulation execution.

Syntax Errors

Catches unexpected tokens, unclosed braces, or missing identifiers.

Duplicate Checks

Prevents re-declaration of duplicate node identifier names.

Strict Schema Rules

Enforces valid property names per node type using ALLOWED_VARIABLES.

PolyForm Noncommercial License 1.0.0

ndk123-web/flowframe

FlowFrame source code is available for educational, personal, and non-commercial research purposes under the PolyForm Noncommercial License 1.0.0. Feel free to inspect the Rust backend, TypeScript compiler pipeline, and simulation runtime.