# temporal-community/temporal-ai-agent architecture

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

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

## Overview

##### Major Components

a. Frontend (React UI):
- Located in the “frontend” directory.
- Built with React (using Vite) and Tailwind CSS.
- Handles user interactions, chat interfaces (e.g., ChatWindow.jsx, MessageBubble.jsx), and communicates with the backend API.

b. Backend API Server (Python):
- Found under the “api” directory (main.py) and supplemented by other scripts.
- Implemented with FastAPI/Uvicorn to expose endpoints (documented in /docs).
- Serves as an interfacing layer between the frontend and the Temporal workflow.

c. Temporal Workers & Workflows (Python):
- The scripts folder contains “run_worker.py” (and also “run_worker” style scripts) that start the Temporal worker to process workflows.
- Workflows are defined under the “workflows” directory and include “agent_goal_workflow.py” and helper modules.
- “activities” contains Python activities for tool operations.
- The Temporal configuration (e.g. connection details) is read from the environment variables and .env file.

d. Tools & Registries:
- “tools” directory includes tool modules (e.g., create_invoice.py, search_flights.py, search_trains.py) along with data and configuration files.
- “goal_registry.py” and “tool_registry.py” (under tools and workflows) map the agent’s capabilities and goals to the specific tools.
- “prompts” directory holds the prompt generation logic for the agent interactions.

e. Enterprise (.NET) Worker:
- The “enterprise” directory contains a C# (.NET) solution that implements specific activities (notably for train search/booking) as part of the “goal_match_train_invoice” scenario.
- This component interacts with external train APIs and serves as a fallback when Python activities are intentionally failing (to show Temporal’s retry behavior).

f. External Services:
- External LLM providers (OpenAI, Anthropic, Google Gemini, DeepSeek, or local LLM via Ollama) are configurable through environment variables.
- External APIs: Flight APIs (RapidAPI), Train API (started by running thirdparty/train_api.py), Stripe for invoice creation, and also a Football Data API for match search.
- Temporal Server itself (either local or cloud) as the workflow orchestration engine.

g. Supporting Scripts & Configurations:
- The “scripts” directory holds various helper scripts (for testing, managing invoices, chat history, etc.).
- Configuration files like .env.example, pyproject.toml, and the .gitignore files regulate deployment and environment setup.

##### Component Relationships and Data Flow

- The React frontend (user interface) communicates via HTTP with the Python API server.
- The API server triggers Temporal workflows (via the Temporal client) to start or interact with an ongoing agent conversation.
- Temporal workflows orchestrate multiple activities:
- They call Python-based tool activities (located in “activities” and “tools”).
- They may also delegate tasks to external services (e.g., contacting flight or event search APIs, or invoicing via Stripe).
- For the “goal_match_train_invoice” scenario, the workflow interacts with the .NET enterprise worker through inter-process communication (or via HTTP calls to the .NET service, depending on configuration).
- The tools and registries serve as the “brain” mapping out which actions to call next based on the current conversation context.
- External LLM providers are invoked (from within Python code) to generate responses and control the agent’s decision-making.

##### Architectural Patterns & Design Principles

- Separation of concerns: Distinct modules for frontend, backend API, Temporal orchestration, tools/activities, and enterprise-specific functionality.
- Modular extensibility: Goal and tool registries allow plugging in different behaviors based on the agent’s objective.
- Polyglot environment: Integration of Python and .NET components indicating a microservices-like approach.
- Resiliency: The indexing of retry/failure behavior in activities, especially the legacy worker and its resolution via the .NET worker.
- Configuration management via environment variables (with .env) ensures that credentials and settings are kept external to code.

- Every component is clearly labeled with its function.
- Incoming requests (e.g., from UI to API).
- Internal orchestration flows (between API server, Temporal workflow, and tools).
- Outgoing calls to external services.
- Incorporate notes on the technologies used for each component.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Frontend Layer
  subgraph "Frontend Layer"
    FE["Frontend – React UI (React/Vite, Tailwind)"]:::frontend
  end

  %% Backend Layer
  subgraph "Backend Layer"
    API["API Server (Python/FastAPI)"]:::backend
  end

  %% Workflow & Activity Layer
  subgraph "Workflow & Activity Layer"
    TEMP["Temporal Workers & Workflows (Python)"]:::backend
    ACT["Tool Activities & Registries"]:::backend
  end

  %% Enterprise & External Layer
  subgraph "Enterprise & External Layer"
    ENT["Enterprise Worker (.NET)"]:::dotnet
    EXT["External Services (LLM, ThirdParty APIs, Stripe, etc.)"]:::external
  end

  %% Data Flow Connections
  FE -->|"HTTP_requests"| API
  API -->|"Triggers_Workflow"| TEMP
  TEMP -->|"Workflow_Updates"| API
  TEMP -->|"Invokes_Tool_Activities"| ACT
  TEMP -->|"Delegates_TrainBooking"| ENT
  ACT -->|"Calls_External_APIs"| EXT
  TEMP -->|"Direct_External_Calls"| EXT

  %% Click Events
  click FE "https://github.com/temporal-community/temporal-ai-agent/tree/main/frontend/"
  click API "https://github.com/temporal-community/temporal-ai-agent/blob/main/api/main.py"
  click TEMP "https://github.com/temporal-community/temporal-ai-agent/blob/main/scripts/run_worker.py"
  click ACT "https://github.com/temporal-community/temporal-ai-agent/tree/main/tools/"
  click ENT "https://github.com/temporal-community/temporal-ai-agent/tree/main/enterprise/"
  click EXT "https://github.com/temporal-community/temporal-ai-agent/blob/main/thirdparty/train_api.py"

  %% Styles
  classDef frontend fill:#cce5ff,stroke:#0056b3,stroke-width:2px;
  classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
  classDef dotnet fill:#f8d7da,stroke:#721c24,stroke-width:2px;
  classDef external fill:#fff3cd,stroke:#856404,stroke-width:2px;
```
