# abhinavkshabu/magnet-ai architecture

> Architecture diagram of the GitHub repository abhinavkshabu/magnet-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abhinavkshabu/magnet-ai
- Repository: https://github.com/abhinavkshabu/magnet-ai

## Overview

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: [`src/app/api/workflows`](https://github.com/abhinavkshabu/magnet-ai/tree/main/src/app/api/workflows) (Workflow API), [`src/app/api`](https://github.com/abhinavkshabu/magnet-ai/tree/main/src/app/api) (API routes), [`src/lib/execution/executors`](https://github.com/abhinavkshabu/magnet-ai/tree/main/src/lib/execution/executors) (Executors), [`src/components/canvas`](https://github.com/abhinavkshabu/magnet-ai/tree/main/src/components/canvas) (Canvas editor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI / Editor"]
  node_app_shell["App shell<br/>Next.js app"]
  node_canvas_editor["Canvas editor<br/>workflow UI"]
  node_side_panels["Property panels<br/>editor panels"]
  node_workflow_hook(("Workflow state<br/>client state<br/>[use-workflow.ts]"))
end

subgraph group_api["API Layer"]
  node_api_routes["API routes<br/>route handlers"]
  node_workflow_api["Workflow API<br/>workflow endpoints"]
  node_execution_api["Execution API<br/>execution endpoints"]
  node_vision_api["Vision API<br/>vision endpoint"]
  node_health_api(("Health check<br/>ops endpoint"))
end

subgraph group_exec["Execution Engine"]
  node_orchestrator["Orchestrator<br/>runtime coordinator<br/>[orchestrator.ts]"]
  node_executor_index["Executors<br/>node handlers"]
  node_executor_llm(("LLM executor<br/>node executor<br/>[llm.ts]"))
  node_executor_vision(("Vision executor<br/>node executor<br/>[vision.ts]"))
  node_executor_api(("API executor<br/>node executor<br/>[api.ts]"))
end

subgraph group_ai["AI Services"]
  node_genkit_flows["Genkit flows<br/>AI flows"]
  node_ai_setup(("AI runtime<br/>genkit setup<br/>[genkit.ts]"))
end

subgraph group_data["Data / Persistence"]
  node_workflow_db[("Workflow store<br/>persistence<br/>[workflows.ts]")]
  node_execution_db[("Execution store<br/>persistence<br/>[executions.ts]")]
  node_shared_models["Domain models<br/>shared types<br/>[types.ts]"]
end

node_app_shell -->|"renders"| node_canvas_editor
node_app_shell -->|"assembles"| node_side_panels
node_canvas_editor -->|"updates state"| node_workflow_hook
node_side_panels -->|"edits"| node_workflow_hook
node_workflow_hook -->|"persists"| node_workflow_api
node_api_routes -->|"hosts"| node_workflow_api
node_api_routes -->|"hosts"| node_execution_api
node_api_routes -->|"hosts"| node_vision_api
node_api_routes -->|"hosts"| node_health_api
node_workflow_api -->|"reads/writes"| node_workflow_db
node_workflow_api -->|"uses"| node_shared_models
node_workflow_api -->|"starts runs"| node_orchestrator
node_orchestrator -->|"dispatches"| node_executor_index
node_executor_index -->|"includes"| node_executor_llm
node_executor_index -->|"includes"| node_executor_vision
node_executor_index -->|"includes"| node_executor_api
node_executor_vision -->|"calls"| node_vision_api
node_orchestrator -->|"records"| node_execution_db
node_execution_api -->|"reads"| node_execution_db
node_genkit_flows -->|"uses"| node_ai_setup
node_canvas_editor -->|"suggests/generates"| node_genkit_flows
node_genkit_flows -.->|"may persist"| node_workflow_db
node_workflow_db -->|"uses"| node_shared_models
node_execution_db -->|"uses"| node_shared_models

click node_app_shell "https://github.com/abhinavkshabu/magnet-ai/tree/main/src/app"
click node_canvas_editor "https://github.com/abhinavkshabu/magnet-ai/tree/main/src/components/canvas"
click node_side_panels "https://github.com/abhinavkshabu/magnet-ai/tree/main/src/components/layout"
click node_workflow_hook "https://github.com/abhinavkshabu/magnet-ai/blob/main/src/hooks/use-workflow.ts"
click node_api_routes "https://github.com/abhinavkshabu/magnet-ai/tree/main/src/app/api"
click node_workflow_api "https://github.com/abhinavkshabu/magnet-ai/tree/main/src/app/api/workflows"
click node_execution_api "https://github.com/abhinavkshabu/magnet-ai/tree/main/src/app/api/executions"
click node_vision_api "https://github.com/abhinavkshabu/magnet-ai/tree/main/src/app/api/vision/analyze"
click node_health_api "https://github.com/abhinavkshabu/magnet-ai/tree/main/src/app/api/health"
click node_orchestrator "https://github.com/abhinavkshabu/magnet-ai/blob/main/src/lib/execution/orchestrator.ts"
click node_executor_index "https://github.com/abhinavkshabu/magnet-ai/tree/main/src/lib/execution/executors"
click node_executor_llm "https://github.com/abhinavkshabu/magnet-ai/blob/main/src/lib/execution/executors/llm.ts"
click node_executor_vision "https://github.com/abhinavkshabu/magnet-ai/blob/main/src/lib/execution/executors/vision.ts"
click node_executor_api "https://github.com/abhinavkshabu/magnet-ai/blob/main/src/lib/execution/executors/api.ts"
click node_genkit_flows "https://github.com/abhinavkshabu/magnet-ai/tree/main/src/ai/flows"
click node_ai_setup "https://github.com/abhinavkshabu/magnet-ai/blob/main/src/ai/genkit.ts"
click node_workflow_db "https://github.com/abhinavkshabu/magnet-ai/blob/main/src/lib/db/workflows.ts"
click node_execution_db "https://github.com/abhinavkshabu/magnet-ai/blob/main/src/lib/db/executions.ts"
click node_shared_models "https://github.com/abhinavkshabu/magnet-ai/blob/main/src/lib/types.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_shell,node_canvas_editor,node_side_panels,node_workflow_hook toneBlue
class node_api_routes,node_workflow_api,node_execution_api,node_vision_api,node_health_api toneAmber
class node_orchestrator,node_executor_index,node_executor_llm,node_executor_vision,node_executor_api toneMint
class node_genkit_flows,node_ai_setup toneRose
class node_workflow_db,node_execution_db,node_shared_models toneIndigo
```

## Components

### UI / Editor

Browser shell, canvas editor, and workflow editing panels.

- [App shell](https://github.com/abhinavkshabu/magnet-ai/tree/main/src/app): Next.js app · Root application entry, layout, and global styles. · `src/app`
- [Canvas editor](https://github.com/abhinavkshabu/magnet-ai/tree/main/src/components/canvas): workflow UI · Main workflow canvas with nodes, connectors, minimap, and AI suggestions. · `src/components/canvas`
- [Property panels](https://github.com/abhinavkshabu/magnet-ai/tree/main/src/components/layout): editor panels · Node, connection, and trigger editing surfaces. · `src/components/layout`
- [Workflow state](https://github.com/abhinavkshabu/magnet-ai/blob/main/src/hooks/use-workflow.ts): client 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](https://github.com/abhinavkshabu/magnet-ai/tree/main/src/app/api): route handlers · Server boundary for workflow CRUD, execution, vision, and health. · `src/app/api`
- [Workflow API](https://github.com/abhinavkshabu/magnet-ai/tree/main/src/app/api/workflows): workflow endpoints · Create, read, update, and execute workflows. · `src/app/api/workflows`
- [Execution API](https://github.com/abhinavkshabu/magnet-ai/tree/main/src/app/api/executions): execution endpoints · Execution status and log retrieval for run history. · `src/app/api/executions`
- [Vision API](https://github.com/abhinavkshabu/magnet-ai/tree/main/src/app/api/vision/analyze): vision endpoint · Image analysis entrypoint used by the vision execution path. · `src/app/api/vision/analyze`
- [Health check](https://github.com/abhinavkshabu/magnet-ai/tree/main/src/app/api/health): ops endpoint · Operational readiness and liveness check. · `src/app/api/health`

### Execution Engine

Workflow runtime and pluggable executors.

- [Orchestrator](https://github.com/abhinavkshabu/magnet-ai/blob/main/src/lib/execution/orchestrator.ts): runtime coordinator · Central workflow runner that walks the graph and schedules node execution. · `src/lib/execution/orchestrator.ts`
- [Executors](https://github.com/abhinavkshabu/magnet-ai/tree/main/src/lib/execution/executors): node handlers · Pluggable executor registry for node-specific runtime behavior. · `src/lib/execution/executors`
- [LLM executor](https://github.com/abhinavkshabu/magnet-ai/blob/main/src/lib/execution/executors/llm.ts): node executor · Handles language-model steps and prompt-based operations. · `src/lib/execution/executors/llm.ts`
- [Vision executor](https://github.com/abhinavkshabu/magnet-ai/blob/main/src/lib/execution/executors/vision.ts): node executor · Handles vision-processing nodes and structured image analysis. · `src/lib/execution/executors/vision.ts`
- [API executor](https://github.com/abhinavkshabu/magnet-ai/blob/main/src/lib/execution/executors/api.ts): node executor · Calls external APIs as workflow steps. · `src/lib/execution/executors/api.ts`

### AI Services

Genkit flows and provider-backed AI features.

- [Genkit flows](https://github.com/abhinavkshabu/magnet-ai/tree/main/src/ai/flows): AI flows · Prompt-to-workflow generation and next-node suggestions. · `src/ai/flows`
- [AI runtime](https://github.com/abhinavkshabu/magnet-ai/blob/main/src/ai/genkit.ts): genkit setup · Genkit configuration and provider integration. · `src/ai/genkit.ts`

### Data / Persistence

Shared domain models and server-side database access.

- [Workflow store](https://github.com/abhinavkshabu/magnet-ai/blob/main/src/lib/db/workflows.ts): persistence · Workflow persistence helpers and data shaping. · `src/lib/db/workflows.ts`
- [Execution store](https://github.com/abhinavkshabu/magnet-ai/blob/main/src/lib/db/executions.ts): persistence · Execution history and log persistence. · `src/lib/db/executions.ts`
- [Domain models](https://github.com/abhinavkshabu/magnet-ai/blob/main/src/lib/types.ts): shared types · Workflow, execution, and API data types plus normalization utilities. · `src/lib/types.ts`

## Connections

- 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.
