Skip to content

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 ​

UnitResponsibility
HelpChatAI.TypesMessage and context records, cancellation token, retriever contract
HelpChatAI.MessagesLocalized strings (English, Italian, Spanish, French, German, Portuguese), chosen at runtime; see Languages
HelpChatAI.AssistantThe built-in icons of the assistant (the bubble, the header), from HelpChatAI.Assistant.res
HelpChatAI.IconsThe icons of providers and models and the flags of the languages, as inline SVG
HelpChatAI.LogThe log entry, the levels, the dispatcher every entry of the process goes through; see Logging
HelpChatAI.UiStateThe place of a bubble the user dragged, and the file of the UI state
HelpChatAI.CommandsThe slash commands: the set an application enables, and the answers of the engine-side ones
HelpChatAI.SettingsSettings, defaults in one place, JSON load/save, profiles, the catalogue of models, the two nodes of a secret
HelpChatAI.StoreThread-safe conversation store, pruning, persistence
HelpChatAI.RunnerWorker pool, cancellation, bounded and memory-safe shutdown
HelpChatAI.ProviderIHelpChatProvider, registry by name, stub; the system prompt, the tool-call record and the Source line every provider shares
HelpChatAI.Provider.SseThe stream an HTTP client writes into, cut into whole UTF-8 lines; each provider parses its own format
HelpChatAI.Provider.DocSearchDeterministic answers from the index
HelpChatAI.Provider.ClaudeAnthropic Messages API, SSE streaming, grounding, tool use
HelpChatAI.Provider.OpenAIOpenAI: the Responses API for OpenAI itself, Chat Completions for the services that speak it (Azure OpenAI, Groq, OpenRouter, Ollama...)
HelpChatAI.Provider.GeminiGoogle Gemini
HelpChatAI.DocIndexThe index and the keyword retriever (stemming, idf, excerpts, areas)
HelpChatAI.DocPagesA page of the documentation folder as safe HTML, for the documentation view of the panel
HelpChatAI.IndexBuilderMarkdown folder → index JSON
HelpChatAI.ActionsRegistry of actions, schema for the model, the queue to the host thread, the shared actions
HelpChatAI.SkillsThe registry of skills and the set a component attaches
HelpChatAI.Skills.ScreenThe four screen skills, written once over a screen a framework provides (RTL and Data.DB)
HelpChatAI.AttachmentsThe documents attached to a conversation, and the form each kind travels in
HelpChatAI.HtmlSafe Markdown → HTML, URL sanitizing, autolink, bubble fragments, the printable document
HelpChatAI.PdfPrinting that document to a PDF file (WebView2)
HelpChatAI.Diagnostics"Would this configuration work?": the check of the component editors and of /check
HelpChatAI.ConfigControllerThe rules of the design-time configuration editor, without a form
HelpChatAI.EngineThe facade: send, read, cancel, clear, render, persist; THelpChatEngines, the registry of one engine per profile
HelpChatAI.TransportIHelpChatTransport: 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.PanelThe panel page and the API contract
HelpChatAI.ThemeTHelpChatTheme: the colours as CSS variables, plus the stylesheet of the application
HelpChatAI.HelpViewerThe chat as a System.HelpIntfs viewer (shared by VCL and FMX)
HelpChatAI.ServerThe HTTP layer: sessions, routing, endpoints; the local server
HelpChatAI.Server.RemoteThe multi-session server
HelpChatAI.Server.HostChannelThe loopback channel a remote page reaches its host through
HelpChatAI.Transport.RemoteThe 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 ​

EndpointWhat it is for
GET /api/historyThe conversation as HTML fragments
POST /api/sendUser bubble + pending assistant bubble
GET /api/poll/{id}That bubble, still pending or complete
POST /api/cancel/{id}Stop a reply
POST /api/clearStart again
GET /api/doc?page=A page of the documentation folder, as safe HTML
POST /api/contextThe screen the user is on (from the native side)
POST /api/themeThe colours of the host, and its stylesheet, as CSS
POST /api/assistantThe name of the assistant and its icon, for the header
GET /api/commandsThe slash commands this panel enables (JSON)
POST /api/commandRuns an engine-side command; 403 for one that is not enabled
POST /api/command/logA command the page answered by itself, for the log
GET /api/assistantsThe models the panel may switch between, and the one in use (JSON)
POST /api/assistant/selectSwitches model; 403 when there is nothing to switch, and always on a remote server
GET /api/languagesThe languages offered, with their flags (JSON)
POST /api/language/selectSwitches the language of the chat; 403 on a remote server
POST /api/attachAttaches a file to the conversation (the bytes are the body)
GET /api/attachmentsWhat is attached (JSON)
POST /api/attach/removeDetaches one
POST /api/pdfAsks 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/close reaches 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 onWhat
Main threadThe components, the context, the theme, the action handlers
Worker poolProviders: the network call, the SSE parsing, the grounding
Indy threadsThe 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, ftp and 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.

Released under the Apache License 2.0