# lnyo-cly/ai4j architecture

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

- Interactive diagram: https://gitdiagram.com/lnyo-cly/ai4j
- Repository: https://github.com/lnyo-cly/ai4j

## Overview

ai4j is a JDK 8+ Java AI-agent SDK, not a single end-user application. A typical request enters an Agent, runs through a selected execution mode, uses model and tool integrations, and returns a result; the SDK also offers distinct RAG ingestion/retrieval, coding-agent, workflow, and long-running harness capabilities. The README supports the capability-level relationships shown here; sampled source confirms details for RAG ingestion/retrieval and FlowGram runtime, but not every integration’s wiring.

Main entry points: [`ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/runtime/ReActRuntime.java`](https://github.com/lnyo-cly/ai4j/blob/main/ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/runtime/ReActRuntime.java) (Execution modes), [`ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/Agent.java`](https://github.com/lnyo-cly/ai4j/blob/main/ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/Agent.java) (Agent API), [`ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/tool/RoutingToolExecutor.java`](https://github.com/lnyo-cly/ai4j/blob/main/ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/tool/RoutingToolExecutor.java) (Tool execution), [`ai4j-coding/src/main/java/io/github/lnyocly/ai4j/coding/loop/CodingAgentLoopController.java`](https://github.com/lnyo-cly/ai4j/blob/main/ai4j-coding/src/main/java/io/github/lnyocly/ai4j/coding/loop/CodingAgentLoopController.java) (Coding agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent runtime"]
  node_agent_api["Agent API<br/>[Agent.java]"]
  node_agent_runtime["Execution modes<br/>[ReActRuntime.java]"]
  node_model_clients["Model clients"]
  node_agent_tools["Tool execution"]
  node_memory["Agent memory<br/>[AgentMemory.java]"]
  node_permissions["Permission checks"]
  node_agent_result["Agent result<br/>[AgentResult.java]"]
end

subgraph group_knowledge["Knowledge and retrieval"]
  node_rag_ingest["Document ingestion"]
  node_embedding["Embedding services"]
  node_vector_store[("Vector stores")]
  node_rag_query["RAG retrieval"]
end

subgraph group_coding["Coding and tasks"]
  node_coding_agent["Coding agent"]
  node_workspace["Workspace files"]
  node_coding_tasks["Coding tasks"]
  node_harness["Long-task harness"]
end

subgraph group_integrations["Integrations and workflows"]
  node_flowgram_api["FlowGram API"]
  node_flowgram_runtime["FlowGram runtime"]
  node_a2a["A2A protocol<br/>[A2AClient.java]"]
  node_mcp["MCP server"]
end

node_user(("Application caller"))
node_model_provider{{"Model providers"}}

node_user -->|"submits request"| node_agent_api
node_agent_api -->|"runs agent"| node_agent_runtime
node_agent_runtime -->|"requests completion"| node_model_clients
node_model_clients -->|"calls provider"| node_model_provider
node_agent_runtime -->|"dispatches tools"| node_agent_tools
node_agent_runtime -->|"uses memory"| node_memory
node_agent_tools -.->|"checks approval"| node_permissions
node_agent_runtime -.->|"returns result"| node_agent_result
node_rag_ingest -->|"creates embeddings"| node_embedding
node_rag_ingest -->|"upserts vectors"| node_vector_store
node_rag_query -.->|"retrieves vectors"| node_vector_store
node_agent_tools -.->|"offers RAG tool"| node_rag_query
node_user -->|"starts coding task"| node_coding_agent
node_coding_agent -->|"works on files"| node_workspace
node_coding_agent -.->|"manages task"| node_coding_tasks
node_harness -.->|"governs long tasks"| node_coding_tasks
node_user -->|"submits workflow"| node_flowgram_api
node_flowgram_api -.->|"delegates task"| node_flowgram_runtime
node_agent_api -->|"exposes collaboration"| node_a2a
node_agent_api -->|"exposes capabilities"| node_mcp

click node_agent_api "https://github.com/lnyo-cly/ai4j/blob/main/ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/Agent.java"
click node_agent_runtime "https://github.com/lnyo-cly/ai4j/blob/main/ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/runtime/ReActRuntime.java"
click node_model_clients "https://github.com/lnyo-cly/ai4j/blob/main/ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/model/AgentModelClient.java"
click node_agent_tools "https://github.com/lnyo-cly/ai4j/blob/main/ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/tool/RoutingToolExecutor.java"
click node_memory "https://github.com/lnyo-cly/ai4j/blob/main/ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/memory/AgentMemory.java"
click node_permissions "https://github.com/lnyo-cly/ai4j/blob/main/ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/permission/AgentPermissionToolExecutor.java"
click node_agent_result "https://github.com/lnyo-cly/ai4j/blob/main/ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/AgentResult.java"
click node_rag_ingest "https://github.com/lnyo-cly/ai4j/blob/main/ai4j/src/main/java/io/github/lnyocly/ai4j/rag/ingestion/IngestionPipeline.java"
click node_embedding "https://github.com/lnyo-cly/ai4j/blob/main/ai4j/src/main/java/io/github/lnyocly/ai4j/platform/openai/embedding/OpenAiEmbeddingService.java"
click node_vector_store "https://github.com/lnyo-cly/ai4j/blob/main/ai4j/src/main/java/io/github/lnyocly/ai4j/vector/service/PineconeService.java"
click node_rag_query "https://github.com/lnyo-cly/ai4j/blob/main/ai4j/src/main/java/io/github/lnyocly/ai4j/rag/DefaultRagService.java"
click node_coding_agent "https://github.com/lnyo-cly/ai4j/blob/main/ai4j-coding/src/main/java/io/github/lnyocly/ai4j/coding/loop/CodingAgentLoopController.java"
click node_workspace "https://github.com/lnyo-cly/ai4j/blob/main/ai4j-coding/src/main/java/io/github/lnyocly/ai4j/coding/workspace/LocalWorkspaceFileService.java"
click node_coding_tasks "https://github.com/lnyo-cly/ai4j/blob/main/ai4j-coding/src/main/java/io/github/lnyocly/ai4j/coding/task/CodingTaskManager.java"
click node_harness "https://github.com/lnyo-cly/ai4j/blob/main/ai4j-harness/src/main/java/io/github/lnyocly/ai4j/harness/HarnessTaskSpec.java"
click node_flowgram_api "https://github.com/lnyo-cly/ai4j/blob/main/ai4j-flowgram-spring-boot-starter/src/main/java/io/github/lnyocly/ai4j/flowgram/springboot/controller/FlowGramTaskController.java"
click node_flowgram_runtime "https://github.com/lnyo-cly/ai4j/blob/main/ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/flowgram/FlowGramRuntimeService.java"
click node_a2a "https://github.com/lnyo-cly/ai4j/blob/main/ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/a2a/A2AClient.java"
click node_mcp "https://github.com/lnyo-cly/ai4j/blob/main/ai4j/src/main/java/io/github/lnyocly/ai4j/mcp/server/McpServerEngine.java"

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_agent_api,node_agent_runtime,node_model_clients,node_agent_tools,node_memory,node_permissions,node_agent_result toneBlue
class node_rag_ingest,node_embedding,node_vector_store,node_rag_query toneAmber
class node_coding_agent,node_workspace,node_coding_tasks,node_harness toneMint
class node_flowgram_api,node_flowgram_runtime,node_a2a,node_mcp toneRose
class node_user,node_model_provider toneIndigo
```

## Components

### Agent runtime

- [Agent API](https://github.com/lnyo-cly/ai4j/blob/main/ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/Agent.java): `ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/Agent.java`
- [Execution modes](https://github.com/lnyo-cly/ai4j/blob/main/ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/runtime/ReActRuntime.java): `ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/runtime/ReActRuntime.java`
- [Model clients](https://github.com/lnyo-cly/ai4j/blob/main/ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/model/AgentModelClient.java): `ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/model/AgentModelClient.java`
- [Tool execution](https://github.com/lnyo-cly/ai4j/blob/main/ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/tool/RoutingToolExecutor.java): `ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/tool/RoutingToolExecutor.java`
- [Agent memory](https://github.com/lnyo-cly/ai4j/blob/main/ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/memory/AgentMemory.java): `ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/memory/AgentMemory.java`
- [Permission checks](https://github.com/lnyo-cly/ai4j/blob/main/ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/permission/AgentPermissionToolExecutor.java): `ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/permission/AgentPermissionToolExecutor.java`
- [Agent result](https://github.com/lnyo-cly/ai4j/blob/main/ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/AgentResult.java): `ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/AgentResult.java`

### Knowledge and retrieval

- [Document ingestion](https://github.com/lnyo-cly/ai4j/blob/main/ai4j/src/main/java/io/github/lnyocly/ai4j/rag/ingestion/IngestionPipeline.java): `ai4j/src/main/java/io/github/lnyocly/ai4j/rag/ingestion/IngestionPipeline.java`
- [Embedding services](https://github.com/lnyo-cly/ai4j/blob/main/ai4j/src/main/java/io/github/lnyocly/ai4j/platform/openai/embedding/OpenAiEmbeddingService.java): `ai4j/src/main/java/io/github/lnyocly/ai4j/platform/openai/embedding/OpenAiEmbeddingService.java`
- [Vector stores](https://github.com/lnyo-cly/ai4j/blob/main/ai4j/src/main/java/io/github/lnyocly/ai4j/vector/service/PineconeService.java): `ai4j/src/main/java/io/github/lnyocly/ai4j/vector/service/PineconeService.java`
- [RAG retrieval](https://github.com/lnyo-cly/ai4j/blob/main/ai4j/src/main/java/io/github/lnyocly/ai4j/rag/DefaultRagService.java): `ai4j/src/main/java/io/github/lnyocly/ai4j/rag/DefaultRagService.java`

### Coding and tasks

- [Coding agent](https://github.com/lnyo-cly/ai4j/blob/main/ai4j-coding/src/main/java/io/github/lnyocly/ai4j/coding/loop/CodingAgentLoopController.java): `ai4j-coding/src/main/java/io/github/lnyocly/ai4j/coding/loop/CodingAgentLoopController.java`
- [Workspace files](https://github.com/lnyo-cly/ai4j/blob/main/ai4j-coding/src/main/java/io/github/lnyocly/ai4j/coding/workspace/LocalWorkspaceFileService.java): `ai4j-coding/src/main/java/io/github/lnyocly/ai4j/coding/workspace/LocalWorkspaceFileService.java`
- [Coding tasks](https://github.com/lnyo-cly/ai4j/blob/main/ai4j-coding/src/main/java/io/github/lnyocly/ai4j/coding/task/CodingTaskManager.java): `ai4j-coding/src/main/java/io/github/lnyocly/ai4j/coding/task/CodingTaskManager.java`
- [Long-task harness](https://github.com/lnyo-cly/ai4j/blob/main/ai4j-harness/src/main/java/io/github/lnyocly/ai4j/harness/HarnessTaskSpec.java): `ai4j-harness/src/main/java/io/github/lnyocly/ai4j/harness/HarnessTaskSpec.java`

### Integrations and workflows

- [FlowGram API](https://github.com/lnyo-cly/ai4j/blob/main/ai4j-flowgram-spring-boot-starter/src/main/java/io/github/lnyocly/ai4j/flowgram/springboot/controller/FlowGramTaskController.java): `ai4j-flowgram-spring-boot-starter/src/main/java/io/github/lnyocly/ai4j/flowgram/springboot/controller/FlowGramTaskController.java`
- [FlowGram runtime](https://github.com/lnyo-cly/ai4j/blob/main/ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/flowgram/FlowGramRuntimeService.java): `ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/flowgram/FlowGramRuntimeService.java`
- [A2A protocol](https://github.com/lnyo-cly/ai4j/blob/main/ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/a2a/A2AClient.java): `ai4j-agent/src/main/java/io/github/lnyocly/ai4j/agent/a2a/A2AClient.java`
- [MCP server](https://github.com/lnyo-cly/ai4j/blob/main/ai4j/src/main/java/io/github/lnyocly/ai4j/mcp/server/McpServerEngine.java): `ai4j/src/main/java/io/github/lnyocly/ai4j/mcp/server/McpServerEngine.java`

### Other components

- **Application caller**
- **Model providers**

## Connections

- Application caller → Agent API: submits request (evidence: `README.md`)
- Agent API → Execution modes: runs agent (evidence: `README.md`)
- Execution modes → Model clients: requests completion (evidence: `README.md`)
- Model clients → Model providers: calls provider (evidence: `README.md`)
- Execution modes → Tool execution: dispatches tools (evidence: `README.md`)
- Execution modes → Agent memory: uses memory (evidence: `README.md`)
- Tool execution → Permission checks: checks approval
- Execution modes → Agent result: returns result
- Document ingestion → Embedding services: creates embeddings (evidence: `ai4j/src/main/java/io/github/lnyocly/ai4j/rag/ingestion/IngestionPipeline.java`)
- Document ingestion → Vector stores: upserts vectors (evidence: `ai4j/src/main/java/io/github/lnyocly/ai4j/rag/ingestion/IngestionPipeline.java`)
- RAG retrieval → Vector stores: retrieves vectors
- Tool execution → RAG retrieval: offers RAG tool
- Application caller → Coding agent: starts coding task (evidence: `README.md`)
- Coding agent → Workspace files: works on files (evidence: `README.md`)
- Coding agent → Coding tasks: manages task
- Long-task harness → Coding tasks: governs long tasks
- Application caller → FlowGram API: submits workflow (evidence: `ai4j-flowgram-spring-boot-starter/src/main/java/io/github/lnyocly/ai4j/flowgram/springboot/controller/FlowGramTaskController.java`)
- FlowGram API → FlowGram runtime: delegates task
- Agent API → A2A protocol: exposes collaboration (evidence: `README.md`)
- Agent API → MCP server: exposes capabilities (evidence: `README.md`)
