# sitionix/forge-ai architecture

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

- Interactive diagram: https://gitdiagram.com/sitionix/forge-ai
- Repository: https://github.com/sitionix/forge-ai

## Overview

Forge AI is a local platform whose operator-facing workflow centers on managing projects and workflows, then executing agent workflows and observing their runs. Forge Agent owns workflow execution; Nexus provides typed platform-facing proxies, while the Console is the operator UI. Knowledge retrieval and Jarvis form a separate assistant capability. Remote access and MCP are additional Agent capabilities. The tree and excerpts support these subsystem boundaries, but not every internal call path; uncertain wiring is omitted.

Main entry points: [`services/forge-agent/api-rest/src/main/java/com/sitionix/forgeagent/api`](https://github.com/sitionix/forge-ai/tree/main/services/forge-agent/api-rest/src/main/java/com/sitionix/forgeagent/api) (Agent API), [`services/forge-agent/application/src/main/java/com/sitionix/forgeagent/application/usecase`](https://github.com/sitionix/forge-ai/tree/main/services/forge-agent/application/src/main/java/com/sitionix/forgeagent/application/usecase) (Agent use cases), [`services/forge-agent/application/src/main/java/com/sitionix/forgeagent/application/runtime/NodeRunWorker.java`](https://github.com/sitionix/forge-ai/blob/main/services/forge-agent/application/src/main/java/com/sitionix/forgeagent/application/runtime/NodeRunWorker.java) (Node execution), [`services/forge-knowledge/src/knowledge_service/knowledge_query_service.py`](https://github.com/sitionix/forge-ai/blob/main/services/forge-knowledge/src/knowledge_service/knowledge_query_service.py) (Knowledge retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator["Operator experience"]
  node_console["Forge Console"]
end

subgraph group_platform["Platform proxy"]
  node_nexus["Forge Nexus"]
  node_nexus_proxy["Agent proxy"]
end

subgraph group_agent["Agent workflows"]
  node_agent_api["Agent API"]
  node_agent_usecases["Agent use cases"]
  node_workflow_graph["Workflow validation"]
  node_workflow_runtime["Workflow coordinator"]
  node_node_worker["Node execution<br/>[NodeRunWorker.java]"]
  node_session_lease["Session leases"]
  node_run_events["Execution events"]
end

subgraph group_integrations["Agent integrations"]
  node_remote_access["Remote access"]
  node_mcp_gateway["MCP gateway"]
end

subgraph group_knowledge["Knowledge assistant"]
  node_knowledge["Knowledge retrieval"]
  node_flow_engine["Flow exploration"]
  node_knowledge_store[("Knowledge storage")]
  node_jarvis["Jarvis assistant<br/>[query_service.py]"]
  node_knowledge_gateway["Knowledge gateway<br/>[query_service.py]"]
end

node_operator(("Operator"))

node_operator -->|"uses"| node_console
node_console -->|"requests"| node_nexus
node_nexus -->|"routes"| node_nexus_proxy
node_nexus_proxy -->|"forwards typed requests"| node_agent_api
node_agent_api -->|"handles requests"| node_agent_usecases
node_agent_usecases -->|"validates workflow"| node_workflow_graph
node_agent_usecases -->|"coordinates execution"| node_workflow_runtime
node_workflow_runtime -->|"dispatches node runs"| node_node_worker
node_node_worker -->|"claims sessions"| node_session_lease
node_agent_api -->|"exposes events"| node_run_events
node_agent_api -->|"serves remote access"| node_remote_access
node_node_worker -.->|"accesses tools"| node_mcp_gateway
node_jarvis -->|"queries"| node_knowledge_gateway
node_knowledge_gateway -->|"sends query"| node_knowledge
node_knowledge -->|"assembles flows"| node_flow_engine
node_knowledge -->|"maintains storage"| node_knowledge_store

click node_console "https://github.com/sitionix/forge-ai/tree/main/services/forge-console"
click node_nexus "https://github.com/sitionix/forge-ai/tree/main/services/forge-nexus"
click node_nexus_proxy "https://github.com/sitionix/forge-ai/tree/main/services/forge-nexus/application/src/main/java/com/sitionix/forgeai/application/agentproxy"
click node_agent_api "https://github.com/sitionix/forge-ai/tree/main/services/forge-agent/api-rest/src/main/java/com/sitionix/forgeagent/api"
click node_agent_usecases "https://github.com/sitionix/forge-ai/tree/main/services/forge-agent/application/src/main/java/com/sitionix/forgeagent/application/usecase"
click node_workflow_graph "https://github.com/sitionix/forge-ai/tree/main/services/forge-agent/application/src/main/java/com/sitionix/forgeagent/application/graph"
click node_workflow_runtime "https://github.com/sitionix/forge-ai/blob/main/services/forge-agent/application/src/main/java/com/sitionix/forgeagent/application/runtime/WorkflowExecutionCoordinator.java"
click node_node_worker "https://github.com/sitionix/forge-ai/blob/main/services/forge-agent/application/src/main/java/com/sitionix/forgeagent/application/runtime/NodeRunWorker.java"
click node_session_lease "https://github.com/sitionix/forge-ai/blob/main/services/forge-agent/application/src/main/java/com/sitionix/forgeagent/application/runtime/AgentSessionLeaseService.java"
click node_run_events "https://github.com/sitionix/forge-ai/blob/main/services/forge-agent/api-rest/src/main/java/com/sitionix/forgeagent/api/AgentExecutionEventsController.java"
click node_remote_access "https://github.com/sitionix/forge-ai/tree/main/services/forge-agent/application/src/main/java/com/sitionix/forgeagent/application/remoteaccess"
click node_mcp_gateway "https://github.com/sitionix/forge-ai/blob/main/services/forge-agent/application/src/main/java/com/sitionix/forgeagent/application/mcp/McpGatewayService.java"
click node_knowledge "https://github.com/sitionix/forge-ai/blob/main/services/forge-knowledge/src/knowledge_service/knowledge_query_service.py"
click node_flow_engine "https://github.com/sitionix/forge-ai/blob/main/services/forge-knowledge/src/knowledge_service/local_flow_unit_engine.py"
click node_knowledge_store "https://github.com/sitionix/forge-ai/blob/main/services/forge-knowledge/src/knowledge_service/storage_operations.py"
click node_jarvis "https://github.com/sitionix/forge-ai/blob/main/services/forge-jarvis/src/jarvis_agent/query_service.py"
click node_knowledge_gateway "https://github.com/sitionix/forge-ai/blob/main/services/forge-jarvis/src/jarvis_agent/query_service.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_console toneBlue
class node_nexus,node_nexus_proxy toneAmber
class node_agent_api,node_agent_usecases,node_workflow_graph,node_workflow_runtime,node_node_worker,node_session_lease,node_run_events toneMint
class node_remote_access,node_mcp_gateway toneRose
class node_knowledge,node_flow_engine,node_knowledge_store,node_jarvis,node_knowledge_gateway,node_operator toneIndigo
```

## Components

### Operator experience

- [Forge Console](https://github.com/sitionix/forge-ai/tree/main/services/forge-console): `services/forge-console`

### Platform proxy

- [Forge Nexus](https://github.com/sitionix/forge-ai/tree/main/services/forge-nexus): `services/forge-nexus`
- [Agent proxy](https://github.com/sitionix/forge-ai/tree/main/services/forge-nexus/application/src/main/java/com/sitionix/forgeai/application/agentproxy): `services/forge-nexus/application/src/main/java/com/sitionix/forgeai/application/agentproxy`

### Agent workflows

- [Agent API](https://github.com/sitionix/forge-ai/tree/main/services/forge-agent/api-rest/src/main/java/com/sitionix/forgeagent/api): `services/forge-agent/api-rest/src/main/java/com/sitionix/forgeagent/api`
- [Agent use cases](https://github.com/sitionix/forge-ai/tree/main/services/forge-agent/application/src/main/java/com/sitionix/forgeagent/application/usecase): `services/forge-agent/application/src/main/java/com/sitionix/forgeagent/application/usecase`
- [Workflow validation](https://github.com/sitionix/forge-ai/tree/main/services/forge-agent/application/src/main/java/com/sitionix/forgeagent/application/graph): `services/forge-agent/application/src/main/java/com/sitionix/forgeagent/application/graph`
- [Workflow coordinator](https://github.com/sitionix/forge-ai/blob/main/services/forge-agent/application/src/main/java/com/sitionix/forgeagent/application/runtime/WorkflowExecutionCoordinator.java): `services/forge-agent/application/src/main/java/com/sitionix/forgeagent/application/runtime/WorkflowExecutionCoordinator.java`
- [Node execution](https://github.com/sitionix/forge-ai/blob/main/services/forge-agent/application/src/main/java/com/sitionix/forgeagent/application/runtime/NodeRunWorker.java): `services/forge-agent/application/src/main/java/com/sitionix/forgeagent/application/runtime/NodeRunWorker.java`
- [Session leases](https://github.com/sitionix/forge-ai/blob/main/services/forge-agent/application/src/main/java/com/sitionix/forgeagent/application/runtime/AgentSessionLeaseService.java): `services/forge-agent/application/src/main/java/com/sitionix/forgeagent/application/runtime/AgentSessionLeaseService.java`
- [Execution events](https://github.com/sitionix/forge-ai/blob/main/services/forge-agent/api-rest/src/main/java/com/sitionix/forgeagent/api/AgentExecutionEventsController.java): `services/forge-agent/api-rest/src/main/java/com/sitionix/forgeagent/api/AgentExecutionEventsController.java`

### Agent integrations

- [Remote access](https://github.com/sitionix/forge-ai/tree/main/services/forge-agent/application/src/main/java/com/sitionix/forgeagent/application/remoteaccess): `services/forge-agent/application/src/main/java/com/sitionix/forgeagent/application/remoteaccess`
- [MCP gateway](https://github.com/sitionix/forge-ai/blob/main/services/forge-agent/application/src/main/java/com/sitionix/forgeagent/application/mcp/McpGatewayService.java): `services/forge-agent/application/src/main/java/com/sitionix/forgeagent/application/mcp/McpGatewayService.java`

### Knowledge assistant

- [Knowledge retrieval](https://github.com/sitionix/forge-ai/blob/main/services/forge-knowledge/src/knowledge_service/knowledge_query_service.py): `services/forge-knowledge/src/knowledge_service/knowledge_query_service.py`
- [Flow exploration](https://github.com/sitionix/forge-ai/blob/main/services/forge-knowledge/src/knowledge_service/local_flow_unit_engine.py): `services/forge-knowledge/src/knowledge_service/local_flow_unit_engine.py`
- [Knowledge storage](https://github.com/sitionix/forge-ai/blob/main/services/forge-knowledge/src/knowledge_service/storage_operations.py): `services/forge-knowledge/src/knowledge_service/storage_operations.py`
- [Jarvis assistant](https://github.com/sitionix/forge-ai/blob/main/services/forge-jarvis/src/jarvis_agent/query_service.py): `services/forge-jarvis/src/jarvis_agent/query_service.py`
- [Knowledge gateway](https://github.com/sitionix/forge-ai/blob/main/services/forge-jarvis/src/jarvis_agent/query_service.py): `services/forge-jarvis/src/jarvis_agent/query_service.py`

### Other components

- **Operator**

## Connections

- Operator → Forge Console: uses
- Forge Console → Forge Nexus: requests
- Forge Nexus → Agent proxy: routes
- Agent proxy → Agent API: forwards typed requests
- Agent API → Agent use cases: handles requests
- Agent use cases → Workflow validation: validates workflow
- Agent use cases → Workflow coordinator: coordinates execution
- Workflow coordinator → Node execution: dispatches node runs
- Node execution → Session leases: claims sessions
- Agent API → Execution events: exposes events
- Agent API → Remote access: serves remote access
- Node execution → MCP gateway: accesses tools
- Jarvis assistant → Knowledge gateway: queries
- Knowledge gateway → Knowledge retrieval: sends query
- Knowledge retrieval → Flow exploration: assembles flows
- Knowledge retrieval → Knowledge storage: maintains storage