# f4cio/aichatbot architecture

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

- Interactive diagram: https://gitdiagram.com/f4cio/aichatbot
- Repository: https://github.com/f4cio/aichatbot

## Overview

#### Purpose and topology
AiChatBot is a .NET 10 n-tier chatbot that sends user messages to Anthropic Claude Managed Agents. It has three interchangeable hosts: an ASP.NET Core REST API, console REPL, and Htmx UI; a separate React 19 SPA consumes the API. There is no application database or authentication; durable context is delegated to Claude’s Memory store.

Key entry points:
- `SourceCode/F4CIO.AiChatBot.UiApi/Program.cs`
- `SourceCode/F4CIO.AiChatBot.UiConsole/Program.cs`
- `SourceCode/F4CIO.AiChatBot.UiHtmx/Program.cs`
- `SourceCode/F4CIO.AiChatBot.UiWeb/src/main.tsx`

#### Shared domain and service boundary
Entities define configuration, request/response, error, and streaming DTO shapes shared across layers. `IChatService` is the primary host-to-business-logic boundary, allowing API and console clients to invoke the same chat capability without depending on Claude details.

- `SourceCode/F4CIO.AiChatBot.Common.Entities/Configuration.cs`
- `SourceCode/F4CIO.AiChatBot.Common.Entities/Dtos.cs`
- `SourceCode/F4CIO.AiChatBot.Common.Entities/DtosStreaming.cs`
- `SourceCode/F4CIO.AiChatBot.Contracts/IChatService.cs`

#### Chat orchestration and Claude integration
`ChatService` implements request handling and streaming behavior. Conversation-specific handling separates local conversation state/logging concerns from the Anthropic integration. `HandlerForClaude` encapsulates the beta Managed Agents SDK surface, making it the key isolation point for Anthropic API changes.

At startup/use, the integration finds or creates configured Claude Environment, Agent, and Memory store resources. Each session attaches the Memory store, so Anthropic persists durable memory while the API process retains only in-memory run/session continuity.

- `SourceCode/F4CIO.AiChatBot.BusinessLogic/ChatService.cs`
- `SourceCode/F4CIO.AiChatBot.BusinessLogic/ChatService.Streaming.cs`
- `SourceCode/F4CIO.AiChatBot.BusinessLogic/HandlerForClaude.cs`
- `SourceCode/F4CIO.AiChatBot.BusinessLogic/HandlerForClaude.Streaming.cs`
- `SourceCode/F4CIO.AiChatBot.BusinessLogic/HandlerForConversation.cs`

#### API host and streaming boundary
The ASP.NET Core API exposes chat endpoints through its controller and publishes Swagger/OpenAPI for client generation. Startup establishes dependency injection, configuration, CORS, and HTTP pipeline behavior. API exceptions are translated by a dedicated handler; server-sent events provide incremental Claude output to streaming clients.

- `SourceCode/F4CIO.AiChatBot.UiApi/Controllers/ChatController.cs`
- `SourceCode/F4CIO.AiChatBot.UiApi/HandlerForStartup.cs`
- `SourceCode/F4CIO.AiChatBot.UiApi/HandlerForServerSentEvents.cs`
- `SourceCode/F4CIO.AiChatBot.UiApi/HandlerForApiExceptions.cs`

#### Front-end variants
The React SPA is a static Vite build with a single application screen. Its generated typed API client follows the API OpenAPI contract; streaming and runtime API-base resolution are handled in the API modules. `public/config.js` is deployed separately so the API URL can change without rebuilding the SPA.

- `SourceCode/F4CIO.AiChatBot.UiWeb/src/App.tsx`
- `SourceCode/F4CIO.AiChatBot.UiWeb/src/api/apiClient.ts`
- `SourceCode/F4CIO.AiChatBot.UiWeb/src/api/stream.ts`
- `SourceCode/F4CIO.AiChatBot.UiWeb/public/config.js`

The Htmx host is an alternative server-rendered single-screen UI with its own controller and Razor page/partial rendering, plus browser streaming support.

- `SourceCode/F4CIO.AiChatBot.UiHtmx/Controllers/ChatController.cs`
- `SourceCode/F4CIO.AiChatBot.UiHtmx/Pages/Index.cshtml`
- `SourceCode/F4CIO.AiChatBot.UiHtmx/Pages/Shared/_MessagePartial.cshtml`
- `SourceCode/F4CIO.AiChatBot.UiHtmx/wwwroot/js/stream.js`

#### Operational boundaries
Common infrastructure centralizes structured error IDs, host-owned logs, conversation transcript files, and path resolution. Hosts supply configuration, including the Claude API key, model, named Managed Agent resources, API URL, and CORS origins.

- `SourceCode/F4CIO.AiChatBot.Common/HandlerForLogging.cs`
- `SourceCode/F4CIO.AiChatBot.Common/HandlerForErrors.cs`
- `SourceCode/F4CIO.AiChatBot.Common/HandlerForConversationLog.cs`
- `SourceCode/F4CIO.AiChatBot.UiApi/appsettings.json`

Deployment targets Windows/IIS: the API can be self-contained behind ASP.NET Core Module, while React is static content with IIS rewrite support. Published outputs are staged under `Published/`.

- `Published/F4CIO.AiChatBot.UiApi/web.config`
- `Published/F4CIO.AiChatBot.UiWeb/web.config`

Main entry points: [`SourceCode/F4CIO.AiChatBot.BusinessLogic/ChatService.cs`](https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.BusinessLogic/ChatService.cs) (ChatService), [`SourceCode/F4CIO.AiChatBot.UiApi/Program.cs`](https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.UiApi/Program.cs) (ASP.NET Core API), [`SourceCode/F4CIO.AiChatBot.UiApi/Controllers/ChatController.cs`](https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.UiApi/Controllers/ChatController.cs) (Chat API controller), [`SourceCode/F4CIO.AiChatBot.Contracts/IChatService.cs`](https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.Contracts/IChatService.cs) (IChatService)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shared["Shared Core"]
  node_entities["Shared DTOs &amp; config<br/>entities<br/>[Dtos.cs]"]
  node_chat_contract{{"IChatService<br/>service contract<br/>[IChatService.cs]"}}
end

subgraph group_hosts["Hosts"]
  node_api_host["ASP.NET Core API<br/>API host<br/>[Program.cs]"]
  node_api_controller["Chat API controller<br/>REST endpoints<br/>[ChatController.cs]"]
  node_sse_handler["SSE handler<br/>streaming transport"]
  node_api_errors["API exception handler<br/>error boundary"]
  node_console_host["Console REPL<br/>console host<br/>[Program.cs]"]
  node_htmx_controller["Htmx chat controller<br/>server-rendered host<br/>[ChatController.cs]"]
  node_htmx_page["Htmx Razor screen<br/>Razor UI<br/>[Index.cshtml]"]
  node_htmx_stream["Htmx browser stream<br/>browser streaming<br/>[stream.js]"]
  node_react_entry["React SPA<br/>Vite entry<br/>[main.tsx]"]
  node_react_screen["Chat screen<br/>React UI<br/>[App.tsx]"]
  node_typed_client["Typed API client<br/>OpenAPI client<br/>[apiClient.ts]"]
  node_react_stream["SPA stream client<br/>browser streaming<br/>[stream.ts]"]
end

subgraph group_claude["Claude Integration"]
  node_chat_service["ChatService<br/>orchestrator<br/>[ChatService.cs]"]
  node_conversation_handler["Conversation handler<br/>conversation state"]
  node_claude_handler["HandlerForClaude<br/>SDK adapter"]
  node_claude_platform{{"Anthropic Managed Agents<br/>external platform"}}
  node_memory_store[("Claude Memory store<br/>durable context")]
end

subgraph group_operations["Operations &amp; Deployment"]
  node_runtime_config["Runtime API config<br/>deployment config<br/>[config.js]"]
  node_common_ops["Logging &amp; transcripts<br/>shared operations"]
  node_iis_deployment["IIS published outputs<br/>Windows deployment<br/>[web.config]"]
end

node_api_host -->|"routes requests"| node_api_controller
node_api_host -->|"handles failures"| node_api_errors
node_api_controller -->|"invokes"| node_chat_contract
node_api_controller -->|"streams via"| node_sse_handler
node_console_host -->|"invokes"| node_chat_contract
node_htmx_controller -->|"invokes"| node_chat_contract
node_htmx_page -->|"loads"| node_htmx_stream
node_htmx_stream -->|"chat stream"| node_htmx_controller
node_react_entry -->|"renders"| node_react_screen
node_react_screen -->|"sends chat"| node_typed_client
node_react_screen -->|"receives stream"| node_react_stream
node_runtime_config -->|"sets API base"| node_typed_client
node_typed_client -->|"REST / OpenAPI"| node_api_controller
node_react_stream -->|"SSE"| node_sse_handler
node_chat_contract -->|"implemented by"| node_chat_service
node_chat_service -->|"uses DTOs"| node_entities
node_chat_service -->|"coordinates"| node_conversation_handler
node_chat_service -->|"delegates agent calls"| node_claude_handler
node_conversation_handler -->|"writes transcripts"| node_common_ops
node_claude_handler -->|"Managed Agents SDK"| node_claude_platform
node_claude_platform -->|"attaches per session"| node_memory_store
node_api_host -->|"host logs"| node_common_ops
node_console_host -->|"host logs"| node_common_ops
node_iis_deployment -->|"hosts API"| node_api_host
node_iis_deployment -->|"serves SPA build"| node_react_entry

click node_entities "https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.Common.Entities/Dtos.cs"
click node_chat_contract "https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.Contracts/IChatService.cs"
click node_chat_service "https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.BusinessLogic/ChatService.cs"
click node_conversation_handler "https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.BusinessLogic/HandlerForConversation.cs"
click node_claude_handler "https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.BusinessLogic/HandlerForClaude.cs"
click node_api_host "https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.UiApi/Program.cs"
click node_api_controller "https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.UiApi/Controllers/ChatController.cs"
click node_sse_handler "https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.UiApi/HandlerForServerSentEvents.cs"
click node_api_errors "https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.UiApi/HandlerForApiExceptions.cs"
click node_console_host "https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.UiConsole/Program.cs"
click node_htmx_controller "https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.UiHtmx/Controllers/ChatController.cs"
click node_htmx_page "https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.UiHtmx/Pages/Index.cshtml"
click node_htmx_stream "https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.UiHtmx/wwwroot/js/stream.js"
click node_react_entry "https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.UiWeb/src/main.tsx"
click node_react_screen "https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.UiWeb/src/App.tsx"
click node_typed_client "https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.UiWeb/src/api/apiClient.ts"
click node_react_stream "https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.UiWeb/src/api/stream.ts"
click node_runtime_config "https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.UiWeb/public/config.js"
click node_common_ops "https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.Common/HandlerForLogging.cs"
click node_iis_deployment "https://github.com/f4cio/aichatbot/blob/main/Published/F4CIO.AiChatBot.UiApi/web.config"

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_entities,node_chat_contract toneBlue
class node_api_host,node_api_controller,node_sse_handler,node_api_errors,node_console_host,node_htmx_controller,node_htmx_page,node_htmx_stream,node_react_entry,node_react_screen,node_typed_client,node_react_stream toneAmber
class node_chat_service,node_conversation_handler,node_claude_handler,node_claude_platform,node_memory_store toneMint
class node_runtime_config,node_common_ops,node_iis_deployment toneRose
```

## Components

### Shared Core

- [Shared DTOs & config](https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.Common.Entities/Dtos.cs): entities · Request, response, streaming, error, and configuration shapes. · `SourceCode/F4CIO.AiChatBot.Common.Entities/Dtos.cs`
- [IChatService](https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.Contracts/IChatService.cs): service contract · Primary host-to-chat boundary. · `SourceCode/F4CIO.AiChatBot.Contracts/IChatService.cs`

### Hosts

- [ASP.NET Core API](https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.UiApi/Program.cs): API host · Configures DI, CORS, and HTTP pipeline. · `SourceCode/F4CIO.AiChatBot.UiApi/Program.cs`
- [Chat API controller](https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.UiApi/Controllers/ChatController.cs): REST endpoints · Exposes chat and OpenAPI contract. · `SourceCode/F4CIO.AiChatBot.UiApi/Controllers/ChatController.cs`
- [SSE handler](https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.UiApi/HandlerForServerSentEvents.cs): streaming transport · Publishes incremental chat output. · `SourceCode/F4CIO.AiChatBot.UiApi/HandlerForServerSentEvents.cs`
- [API exception handler](https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.UiApi/HandlerForApiExceptions.cs): error boundary · Translates server errors into API responses. · `SourceCode/F4CIO.AiChatBot.UiApi/HandlerForApiExceptions.cs`
- [Console REPL](https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.UiConsole/Program.cs): console host · Alternative interactive chat host. · `SourceCode/F4CIO.AiChatBot.UiConsole/Program.cs`
- [Htmx chat controller](https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.UiHtmx/Controllers/ChatController.cs): server-rendered host · Alternative browser chat host. · `SourceCode/F4CIO.AiChatBot.UiHtmx/Controllers/ChatController.cs`
- [Htmx Razor screen](https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.UiHtmx/Pages/Index.cshtml): Razor UI · Renders chat page and message partials. · `SourceCode/F4CIO.AiChatBot.UiHtmx/Pages/Index.cshtml`
- [Htmx browser stream](https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.UiHtmx/wwwroot/js/stream.js): browser streaming · `SourceCode/F4CIO.AiChatBot.UiHtmx/wwwroot/js/stream.js`
- [React SPA](https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.UiWeb/src/main.tsx): Vite entry · Static React 19 chat application. · `SourceCode/F4CIO.AiChatBot.UiWeb/src/main.tsx`
- [Chat screen](https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.UiWeb/src/App.tsx): React UI · Single application screen. · `SourceCode/F4CIO.AiChatBot.UiWeb/src/App.tsx`
- [Typed API client](https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.UiWeb/src/api/apiClient.ts): OpenAPI client · Generated client for the API contract. · `SourceCode/F4CIO.AiChatBot.UiWeb/src/api/apiClient.ts`
- [SPA stream client](https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.UiWeb/src/api/stream.ts): browser streaming · Consumes incremental API output. · `SourceCode/F4CIO.AiChatBot.UiWeb/src/api/stream.ts`

### Claude Integration

- [ChatService](https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.BusinessLogic/ChatService.cs): orchestrator · Handles chat requests and streaming. · `SourceCode/F4CIO.AiChatBot.BusinessLogic/ChatService.cs`
- [Conversation handler](https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.BusinessLogic/HandlerForConversation.cs): conversation state · Manages local session continuity and transcript concerns. · `SourceCode/F4CIO.AiChatBot.BusinessLogic/HandlerForConversation.cs`
- [HandlerForClaude](https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.BusinessLogic/HandlerForClaude.cs): SDK adapter · Isolation boundary for Managed Agents SDK calls. · `SourceCode/F4CIO.AiChatBot.BusinessLogic/HandlerForClaude.cs`
- **Anthropic Managed Agents**: external platform · Provides Environment, Agent, runs, and Memory resources.
- **Claude Memory store**: durable context · Anthropic-owned durable conversation memory.

### Operations & Deployment

- [Runtime API config](https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.UiWeb/public/config.js): deployment config · Allows API URL changes without rebuilding the SPA. · `SourceCode/F4CIO.AiChatBot.UiWeb/public/config.js`
- [Logging & transcripts](https://github.com/f4cio/aichatbot/blob/main/SourceCode/F4CIO.AiChatBot.Common/HandlerForLogging.cs): shared operations · Hosts own logs; conversation transcripts are file-backed. · `SourceCode/F4CIO.AiChatBot.Common/HandlerForLogging.cs`
- [IIS published outputs](https://github.com/f4cio/aichatbot/blob/main/Published/F4CIO.AiChatBot.UiApi/web.config): Windows deployment · API runs behind ASP.NET Core Module; SPA is static content. · `Published/F4CIO.AiChatBot.UiApi/web.config`

## Connections

- ASP.NET Core API → Chat API controller: routes requests
- ASP.NET Core API → API exception handler: handles failures
- Chat API controller → IChatService: invokes
- Chat API controller → SSE handler: streams via
- Console REPL → IChatService: invokes
- Htmx chat controller → IChatService: invokes
- Htmx Razor screen → Htmx browser stream: loads
- Htmx browser stream → Htmx chat controller: chat stream
- React SPA → Chat screen: renders
- Chat screen → Typed API client: sends chat
- Chat screen → SPA stream client: receives stream
- Runtime API config → Typed API client: sets API base
- Typed API client → Chat API controller: REST / OpenAPI
- SPA stream client → SSE handler: SSE
- IChatService → ChatService: implemented by
- ChatService → Shared DTOs & config: uses DTOs
- ChatService → Conversation handler: coordinates
- ChatService → HandlerForClaude: delegates agent calls
- Conversation handler → Logging & transcripts: writes transcripts
- HandlerForClaude → Anthropic Managed Agents: Managed Agents SDK
- Anthropic Managed Agents → Claude Memory store: attaches per session
- ASP.NET Core API → Logging & transcripts: host logs
- Console REPL → Logging & transcripts: host logs
- IIS published outputs → ASP.NET Core API: hosts API
- IIS published outputs → React SPA: serves SPA build