Architecture
You do not need this page to use HelpChatAI. Read it if you want to extend it, host the engine yourself, or understand why a chat panel talks to its own application over HTTP. To follow one question through these parts, step by step, read In depth: anatomy of a conversation; for the page in the browser - htmx, the window.hc* functions, the theme and your own CSS - read Inside the panel.
Three ideas
1. The engine knows nothing about the UI or the web. Providers, index, scoring, the conversation store and the Markdown conversion are plain Pascal with no Vcl.*, FMX.*, Indy or WebView unit in sight. That is why the same engine serves a VCL application, an FMX one, a console program and a server.
Since 1.7 it is also why a component does not create its engine: it asks a registry (THelpChatEngines.Acquire) for the engine of its Profile, and every component of that profile - two instances of the same form, say - gets the same one, freed by the last Release. The index is loaded once and the conversation is one. The engine runs on a copy of the settings of the first component that asked; what the user changes in the panel (the model, the language) is written on that copy, which the components read as RunSettings. The actions are not the engine's: each component gives its own to its transport, and they travel with every question, so an action runs in the window it was asked from. See Assistants and models.
2. Nothing waits on the model. Send records the question, creates a pending assistant message and returns immediately; a worker pool fills it in. A remote model call lasts seconds and never runs on the UI thread. Shutdown waits with a timeout and detaches a stuck worker rather than freezing the application — a detached worker can never touch a freed store.
3. Streaming needs no push channel. Tokens are appended to the pending message in the store; whoever reads the store — the polling page, a UI event — sees the partial grow. No WebSocket, no server-sent events towards the page, nothing to keep alive.
The units
| Unit | Responsibility |
|---|---|
HelpChatAI.Types | Message and context records, cancellation token, retriever contract |
HelpChatAI.Messages | Localized strings (English, Italian, Spanish, French, German, Portuguese), chosen at runtime; see Languages |
HelpChatAI.Assistant | The built-in icons of the assistant (the bubble, the header), from HelpChatAI.Assistant.res |
HelpChatAI.Icons | The icons of providers and models and the flags of the languages, as inline SVG |
HelpChatAI.Log | The log entry, the levels, the dispatcher every entry of the process goes through; see Logging |
HelpChatAI.UiState | The place of a bubble the user dragged, and the file of the UI state |
HelpChatAI.Commands | The slash commands: the set an application enables, and the answers of the engine-side ones |
HelpChatAI.Settings | Settings, defaults in one place, JSON load/save, profiles, the catalogue of models, the two nodes of a secret |
HelpChatAI.Store | Thread-safe conversation store, pruning, persistence |
HelpChatAI.Runner | Worker pool, cancellation, bounded and memory-safe shutdown |
HelpChatAI.Provider | IHelpChatProvider, registry by name, stub; the system prompt, the tool-call record and the Source line every provider shares |
HelpChatAI.Provider.Sse | The stream an HTTP client writes into, cut into whole UTF-8 lines; each provider parses its own format |
HelpChatAI.Provider.DocSearch | Deterministic answers from the index |
HelpChatAI.Provider.Claude | Anthropic Messages API, SSE streaming, grounding, tool use |
HelpChatAI.Provider.OpenAI | OpenAI: the Responses API for OpenAI itself, Chat Completions for the services that speak it (Azure OpenAI, Groq, OpenRouter, Ollama...) |
HelpChatAI.Provider.Gemini | Google Gemini |
HelpChatAI.DocIndex | The index and the keyword retriever (stemming, idf, excerpts, areas) |
HelpChatAI.DocPages | A page of the documentation folder as safe HTML, for the documentation view of the panel |
HelpChatAI.IndexBuilder | Markdown folder → index JSON |
HelpChatAI.Actions | Registry of actions, schema for the model, the queue to the host thread, the shared actions |
HelpChatAI.Skills | The registry of skills and the set a component attaches |
HelpChatAI.Skills.Screen | The four screen skills, written once over a screen a framework provides (RTL and Data.DB) |
HelpChatAI.Attachments | The documents attached to a conversation, and the form each kind travels in |
HelpChatAI.Html | Safe Markdown → HTML, URL sanitizing, autolink, bubble fragments, the printable document |
HelpChatAI.Pdf | Printing that document to a PDF file (WebView2) |
HelpChatAI.Diagnostics | "Would this configuration work?": the check of the component editors and of /check |
HelpChatAI.ConfigController | The rules of the design-time configuration editor, without a form |
HelpChatAI.Engine | The facade: send, read, cancel, clear, render, persist; THelpChatEngines, the registry of one engine per profile |
HelpChatAI.Transport | IHelpChatTransport: what a component asks for the panel URL, and where it puts what belongs to one panel (context, theme, name and icon, commands, actions) |
HelpChatAI.Panel | The panel page and the API contract |
HelpChatAI.Theme | THelpChatTheme: the colours as CSS variables, plus the stylesheet of the application |
HelpChatAI.HelpViewer | The chat as a System.HelpIntfs viewer (shared by VCL and FMX) |
HelpChatAI.Server | The HTTP layer: sessions, routing, endpoints; the local server |
HelpChatAI.Server.Remote | The multi-session server |
HelpChatAI.Server.HostChannel | The loopback channel a remote page reaches its host through |
HelpChatAI.Transport.Remote | The client of a HelpChatAI server |
Vcl.HelpChatAI*, FMX.HelpChatAI* | The components, the chat control, the bubble, the confirmation dialog, the screen of the skills; in the VCL also the style theming and the voice input |
They are grouped in packages: HelpChatAI (the engine: RTL, Data.DB for the screen skills and the MarkdownProcessor package, no UI framework - the units above from HelpChatAI.Types to HelpChatAI.HelpViewer, the skills included), HelpChatAIServer (HelpChatAI.Server, its two companions and HelpChatAI.Transport.Remote, on Indy), HelpChatAIVcl and HelpChatAIFmx (the components), and the design packages dclHelpChatAIVcl and dclHelpChatAIFmx (registration, the configuration editor, the design-time preview).
How the panel talks to the engine
| Endpoint | What it is for |
|---|---|
GET /api/history | The conversation as HTML fragments |
POST /api/send | User bubble + pending assistant bubble |
GET /api/poll/{id} | That bubble, still pending or complete |
POST /api/cancel/{id} | Stop a reply |
POST /api/clear | Start again |
GET /api/doc?page= | A page of the documentation folder, as safe HTML |
POST /api/context | The screen the user is on (from the native side) |
POST /api/theme | The colours of the host, and its stylesheet, as CSS |
POST /api/assistant | The name of the assistant and its icon, for the header |
GET /api/commands | The slash commands this panel enables (JSON) |
POST /api/command | Runs an engine-side command; 403 for one that is not enabled |
POST /api/command/log | A command the page answered by itself, for the log |
GET /api/assistants | The models the panel may switch between, and the one in use (JSON) |
POST /api/assistant/select | Switches model; 403 when there is nothing to switch, and always on a remote server |
GET /api/languages | The languages offered, with their flags (JSON) |
POST /api/language/select | Switches the language of the chat; 403 on a remote server |
POST /api/attach | Attaches a file to the conversation (the bytes are the body) |
GET /api/attachments | What is attached (JSON) |
POST /api/attach/remove | Detaches one |
POST /api/pdf | Asks the host to save an answer, the conversation or a page as PDF; 403 when PDF is off, 501 where no host can |
POST /api/ui/{command} | What the page asks of its host (close, mic-start, mic-stop, reload); the server raises language and model to the same host |
The two paths of the models say "assistant" because that is what a model was called before 1.7, and they kept their names; the assistant is now the profile, which no endpoint switches.
Every /api/* call carries X-HelpChat-Token: <secret>, generated for each session; only the panel page knows it, because it receives it in its URL. For the conversation the server answers HTML fragments, not JSON: htmx swaps them into the page, which is why the page has little rendering code. The lists the page builds its menus from - commands, models, languages, attachments - are JSON.
Each panel has a session on the server: its secret, its screen context, its theme, the name and icon of its assistant, its enabled commands and its actions. The engine behind may be shared by several panels; the session is what makes a question carry the context and the actions of the window it was asked from.
The screen context never travels through the page: the component computes it natively and hands it to the transport. A page cannot forge it and cannot lose it.
Why the page calls its host over HTTP
The page must sometimes ask the application for something — "close me", "start the microphone". WebView2 has a message bridge, but FireMonkey exposes none, and a page served by a remote server has no native side at all. One mechanism works everywhere: an HTTP call to somebody who is listening.
- Local engine: that is the same server, and
/api/ui/closereaches the component. - Remote engine: the client opens a small listener on
127.0.0.1— the host channel — and the server tells the page where it is. CORS is limited to the panel origin, the channel has its own secret, and the browser's private-network preflight is answered.
The same channel is where file exchange between page and application will live.
Threads
| Runs on | What |
|---|---|
| Main thread | The components, the context, the theme, the action handlers |
| Worker pool | Providers: the network call, the SSE parsing, the grounding |
| Indy threads | The HTTP requests of the page |
The store is thread-safe and is the meeting point. OnMessageChanged fires on the thread that changed the message — a UI layer must marshal it; the polling page does not care.
An action crosses the boundary in the other direction: a provider on a worker asks for something that must run on the main thread, and waits with a timeout while honouring cancellation. An engine may outlive the window that asked, so the broker of a component that was deactivated answers "cancelled" at once (HostActive) instead of running the action on a form that is being closed.
Security boundaries
- Model output is untrusted content: rendered through safe-mode Markdown with active HTML escaped, URL schemes restricted to
http(s),mailto,ftpand relative paths, and a Content-Security-Policy on the page. - The browser is confined to the exact origin of the panel (scheme, host and port, not an address that merely starts the same way): any other navigation is cancelled and opened in the system browser.
- The local server binds 127.0.0.1 only and requires the per-process secret.
More in Security and privacy.