# steveandroulakis/temporal-ai-agent architecture

> Architecture diagram of the GitHub repository steveandroulakis/temporal-ai-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/steveandroulakis/temporal-ai-agent
- Repository: https://github.com/steveandroulakis/temporal-ai-agent

## Overview

##### Project type and purpose
- This is a full-stack “AI Agent” demo application built on Temporal.
- Purpose: Drive a multi-turn conversation with an LLM inside a durable workflow; support native and MCP (Model Context Protocol) tool calls; expose a web UI and an HTTP API; ship example enterprise (.NET) worker.

##### File structure
- Top-level components:
- frontend/ – React + Vite + Tailwind UI
- api/ – FastAPI (or similar) HTTP server entrypoint
- workflows/ & activities/ – Python Temporal workflows and Activities that implement the agent loop
- tools/ – Native tool implementations (python scripts) organized by domain + registration logic
- shared/ – Config, MCP client manager, common code
- goals/ – Goal definitions driving which tools and prompts to use
- enterprise/ – C# sample worker & activities for “Train” domain
- docker-compose.yml, Dockerfile, Makefile, .devcontainer – dev and deployment tooling
- Supporting artifacts:
- docs/ – architecture decisions, setup, testing guidelines
- tests/ – pytest-based workflow & activity tests
- .github/workflows/ci.yml – CI pipeline

##### README
- Describes the core architecture: Temporal workflows for durability, Activities for tool calls, LLM orchestration, multi-agent vs single-agent modes.
- Highlights two kinds of tools: native (in tools/) and MCP (configured via shared/mcp_config.py).
- The UI (frontend/) communicates with api/main.py which folds into Temporal workflows.

##### Main components
a. Frontend (React app)
- Components: ChatWindow, message bubble, NavBar
- Communicates via REST/WebSocket to API
b. API Server (api/main.py)
- Exposes HTTP endpoints: start chat, send user message, query chat state
- Translates requests into Temporal Workflow signals/queries
c. Temporal Server
- Orchestrates Workflow executions, stores history
- Persistence backend (PostgreSQL or Cassandra – optional)
d. Workflow Worker (Python process)
- Hosts Workflow definitions (workflows/agent_goal_workflow.py)
- Hosts Activity stubs for orchestration loops
e. Activity Worker (Python process)
- Activities in activities/tool_activities.py call into:
- Native tools (tools/… modules)
- MCP tools via shared/mcp_client_manager.py + shared/mcp_config.py
- Prompt generators (prompts/agent_prompt_generators.py)
f. Enterprise Worker (C# process)
- Example .NET Temporal Worker for TrainActivities
g. External Services
- LLM Providers (OpenAI, Anthropic, etc. via LiteLLM)
- MCP servers (Stripe, custom APIs)
h. Persistence & Observability
- Temporal’s own database
- (Optional) Check-claim pattern storage for large payloads

##### Relationships & interactions
1. User → Frontend → API
2. API → Temporal Workflow (Start/Signal)
3. Workflow → Activity Worker (LLM call, tool invocation)
4. Activity Worker → External LLM / MCP service
5. Activity Worker → returns output → Workflow
6. Workflow aggregates history, loops until goal complete
7. API queries Workflow for state → Frontend updates UI
8. Enterprise Worker runs in parallel for domain-specific workflows

##### Architectural patterns & principles
- Orchestrator-Worker pattern (Temporal)
- Separation of concerns:
- Workflow code handles control flow & state
- Activities handle side-effects (tool and LLM calls)
- API layer handles user communication
- Frontend handles presentation
- Plugin-style tool registry (tools/tool_registry.py)
- Domain-driven goal modules under goals/
- Durable, event-sourced workflow history
- Extensibility: add new goals in /goals/, new tools in /tools/

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        User["User"]:::external
        Frontend["Frontend (React App)"]:::frontend
        subgraph "Frontend Components"
            direction TB
            ChatWindow["ChatWindow"]:::frontend
            NavBar["NavBar"]:::frontend
            MessageBubble["MessageBubble"]:::frontend
            AppPage["App.jsx"]:::frontend
            ApiService["api.js"]:::frontend
        end
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        API["API Server\napi/main.py"]:::api
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        TemporalServer["Temporal Server"]:::orchestration
        WorkflowWorker["Workflow Worker\n(workflows/)"]:::orchestration
        subgraph "Workflows"
            direction TB
            AgentWorkflow["agent_goal_workflow.py"]:::orchestration
            WorkflowHelpers["workflow_helpers.py"]:::orchestration
        end
        TemporalDB["Temporal Database"]:::db
    end

    %% Worker Layer
    subgraph "Worker Layer"
        direction TB
        ActivityWorker["Activity Worker\n(activities/)"]:::worker
        subgraph "Activities & Tools"
            direction TB
            ToolActivities["tool_activities.py"]:::worker
            NativeTools["Native Tools\n(tools/)"]:::worker
            MCPClient["MCP Client Manager\n(shared/mcp_client_manager.py)"]:::worker
            MCPConfig["MCP Config\n(shared/mcp_config.py)"]:::worker
            PromptGen["Prompt Generators\n(prompts/)"]:::worker
            Goals["Goal Definitions\n(goals/)"]:::worker
            SharedConfig["Shared Config\n(shared/config.py)"]:::worker
        end
        EnterpriseWorker["Enterprise .NET Worker"]:::worker
        subgraph "Enterprise Components"
            direction TB
            ProgramCs["Program.cs"]:::worker
            TrainActivitiesCs["TrainActivities.cs"]:::worker
        end
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        LLMProviders["LLM Providers\n(OpenAI, Anthropic)"]:::external
        MCPServers["MCP Servers"]:::external
    end

    %% Relationships
    User -->|"uses"| Frontend
    ChatWindow -->|"component of"| Frontend
    NavBar -->|"component of"| Frontend
    MessageBubble -->|"component of"| Frontend
    AppPage -->|"loads components"| Frontend
    ApiService -->|"calls"| API

    Frontend -->|"HTTPS/WebSocket"| API
    API -->|"Temporal RPC (Start/Signal/Query)"| TemporalServer
    TemporalServer -->|"dispatches workflows"| WorkflowWorker
    WorkflowWorker -->|"executes"| AgentWorkflow
    WorkflowWorker -->|"uses helpers"| WorkflowHelpers

    WorkflowWorker -->|"invokes activities"| ActivityWorker
    ActivityWorker -->|"LLM Calls"| LLMProviders
    ActivityWorker -->|"MCP Calls"| MCPServers
    ActivityWorker -->|"reads prompts"| PromptGen
    ActivityWorker -->|"executes native tools"| NativeTools
    ActivityWorker -->|"manages registry"| MCPClient
    ActivityWorker -->|"reads config"| SharedConfig
    ActivityWorker -->|"loads goals"| Goals

    ActivityWorker -->|"returns results"| WorkflowWorker
    WorkflowWorker -->|"updates state"| TemporalServer
    TemporalServer -->|"persists history"| TemporalDB

    API -->|"query state"| TemporalServer
    TemporalServer -->|"responds"| API
    API -->|"updates UI"| Frontend

    EnterpriseWorker -->|"connects to"| TemporalServer
    ProgramCs -->|"defines worker"| EnterpriseWorker
    TrainActivitiesCs -->|"activities"| EnterpriseWorker

    %% Click Events
    click ChatWindow "https://github.com/steveandroulakis/temporal-ai-agent/blob/main/frontend/src/components/ChatWindow.jsx"
    click NavBar "https://github.com/steveandroulakis/temporal-ai-agent/blob/main/frontend/src/components/NavBar.jsx"
    click MessageBubble "https://github.com/steveandroulakis/temporal-ai-agent/blob/main/frontend/src/components/MessageBubble.jsx"
    click AppPage "https://github.com/steveandroulakis/temporal-ai-agent/blob/main/frontend/src/pages/App.jsx"
    click ApiService "https://github.com/steveandroulakis/temporal-ai-agent/blob/main/frontend/src/services/api.js"
    click API "https://github.com/steveandroulakis/temporal-ai-agent/blob/main/api/main.py"
    click AgentWorkflow "https://github.com/steveandroulakis/temporal-ai-agent/blob/main/workflows/agent_goal_workflow.py"
    click WorkflowHelpers "https://github.com/steveandroulakis/temporal-ai-agent/blob/main/workflows/workflow_helpers.py"
    click ToolActivities "https://github.com/steveandroulakis/temporal-ai-agent/blob/main/activities/tool_activities.py"
    click NativeTools "https://github.com/steveandroulakis/temporal-ai-agent/tree/main/tools/"
    click MCPClient "https://github.com/steveandroulakis/temporal-ai-agent/blob/main/shared/mcp_client_manager.py"
    click MCPConfig "https://github.com/steveandroulakis/temporal-ai-agent/blob/main/shared/mcp_config.py"
    click PromptGen "https://github.com/steveandroulakis/temporal-ai-agent/blob/main/prompts/agent_prompt_generators.py"
    click Goals "https://github.com/steveandroulakis/temporal-ai-agent/tree/main/goals/"
    click SharedConfig "https://github.com/steveandroulakis/temporal-ai-agent/blob/main/shared/config.py"
    click ProgramCs "https://github.com/steveandroulakis/temporal-ai-agent/blob/main/enterprise/Program.cs"
    click TrainActivitiesCs "https://github.com/steveandroulakis/temporal-ai-agent/blob/main/enterprise/Activities/TrainActivities.cs"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef api fill:#E2F0CB,stroke:#6AA84F,color:#274E13;
    classDef orchestration fill:#FFE6CC,stroke:#E69138,color:#783F04;
    classDef worker fill:#EAD1DC,stroke:#C27BA0,color:#5B0F2C;
    classDef external fill:#F4CCCC,stroke:#CC0000,color:#660000;
    classDef db fill:#FFF2CC,stroke:#BF9000,color:#7F6000;
```
