How abhinavkshabu/magnet-ai works
1. Repository shape
- This is a Next.js App Router application built as a workflow automation studio.
- The main product is a visual canvas for designing workflows, then executing them through a server-side orchestration layer.
- The repo is split into three major planes: UI/editor, API/backend, and execution/AI services.
2. Frontend composition
- The application shell lives in src/app, with the main entry at src/app/page.tsx and shared layout/styling in layout.tsx and globals.css.
- The core UI is a workflow canvas editor under src/components/canvas, including:
- the canvas itself,
- workflow node rendering,
- node connectors,
- a mini-map,
- AI-driven node suggestions.
- Side panels and dialogs in src/components/layout and src/components/modals handle node properties, connection properties, and trigger selection.
3. Client-side workflow state
- src/hooks/use-workflow.ts is the main client state boundary for workflow editing.
- It likely coordinates the canvas, selection state, node/edge updates, and persistence actions.
- This is the main interaction loop for the diagram: user edits workflow → local state updates → API persistence.
4. API boundary
- Server endpoints are organized under src/app/api.
- Major API groups are:
- workflows for workflow CRUD and execution triggering,
- executions for execution status and logs,
- vision/analyze for image/vision analysis,
- health for operational checks.
- This is the clean boundary between the interactive editor and backend services.
5. Workflow domain model
- Workflow-related data structures and persistence helpers live in src/lib/db/workflows.ts, with shared types in src/lib/types.ts and src/lib/db/types.ts.
- src/lib/workflow-data.ts and src/lib/utils.ts likely provide transformation/normalization logic used by both UI and backend.
- The architecture treats workflows as a persisted graph of nodes, edges, and node-specific configuration.
6. Execution engine
- The runtime for workflows is isolated in src/lib/execution.
- orchestrator.ts is the central coordination point for running a workflow end-to-end.
- executors/ contains node-type handlers, including:
- API,
- webhook,
- logic,
- LLM,
- vision,
- IoT,
- output.
- This indicates a pluggable executor pattern where each node type is handled by a specialized module.
7. Execution data flow
- The execution path is likely:
- workflow is selected in the UI,
- the execute endpoint is called,
- the orchestrator walks the workflow graph,
- executor modules perform node-specific work,
- execution state and logs are persisted,
- the UI reads back execution details from /executions/[id] and /logs.
- src/lib/db/executions.ts is the persistence layer for execution history and log retrieval.
8. AI subsystem
- AI features are isolated under src/ai, with Genkit setup in genkit.ts and flows in src/ai/flows.
- The two visible flows are:
- generate-workflow-from-prompt.ts
- suggest-next-nodes.ts
- This supports two product behaviors:
- generating a workflow from natural language,
- suggesting graph expansion while editing.
- The presence of provider icons for Gemini, OpenAI, and Groq suggests the system is designed to work across multiple model backends.
9. Vision analysis
- src/app/api/vision/analyze plus the vision executor indicate a dedicated vision-processing path.
- This is separate from generic LLM logic, so diagrammatically it should be shown as its own AI/service branch.
- The flow likely accepts images or visual inputs, analyzes them through an AI provider, and returns structured outputs usable inside workflows.
10. Persistence and server utilities
- Database access is abstracted behind src/lib/db, with helpers for workflows, executions, and users.
- src/lib/firebase-admin.ts suggests the backend uses Firebase Admin for server-side access to Firebase services, likely Firestore or related Firebase resources.
- This means persistence is not handled directly in UI components; all authoritative writes go through server utilities and API routes.
11. Shared UI system
- The repository uses a large set of reusable components in src/components/ui, which are standard design-system primitives.
- These are supporting infrastructure rather than core architecture, but they matter because the canvas, sidebars, dialogs, and execution views are all assembled from them.
- The UI is therefore a composition of a graph editor plus reusable form and dialog primitives.
12. Operational and deployment boundary
- apphosting.yaml and the Firebase Admin setup indicate the app is intended for Firebase-backed hosting/runtime integration.
- scripts/ contains setup and test scripts for API, execution, and vision paths, which suggests the project has multiple backend capabilities worth validating independently.
- Docs such as docs/EXECUTION-ENGINE.md and docs/backend-plan.md likely describe the runtime design and should be treated as authoritative references for deeper subsystem behavior.
13. Recommended diagram boundaries
- For an architecture diagram, the clearest boundary lines are:
- Browser/UI canvas editor
- Next.js API routes
- Execution orchestrator + executors
- AI/Genkit flows
- Firebase-backed persistence
- The key flows to draw are:
- workflow authoring and save,
- workflow execution and log retrieval,
- AI-assisted generation/suggestions,
- vision analysis as a specialized AI path.
Main entry points: workflows Workflow API · api API routes · executors Executors · canvas Canvas editor
Components 19
UI / Editor
Browser shell, canvas editor, and workflow editing panels.
- App shell · Root application entry, layout, and global styles.
src/app - Canvas editor · Main workflow canvas with nodes, connectors, minimap, and AI suggestions.
src/components/canvas - Property panels · Node, connection, and trigger editing surfaces.
src/components/layout - Workflow state · Primary client-side boundary for editing, selection, and persistence actions.
src/hooks/use-workflow.ts
API Layer
Next.js route handlers that expose workflows, execution, health, and vision endpoints.
- API routes · Server boundary for workflow CRUD, execution, vision, and health.
src/app/api - Workflow API · Create, read, update, and execute workflows.
src/app/api/workflows - Execution API · Execution status and log retrieval for run history.
src/app/api/executions - Vision API · Image analysis entrypoint used by the vision execution path.
src/app/api/vision/analyze - Health check · Operational readiness and liveness check.
src/app/api/health
Execution Engine
Workflow runtime and pluggable executors.
- Orchestrator · Central workflow runner that walks the graph and schedules node execution.
src/lib/execution/orchestrator.ts - Executors · Pluggable executor registry for node-specific runtime behavior.
src/lib/execution/executors - LLM executor · Handles language-model steps and prompt-based operations.
src/lib/execution/executors/llm.ts - Vision executor · Handles vision-processing nodes and structured image analysis.
src/lib/execution/executors/vision.ts - API executor · Calls external APIs as workflow steps.
src/lib/execution/executors/api.ts
AI Services
Genkit flows and provider-backed AI features.
- Genkit flows · Prompt-to-workflow generation and next-node suggestions.
src/ai/flows - AI runtime · Genkit configuration and provider integration.
src/ai/genkit.ts
Data / Persistence
Shared domain models and server-side database access.
- Workflow store · Workflow persistence helpers and data shaping.
src/lib/db/workflows.ts - Execution store · Execution history and log persistence.
src/lib/db/executions.ts - Domain models · Workflow, execution, and API data types plus normalization utilities.
src/lib/types.ts
Connections 24
- App shell → Canvas editor: renders · The app shell hosts the main canvas editor.
- App shell → Property panels: assembles · Shared layout composes the editing sidebars and dialogs.
- Canvas editor → Workflow state: updates state · Canvas interactions flow through the workflow state boundary.
- Property panels → Workflow state: edits · Property panels mutate the same workflow state.
- Workflow state → Workflow API: persists · Client edits are written through workflow API routes.
- API routes → Workflow API: hosts · Workflow CRUD and execute endpoints live under the API layer.
- API routes → Execution API: hosts · Execution status and logs are served from the API layer.
- API routes → Vision API: hosts · Vision analysis is exposed as a dedicated endpoint.
- API routes → Health check: hosts · Operational checks are exposed separately.
- Workflow API → Workflow store: reads/writes · Workflow endpoints persist and load workflow records.
- Workflow API → Domain models: uses · Workflow requests and responses use shared domain types.
- Workflow API → Orchestrator: starts runs · Execute requests hand off to the runtime orchestrator.
- Orchestrator → Executors: dispatches · The orchestrator selects a handler for each workflow node.
- Executors → LLM executor: includes · LLM nodes are handled by a specialized executor.
- Executors → Vision executor: includes · Vision nodes are handled by a specialized executor.
- Executors → API executor: includes · API-call nodes are handled by a specialized executor.
- Vision executor → Vision API: calls · Vision execution uses the vision analysis endpoint or backend path.
- Orchestrator → Execution store: records · Runs and logs are persisted during execution.
- Execution API → Execution store: reads · Execution detail pages fetch stored run data and logs.
- Genkit flows → AI runtime: uses · Flows run on the shared Genkit provider configuration.
- Canvas editor → Genkit flows: suggests/generates · The editor can request workflow generation or next-node suggestions.
- Genkit flows → Workflow store: may persist · Generated or refined workflows can be stored through the workflow data layer.
- Workflow store → Domain models: uses · Persistence helpers are built around shared workflow types.
- Execution store → Domain models: uses · Execution records are shaped by shared execution types.