# rrusson/darkclippy architecture

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

- Interactive diagram: https://gitdiagram.com/rrusson/darkclippy
- Repository: https://github.com/rrusson/darkclippy

## Overview

DarkClippy is an ASP.NET chatbot that presents a Clippy-themed web experience and sends questions to a locally hosted Ollama model through Semantic Kernel. The main workflow accepts a question at the chat API, obtains a client keyed by requester IP, maintains per-client conversation context, and returns Markdown-rendered HTML. Startup also validates the configured service connection. The README documents the Ollama integration and Clippy.js capability; source excerpts do not establish the browser-side request wiring or connection-validation internals, so those links are kept limited.

Main entry points: [`ClippyWeb/Controllers/ChatController.cs`](https://github.com/rrusson/darkclippy/blob/master/ClippyWeb/Controllers/ChatController.cs) (Chat API), [`ClippyWeb/Util/ConnectionValidator.cs`](https://github.com/rrusson/darkclippy/blob/master/ClippyWeb/Util/ConnectionValidator.cs) (Connection validator), [`SemanticKernelHelper/SemanticKernelClient.cs`](https://github.com/rrusson/darkclippy/blob/master/SemanticKernelHelper/SemanticKernelClient.cs) (Session chat client), [`ClippyWeb/Program.cs`](https://github.com/rrusson/darkclippy/blob/master/ClippyWeb/Program.cs) (ASP.NET app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["ASP.NET app<br/>[Program.cs]"]
  node_chatui["Chat page"]
  node_clippy["Clippy assistant"]
end

subgraph group_chat["Chat handling"]
  node_api["Chat API<br/>[ChatController.cs]"]
  node_requestgate["Request gate<br/>[ChatController.cs]"]
  node_markdown["Markdown rendering<br/>[ChatController.cs]"]
  node_memory[("Memory cache")]
end

subgraph group_ai["AI integration"]
  node_factory["Client factory"]
  node_sessionclient["Session chat client"]
  node_history[("Chat history")]
  node_kernel["Semantic Kernel"]
end

subgraph group_connectivity["Startup connectivity"]
  node_validator["Connection validator"]
  node_ping["Ping service<br/>[PingService.cs]"]
  node_tcpfactory["TCP client factory"]
  node_tcpwrapper["TCP client wrapper"]
  node_interfaces["Service contracts"]
end

node_visitor(("Visitor"))
node_ollama{{"Ollama service"}}

node_visitor -->|"views"| node_chatui
node_visitor -->|"submits question"| node_api
node_webapp -->|"maps controllers"| node_api
node_webapp -->|"maps pages"| node_chatui
node_chatui -->|"loads assets"| node_clippy
node_api -->|"checks request"| node_requestgate
node_requestgate -->|"reads and writes lock"| node_memory
node_api -->|"gets client"| node_factory
node_factory -->|"caches clients"| node_memory
node_factory -->|"creates client"| node_sessionclient
node_api -->|"requests response"| node_sessionclient
node_sessionclient -->|"updates context"| node_history
node_sessionclient -->|"requests completion"| node_kernel
node_kernel -->|"streams completion"| node_ollama
node_api -->|"converts response"| node_markdown
node_markdown -->|"returns HTML"| node_visitor
node_webapp -->|"validates startup connection"| node_validator
node_validator -.->|"uses contracts"| node_interfaces
node_validator -.-> node_ping
node_validator -.-> node_tcpfactory
node_tcpfactory -->|"creates client"| node_tcpwrapper

click node_webapp "https://github.com/rrusson/darkclippy/blob/master/ClippyWeb/Program.cs"
click node_chatui "https://github.com/rrusson/darkclippy/tree/master/ClippyWeb/Pages"
click node_clippy "https://github.com/rrusson/darkclippy/tree/master/ClippyWeb/wwwroot/js/clippy"
click node_api "https://github.com/rrusson/darkclippy/blob/master/ClippyWeb/Controllers/ChatController.cs"
click node_requestgate "https://github.com/rrusson/darkclippy/blob/master/ClippyWeb/Controllers/ChatController.cs"
click node_markdown "https://github.com/rrusson/darkclippy/blob/master/ClippyWeb/Controllers/ChatController.cs"
click node_factory "https://github.com/rrusson/darkclippy/blob/master/SemanticKernelHelper/ChatClientFactory.cs"
click node_sessionclient "https://github.com/rrusson/darkclippy/blob/master/SemanticKernelHelper/SemanticKernelClient.cs"
click node_history "https://github.com/rrusson/darkclippy/blob/master/SemanticKernelHelper/SemanticKernelClient.cs"
click node_kernel "https://github.com/rrusson/darkclippy/blob/master/SemanticKernelHelper/SemanticKernelClient.cs"
click node_validator "https://github.com/rrusson/darkclippy/blob/master/ClippyWeb/Util/ConnectionValidator.cs"
click node_ping "https://github.com/rrusson/darkclippy/blob/master/ClippyWeb/Util/PingService.cs"
click node_tcpfactory "https://github.com/rrusson/darkclippy/blob/master/ClippyWeb/Util/TcpClientFactory.cs"
click node_tcpwrapper "https://github.com/rrusson/darkclippy/blob/master/ClippyWeb/Util/TcpClientWrapper.cs"
click node_interfaces "https://github.com/rrusson/darkclippy/tree/master/SharedInterfaces"

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_webapp,node_chatui,node_clippy toneBlue
class node_api,node_requestgate,node_markdown,node_memory toneAmber
class node_factory,node_sessionclient,node_history,node_kernel toneMint
class node_validator,node_ping,node_tcpfactory,node_tcpwrapper,node_interfaces toneRose
class node_visitor,node_ollama toneIndigo
```

## Components

### Web experience

- [ASP.NET app](https://github.com/rrusson/darkclippy/blob/master/ClippyWeb/Program.cs): `ClippyWeb/Program.cs`
- [Chat page](https://github.com/rrusson/darkclippy/tree/master/ClippyWeb/Pages): `ClippyWeb/Pages`
- [Clippy assistant](https://github.com/rrusson/darkclippy/tree/master/ClippyWeb/wwwroot/js/clippy): `ClippyWeb/wwwroot/js/clippy`

### Chat handling

- [Chat API](https://github.com/rrusson/darkclippy/blob/master/ClippyWeb/Controllers/ChatController.cs): `ClippyWeb/Controllers/ChatController.cs`
- [Request gate](https://github.com/rrusson/darkclippy/blob/master/ClippyWeb/Controllers/ChatController.cs): `ClippyWeb/Controllers/ChatController.cs`
- [Markdown rendering](https://github.com/rrusson/darkclippy/blob/master/ClippyWeb/Controllers/ChatController.cs): `ClippyWeb/Controllers/ChatController.cs`
- **Memory cache**

### AI integration

- [Client factory](https://github.com/rrusson/darkclippy/blob/master/SemanticKernelHelper/ChatClientFactory.cs): `SemanticKernelHelper/ChatClientFactory.cs`
- [Session chat client](https://github.com/rrusson/darkclippy/blob/master/SemanticKernelHelper/SemanticKernelClient.cs): `SemanticKernelHelper/SemanticKernelClient.cs`
- [Chat history](https://github.com/rrusson/darkclippy/blob/master/SemanticKernelHelper/SemanticKernelClient.cs): `SemanticKernelHelper/SemanticKernelClient.cs`
- [Semantic Kernel](https://github.com/rrusson/darkclippy/blob/master/SemanticKernelHelper/SemanticKernelClient.cs): `SemanticKernelHelper/SemanticKernelClient.cs`

### Startup connectivity

- [Connection validator](https://github.com/rrusson/darkclippy/blob/master/ClippyWeb/Util/ConnectionValidator.cs): `ClippyWeb/Util/ConnectionValidator.cs`
- [Ping service](https://github.com/rrusson/darkclippy/blob/master/ClippyWeb/Util/PingService.cs): `ClippyWeb/Util/PingService.cs`
- [TCP client factory](https://github.com/rrusson/darkclippy/blob/master/ClippyWeb/Util/TcpClientFactory.cs): `ClippyWeb/Util/TcpClientFactory.cs`
- [TCP client wrapper](https://github.com/rrusson/darkclippy/blob/master/ClippyWeb/Util/TcpClientWrapper.cs): `ClippyWeb/Util/TcpClientWrapper.cs`
- [Service contracts](https://github.com/rrusson/darkclippy/tree/master/SharedInterfaces): `SharedInterfaces`

### Other components

- **Visitor**
- **Ollama service**

## Connections

- Visitor → Chat page: views
- Visitor → Chat API: submits question
- ASP.NET app → Chat API: maps controllers
- ASP.NET app → Chat page: maps pages
- Chat page → Clippy assistant: loads assets
- Chat API → Request gate: checks request
- Request gate → Memory cache: reads and writes lock
- Chat API → Client factory: gets client
- Client factory → Memory cache: caches clients
- Client factory → Session chat client: creates client
- Chat API → Session chat client: requests response
- Session chat client → Chat history: updates context
- Session chat client → Semantic Kernel: requests completion
- Semantic Kernel → Ollama service: streams completion
- Chat API → Markdown rendering: converts response
- Markdown rendering → Visitor: returns HTML
- ASP.NET app → Connection validator: validates startup connection
- Connection validator → Service contracts: uses contracts
- Connection validator → Ping service
- Connection validator → TCP client factory
- TCP client factory → TCP client wrapper: creates client