# jyothish9988/ai-workflow-saas architecture

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

- Interactive diagram: https://gitdiagram.com/jyothish9988/ai-workflow-saas
- Repository: https://github.com/jyothish9988/ai-workflow-saas

## Overview

AWF is a self-hosted visual workflow automation product. Users configure connections, compose and save node graphs, execute them, and inspect run history; workflows can also run on cron schedules. The backend exposes authenticated APIs, persists workflow and execution state, and dispatches graph execution to node handlers and LLM services. The graph includes documented capabilities whose exact implementation paths or call sites were not sampled; those relationships are identified as README-supported rather than implying source inspection.

Main entry points: [`frontend/src/utils/api.js`](https://github.com/jyothish9988/ai-workflow-saas/blob/main/frontend/src/utils/api.js) (REST client), [`backend/app/services/execution_engine.py`](https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/services/execution_engine.py) (Execution engine), [`backend/app/api/workflow.py`](https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/api/workflow.py) (Workflow API), [`frontend/src/pages/workflow/WorkflowEditor.jsx`](https://github.com/jyothish9988/ai-workflow-saas/blob/main/frontend/src/pages/workflow/WorkflowEditor.jsx) (Workflow editor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_frontend_routes["App routes<br/>[App.jsx]"]
  node_workflow_editor["Workflow editor<br/>[WorkflowEditor.jsx]"]
  node_node_registry["Node registry<br/>[nodeRegistry.js]"]
  node_frontend_views["Run and schedule views<br/>[Executions.jsx]"]
  node_connection_views["Connection settings<br/>[AppIntegration.jsx]"]
  node_api_client["REST client<br/>[api.js]"]
end

subgraph group_api["Backend APIs"]
  node_auth_api["Auth API<br/>[auth.py]"]
  node_workflow_api["Workflow API<br/>[workflow.py]"]
  node_integration_api["Integration API"]
  node_llm_api["LLM connections API<br/>[llm_connections.py]"]
  node_schedule_api["Schedule API<br/>[schedule.py]"]
end

subgraph group_runtime["Workflow runtime"]
  node_execution_engine["Execution engine"]
  node_control_flow["Graph control flow<br/>[control_flow.py]"]
  node_node_handlers["Node handlers<br/>[node_handlers.py]"]
  node_gmail_nodes["Gmail nodes<br/>[gmail_nodes.py]"]
  node_run_manager["Background run manager<br/>[run_manager.py]"]
  node_schedule_service["Schedule service"]
end

subgraph group_connections["Connections and integrations"]
  node_llm_service["LLM service<br/>[llm_service.py]"]
  node_ollama_service["Ollama service<br/>[ollama_service.py]"]
  node_security["Authentication and encryption<br/>[security.py]"]
end

subgraph group_persistence["Persistence"]
  node_db_layer["Database session layer<br/>[db.py]"]
  node_workflow_records["Workflow and run records"]
end

node_user(("User"))
node_browser(("Browser client"))
node_postgres[("PostgreSQL")]
node_llm_providers{{"Hosted LLM providers"}}
node_external_apps{{"External app APIs"}}
node_ollama{{"Ollama server"}}

node_user -->|"uses"| node_browser
node_browser -->|"opens"| node_frontend_routes
node_frontend_routes -->|"routes to"| node_workflow_editor
node_user -->|"builds workflows"| node_workflow_editor
node_workflow_editor -->|"looks up nodes"| node_node_registry
node_workflow_editor -->|"saves and runs"| node_api_client
node_frontend_views -->|"requests run data"| node_api_client
node_connection_views -->|"manages connections"| node_api_client
node_api_client -->|"calls"| node_auth_api
node_api_client -->|"calls"| node_workflow_api
node_api_client -->|"calls"| node_integration_api
node_api_client -->|"calls"| node_llm_api
node_api_client -->|"calls"| node_schedule_api
node_workflow_api -->|"authenticates"| node_security
node_auth_api -->|"issues tokens"| node_security
node_integration_api -->|"encrypts secrets"| node_security
node_llm_api -->|"authenticates"| node_security
node_workflow_api -->|"starts runs"| node_run_manager
node_run_manager -->|"executes workflow"| node_execution_engine
node_execution_engine -->|"dispatches branches"| node_control_flow
node_execution_engine -->|"runs leaf nodes"| node_node_handlers
node_node_handlers -->|"delegates Gmail"| node_gmail_nodes
node_execution_engine -->|"records executions"| node_workflow_records
node_workflow_api -->|"manages workflows and runs"| node_workflow_records
node_schedule_api -.->|"manages schedules"| node_schedule_service
node_schedule_service -.->|"persists schedule state"| node_workflow_records
node_execution_engine -.->|"uses AI Agent"| node_llm_service
node_llm_service -.->|"sends prompts"| node_llm_providers
node_llm_service -->|"delegates local inference"| node_ollama_service
node_ollama_service -.->|"requests inference"| node_ollama
node_node_handlers -.->|"uses app nodes"| node_external_apps
node_db_layer -.->|"stores records"| node_postgres
node_workflow_records -->|"uses ORM base"| node_db_layer

click node_frontend_routes "https://github.com/jyothish9988/ai-workflow-saas/blob/main/frontend/src/App.jsx"
click node_workflow_editor "https://github.com/jyothish9988/ai-workflow-saas/blob/main/frontend/src/pages/workflow/WorkflowEditor.jsx"
click node_node_registry "https://github.com/jyothish9988/ai-workflow-saas/blob/main/frontend/src/pages/workflow/nodeRegistry.js"
click node_frontend_views "https://github.com/jyothish9988/ai-workflow-saas/blob/main/frontend/src/pages/Executions.jsx"
click node_connection_views "https://github.com/jyothish9988/ai-workflow-saas/blob/main/frontend/src/pages/settings/AppIntegration.jsx"
click node_api_client "https://github.com/jyothish9988/ai-workflow-saas/blob/main/frontend/src/utils/api.js"
click node_auth_api "https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/api/auth.py"
click node_workflow_api "https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/api/workflow.py"
click node_integration_api "https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/api/app_integrations.py"
click node_llm_api "https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/api/llm_connections.py"
click node_schedule_api "https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/api/schedule.py"
click node_execution_engine "https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/services/execution_engine.py"
click node_control_flow "https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/services/execution/control_flow.py"
click node_node_handlers "https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/services/node_handlers.py"
click node_gmail_nodes "https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/services/gmail_nodes.py"
click node_run_manager "https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/services/run_manager.py"
click node_schedule_service "https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/services/schedule_service.py"
click node_llm_service "https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/services/llm_service.py"
click node_ollama_service "https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/services/ollama_service.py"
click node_security "https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/core/security.py"
click node_db_layer "https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/database/db.py"
click node_workflow_records "https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/models/workflow_execution.py"

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_frontend_routes,node_workflow_editor,node_node_registry,node_frontend_views,node_connection_views,node_api_client,node_user,node_browser toneBlue
class node_auth_api,node_workflow_api,node_integration_api,node_llm_api,node_schedule_api,node_postgres toneAmber
class node_execution_engine,node_control_flow,node_node_handlers,node_gmail_nodes,node_run_manager,node_schedule_service,node_external_apps,node_ollama toneMint
class node_llm_service,node_ollama_service,node_security toneRose
class node_db_layer,node_workflow_records,node_llm_providers toneIndigo
```

## Components

### Web application

- [App routes](https://github.com/jyothish9988/ai-workflow-saas/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Workflow editor](https://github.com/jyothish9988/ai-workflow-saas/blob/main/frontend/src/pages/workflow/WorkflowEditor.jsx): `frontend/src/pages/workflow/WorkflowEditor.jsx`
- [Node registry](https://github.com/jyothish9988/ai-workflow-saas/blob/main/frontend/src/pages/workflow/nodeRegistry.js): `frontend/src/pages/workflow/nodeRegistry.js`
- [Run and schedule views](https://github.com/jyothish9988/ai-workflow-saas/blob/main/frontend/src/pages/Executions.jsx): `frontend/src/pages/Executions.jsx`
- [Connection settings](https://github.com/jyothish9988/ai-workflow-saas/blob/main/frontend/src/pages/settings/AppIntegration.jsx): `frontend/src/pages/settings/AppIntegration.jsx`
- [REST client](https://github.com/jyothish9988/ai-workflow-saas/blob/main/frontend/src/utils/api.js): `frontend/src/utils/api.js`

### Backend APIs

- [Auth API](https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Workflow API](https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/api/workflow.py): `backend/app/api/workflow.py`
- [Integration API](https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/api/app_integrations.py): `backend/app/api/app_integrations.py`
- [LLM connections API](https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/api/llm_connections.py): `backend/app/api/llm_connections.py`
- [Schedule API](https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/api/schedule.py): `backend/app/api/schedule.py`

### Workflow runtime

- [Execution engine](https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/services/execution_engine.py): `backend/app/services/execution_engine.py`
- [Graph control flow](https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/services/execution/control_flow.py): `backend/app/services/execution/control_flow.py`
- [Node handlers](https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/services/node_handlers.py): `backend/app/services/node_handlers.py`
- [Gmail nodes](https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/services/gmail_nodes.py): `backend/app/services/gmail_nodes.py`
- [Background run manager](https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/services/run_manager.py): `backend/app/services/run_manager.py`
- [Schedule service](https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/services/schedule_service.py): `backend/app/services/schedule_service.py`

### Connections and integrations

- [LLM service](https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/services/llm_service.py): `backend/app/services/llm_service.py`
- [Ollama service](https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/services/ollama_service.py): `backend/app/services/ollama_service.py`
- [Authentication and encryption](https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/core/security.py): `backend/app/core/security.py`

### Persistence

- [Database session layer](https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/database/db.py): `backend/app/database/db.py`
- [Workflow and run records](https://github.com/jyothish9988/ai-workflow-saas/blob/main/backend/app/models/workflow_execution.py): `backend/app/models/workflow_execution.py`

### Other components

- **User**
- **Browser client**
- **PostgreSQL**
- **Hosted LLM providers**
- **External app APIs**
- **Ollama server**

## Connections

- User → Browser client: uses (evidence: `README.md`)
- Browser client → App routes: opens (evidence: `frontend/src/App.jsx`)
- App routes → Workflow editor: routes to (evidence: `frontend/src/App.jsx`)
- User → Workflow editor: builds workflows (evidence: `README.md`)
- Workflow editor → Node registry: looks up nodes (evidence: `frontend/src/pages/workflow/WorkflowEditor.jsx`)
- Workflow editor → REST client: saves and runs (evidence: `frontend/src/pages/workflow/WorkflowEditor.jsx`)
- Run and schedule views → REST client: requests run data (evidence: `frontend/src/utils/api.js`)
- Connection settings → REST client: manages connections (evidence: `frontend/src/utils/api.js`)
- REST client → Auth API: calls (evidence: `frontend/src/utils/api.js`)
- REST client → Workflow API: calls (evidence: `frontend/src/utils/api.js`)
- REST client → Integration API: calls (evidence: `frontend/src/utils/api.js`)
- REST client → LLM connections API: calls (evidence: `frontend/src/utils/api.js`)
- REST client → Schedule API: calls (evidence: `frontend/src/utils/api.js`)
- Workflow API → Authentication and encryption: authenticates (evidence: `backend/app/api/workflow.py`)
- Auth API → Authentication and encryption: issues tokens (evidence: `backend/app/api/auth.py`)
- Integration API → Authentication and encryption: encrypts secrets (evidence: `backend/app/api/app_integrations.py`)
- LLM connections API → Authentication and encryption: authenticates (evidence: `backend/app/api/llm_connections.py`)
- Workflow API → Background run manager: starts runs (evidence: `backend/app/api/workflow.py`)
- Background run manager → Execution engine: executes workflow (evidence: `backend/app/services/run_manager.py`)
- Execution engine → Graph control flow: dispatches branches (evidence: `backend/app/services/execution_engine.py`)
- Execution engine → Node handlers: runs leaf nodes (evidence: `backend/app/services/execution_engine.py`)
- Node handlers → Gmail nodes: delegates Gmail (evidence: `backend/app/services/node_handlers.py`)
- Execution engine → Workflow and run records: records executions (evidence: `backend/app/services/execution_engine.py`)
- Workflow API → Workflow and run records: manages workflows and runs (evidence: `backend/app/api/workflow.py`)
- Schedule API → Schedule service: manages schedules
- Schedule service → Workflow and run records: persists schedule state
- Execution engine → LLM service: uses AI Agent (evidence: `README.md`)
- LLM service → Hosted LLM providers: sends prompts (evidence: `README.md`)
- LLM service → Ollama service: delegates local inference (evidence: `backend/app/services/llm_service.py`)
- Ollama service → Ollama server: requests inference (evidence: `README.md`)
- Node handlers → External app APIs: uses app nodes (evidence: `README.md`)
- Database session layer → PostgreSQL: stores records (evidence: `README.md`)
- Workflow and run records → Database session layer: uses ORM base (evidence: `backend/app/models/workflow_execution.py`)
