Interactive distributed systems simulator to design, test, and understand architecture behavior frame by frame.
FlowFrame is a full-stack platform for visualizing distributed systems behavior through simulation rather than static diagrams. It combines a modern Next.js frontend with a high-performance Rust Axum backend for authentication, workspace management, diagram persistence, and recent activity feeds.
Primary use cases:
- Learn distributed systems with interactive scenarios
- Prototype architecture designs in a visual canvas
- Simulate request traversal and observe component-level behavior
- Persist and manage diagrams across workspaces
- Product demo: https://youtu.be/3Tezcle9FUY
- Rust backend repository: https://github.com/ndk123-web/flowframe-backend
- Frontend setup guide: Local Setup
- Backend integration notes: Backend Integration (Rust Axum)
- License: License
- YouTube demo: https://youtu.be/3Tezcle9FUY
Sample screenshots are available in the public folder:
FlowFrame is split into two repositories:
- Frontend (this repository): Next.js app, simulation UI, engine, and learning experience
- Backend (Rust + Axum): API, auth, workspace and diagram persistence
Backend repository:
FlowFrame includes a separate, purpose-built DSL for defining distributed architectures declaratively. This DSL is designed for system modeling, not general-purpose programming.
What you can express in .flow scripts:
- Infrastructure node definitions using
define <TYPE> <id> { ... } - Directed topology using
connect a -> b -> cor direct arrow chains - Runtime-related configs such as routes, endpoints, capacities, cache data, topics, and queue behavior
Supported high-level node types include:
- CLIENT
- SERVER
- GATEWAY
- LOADBALANCER
- REDIS
- POSTGRES
- MESSAGEQUEUE
- PUBSUB
The DSL compiler entry point is implemented in src/DSL/index.ts as compileDSL(sourceCode).
Compilation flow:
- Lexing: source text to tokens
- Parsing: tokens to AST
- Semantic analysis: AST validation and normalization
- Interpretation: semantic AST to graph output consumed by FlowFrame
Implementation modules:
- Lexer:
src/DSL/flow-interpreter/src/flowLexer/lexer.ts - Parser:
src/DSL/flow-interpreter/src/flowParser/parser.ts - Semantic analyzer:
src/DSL/flow-interpreter/src/flowSemantic/semantic - Interpreter:
src/DSL/flow-interpreter/src/flowInterpreter/interpreterFlow
Reference documentation:
src/DSL/README.md
Minimal example:
define CLIENT c1 {
label: "Mobile Client",
requests: [
{
endpoint: "/api/v1/posts",
allowedMethods: ["GET"],
key: "rohan"
}
]
}
define SERVER s1 {
label: "Posts Service",
acceptedEndpoints: [
{
endpoint: "/api/v1/posts",
allowedMethod: ["GET"]
}
]
}
connect c1 -> s1
- Interactive system-design canvas with reusable components
- Frame-based simulation engine with deterministic playback
- Animated request path visualization over graph edges
- Separate domain-specific language (DSL) for architecture definitions
- Scenario library for common distributed architecture patterns
- Authenticated workspaces and diagram persistence
- Recent diagrams feed and full CRUD operations
The frontend uses NEXT_PUBLIC_API_URL to call the Rust backend. If not set, it defaults to:
Client service modules calling backend APIs:
- src/services/authApi.ts
- src/services/workspaceApi.ts
- src/services/diagramApi.ts
Key API groups consumed by frontend:
- Auth: /api/auth/signup, /api/auth/signin, /api/auth/sync
- Workspaces: /api/workspaces
- Diagrams: /api/workspaces/:id/diagrams, /api/diagrams/recent
Frontend:
- Next.js 16
- React 19
- TypeScript
- Tailwind CSS 4
- React Flow (@xyflow/react)
- Framer Motion
- Firebase Auth
- Vitest
Backend (separate repo):
- Rust
- Axum
- Tokio
- MongoDB
- JWT-based auth middleware
app/ Next.js App Router pages
public/ Static assets and screenshots
src/components/ UI and visualization components
src/engine/ Simulation core and routing strategies
src/scenarios/ Scenario builders and registry map
src/services/ Frontend API clients for Rust backend
tests/ Unit tests
- Node.js 20+
- npm 10+
- Rust toolchain (for backend repository)
- MongoDB instance (for backend repository)
Clone and start backend from:
Typical backend environment values:
MONGODB_URI=mongodb://localhost:27017
DATABASE_NAME=flowframe
JWT_SECRET=change_me
HOST=0.0.0.0
PORT=8000
FRONTEND_URL=http://localhost:3000Then run backend:
cargo check
cargo runCreate .env.local in this repository:
NEXT_PUBLIC_API_URL=http://127.0.0.1:8000
NEXT_PUBLIC_APP_URL=http://localhost:3000
# Firebase client config
NEXT_PUBLIC_FIREBASE_API_KEY=your_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_domain
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_bucket
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDERID=your_sender_id
NEXT_PUBLIC_FIREBASE_APPID=your_app_id
NEXT_PUBLIC_FIREBASE_MEASUREMENTID=your_measurement_idInstall and run:
npm install
npm run devOpen:
- npm run dev: Start development server
- npm run build: Build for production
- npm run start: Start production build
- npm run lint: Run lint checks
- npm run test: Run test suite once
- npm run test:watch: Run tests in watch mode
- Home: /
- Dashboard: /dashboard
- Workspaces: /workspace
- Scenarios: /scenarios
- Learning Hub: /learn
- Docs: /docs
This frontend repository is licensed under PolyForm Noncommercial License 1.0.0.
- License file: LICENSE.txt
- Official text: https://polyformproject.org/licenses/noncommercial/1.0.0
Noncommercial usage is allowed under the license terms.




