> For the complete documentation index, see [llms.txt](https://yvechat.gitbook.io/wp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yvechat.gitbook.io/wp/architecture.md).
# Architecture
Four layers. Each one held by the user.
Four layers: hosted interface, local connector, local runtimes, local data
***
### In plain language
YveChat has two halves.
The first half is a web page. It loads from a website, it draws the interface, and it holds nothing. It stores no conversations, keeps no models, and performs no thinking.
The second half is a small program called YveChat Engine that runs on your own computer. It finds the AI models installed on your machine, runs them when you ask a question, and saves your conversations to a file on your disk.
The web page and YveChat Engine are introduced to each other once, through a step called pairing. You approve that introduction yourself, on your own machine, by typing a six-digit code. From then on the page can ask YveChat Engine to do work.
The result is an interface that behaves like any website and a system where the thinking and the storage happen on hardware you own. When you use a local model, your question reaches no company at all.
Everything below describes that arrangement in detail.
***
### The Layers
| Layer | Held by | Function |
| ------------------ | ------------------------------- | ------------------------------------------------------------------------------- |
| **Workspace** | Rendered to the user | The interface: threads, model selection, tool activity, citations |
| **YveChat Engine** | The user's machine | Secrets, runtime discovery, provider normalization, tool execution |
| **Runtimes** | The user's hardware or accounts | Ollama, vLLM, and hosted provider endpoints |
| **Storage** | The user's own disk | A SQLite database holding conversations and settings, managed by YveChat Engine |
***
### Topology
```mermaid
graph TD
subgraph Hosted["Hosted by YveChat"]
W["Workspace interface app.yvechat.xyz"]
end
subgraph Machine["Your machine"]
B["YveChat Engine"]
O["Ollama localhost"]
V["vLLM localhost"]
S[("Local secrets and settings")]
end
subgraph Yours["Your infrastructure and accounts"]
D[("Self-hosted data")]
P["Provider APIs"]
end
W -->|"paired, origin-restricted"| B
B --> O
B --> V
B --> S
B --> D
B -->|"your keys"| P
```
The hosted origin renders the interface. Every secret, every prompt, and every model response passes through the Engine on the user's own machine.
***
### Technical Flow
| Step | Where it happens | What moves |
| ----------- | ------------------------------ | ------------------------------------------------------------------------ |
| 1. Sign in | Wallet, then workspace | A signature. No password, no account record |
| 2. Pair | Workspace to Engine | A one-time pairing that binds the Engine to the origin |
| 3. Discover | Engine to runtimes | Installed runtimes and available models |
| 4. Compose | Workspace | The prompt, held in the browser |
| 5. Route | Engine | The prompt goes to a local runtime, or to a provider with the user's key |
| 6. Stream | Runtime to Engine to workspace | Tokens, rendered as they arrive |
| 7. Persist | Engine to storage | The thread, written to the user's own infrastructure |
At no step does a prompt, an attachment, a model response, or a credential reach YveChat infrastructure.
***
### What each destination receives
| Destination | Receives | Never receives |
| -------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| **The static website host** | Requests for the interface files: HTML, JavaScript, CSS | Prompts, responses, model lists, images, conversation history, credentials, tool results |
| **YveChat Engine** | Your prompts, your conversations, your local profile, and any configured tool credentials | Nothing leaves it toward YveChat |
| **Ollama or ComfyUI** | The prompt text and generation parameters, over loopback on your machine | Anything beyond your machine |
| **A configured hosted provider** | The prompt and the response, under that provider's own terms, when you select one | Applies only once hosted-provider support ships. It is Planned |
| **Web-search services** | The search query text, when search is enabled for a conversation | Your conversation history and your prompts |
Hosted analytics are off by default and remain opt-in.
The single line worth remembering: the website host receives requests for files, and nothing else.
***
### What local execution costs you
Running a model on your own machine consumes your electricity, your memory, your storage, and your processing time. A long generation warms a laptop and drains its battery. Each model occupies gigabytes of disk for as long as you keep it.
Those costs are the substance of the arrangement. You supply the hardware and the compute, and in exchange the conversation stays yours.
***
### Without YveChat Engine
The hosted interface is a static browser application. A page served from the public internet cannot enumerate software running on your computer on its own, and browsers restrict such connections deliberately.
The hosted interface therefore shows an empty model list until YveChat Engine is installed, running, and paired. YveChat Engine is the mechanism that turns a web page into a sovereign workspace.
***
### Design Principles
| Principle | Application |
| ----------------------- | ----------------------------------------------------------------------------------------- |
| **Secrets stay local** | Credentials live in Engine-managed storage on the user's machine |
| **Provider neutrality** | A normalized layer treats every runtime as a peer, with capability negotiated per backend |
| **Explicit boundaries** | Actions that change state wait for confirmation. Reads disclose themselves |
| **Verifiable claims** | Every sovereignty property is observable in network traffic |
| **Honest degradation** | When a constraint blocks the ideal path, the product says so and offers the fallback |
***
### Why the Engine Exists
A hosted page alone cannot reliably reach local model servers across browsers. Three independent constraints make that true, and each is documented by the relevant vendor.
Ollama accepts cross-origin browser requests only from `127.0.0.1` and `0.0.0.0` unless the user manually configures `OLLAMA_ORIGINS`. Chrome now gates requests from public sites to loopback behind a user permission prompt. WebKit's loopback mixed-content behavior has been inconsistent, with a Safari 18 regression that blocked exactly this pattern.
The full case, with sources, is in [YveChat Engine](/wp/architecture/engine.md).
***
Interface in the browser.
Custody on the machine.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://yvechat.gitbook.io/wp/architecture.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.