# johnny-alvarado/ts-expert architecture

> Architecture diagram of the GitHub repository johnny-alvarado/ts-expert, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/johnny-alvarado/ts-expert
- Repository: https://github.com/johnny-alvarado/ts-expert

## Overview

1. **Overall shape**
   - TS Expert is a **single-machine, locally hosted** application with three main layers: a **browser UI**, a **FastAPI backend**, and **local industrial/AI services** it brokers to.
   - The architecture is centered on a chat loop that can call tools, retrieve manuals, and stream responses back to the UI.

2. **Frontend boundary**
   - The `frontend/` folder is a **static web client**: `index.html` for the main assistant, `login.html` for authentication, and vanilla JS in `frontend/js/` for app logic and API calls.
   - `i18n.js` plus `frontend/lang/en.json` and `es.json` provide a **bilingual UI boundary** without server-side rendering.
   - The UI also handles **markdown rendering** and **tool-call visualization**, so the backend can return structured assistant output and streamed events.

3. **Backend entry point**
   - `backend/main.py` is the **FastAPI application** and the central HTTP boundary.
   - It likely serves the static frontend, exposes chat/auth/API endpoints, and coordinates all backend subsystems.
   - `uvicorn` is the runtime, so the app is an ASGI service rather than a separate worker topology.

4. **Authentication and session boundary**
   - `backend/auth.py` implements **JWT-based login** with local password verification, using `bcrypt` and `python-jose`.
   - The auth layer separates the browser from the chat/API functionality: users authenticate through the login page, then present tokens to access the assistant and operational tools.
   - This is a local-user model, not an external identity provider.

5. **LLM orchestration**
   - `backend/llm_router.py` is the **model-routing layer**.
   - The primary model is **Gemma 4 via Ollama**, fully local; `litellm` provides the abstraction.
   - There is an **optional OpenAI fallback**, which is an explicit boundary between local-first operation and external cloud dependency.

6. **Tool execution and industrial control**
   - `backend/tools.py` and `backend/mcp_client.py` form the **agent/tooling subsystem**.
   - The backend connects over **MCP stdio transport** to a separate TOP Server/Kepware MCP server process.
   - This is the key operational boundary: the assistant does not talk directly to OPC servers; it goes through MCP tools that encapsulate management, read/write tag access, and related industrial operations.

7. **Retrieval-Augmented Generation**
   - `backend/rag.py` provides **manual search over TOP Server documentation**.
   - The readme indicates **ChromaDB** as the vector store and `sentence-transformers` for embeddings, with `pdfplumber` used during ingestion.
   - This creates a separate knowledge path: user questions can be answered from indexed manuals rather than only from the model’s parametric knowledge.

8. **Streaming response flow**
   - `backend/streaming.py` handles **incremental response delivery**, likely via SSE or a similar event stream.
   - This matters because the assistant can emit partial tokens, tool-call updates, and progress events to the frontend instead of waiting for a single final response.
   - The UI therefore has a real-time conversational feel and can show intermediate agent activity.

9. **Document ingestion pipeline**
   - `ingest_docs.py` is an **offline indexing job** that turns TOP Server PDF manuals into the RAG corpus.
   - This is separate from the live chat runtime: ingestion prepares the knowledge base, while `rag.py` serves it during queries.
   - The docs folder is therefore an input source for the retrieval subsystem, not part of the request path.

10. **Configuration and runtime packaging**
   - `backend/config.py` and `.env.template` define the **deployment/config boundary**: model names, credentials, local service addresses, and feature flags.
   - `requirements.txt` shows a Python-first stack, and `start.ps1` plus `gen_cert.py` suggest Windows-oriented startup and optional HTTPS setup.
   - `gen_password.py` is a provisioning utility for creating the stored password hash.

11. **External dependencies that materially shape the design**
   - **Ollama** is the local model runtime.
   - **TOP Server / Kepware + MCP server** is the industrial integration endpoint.
   - **ChromaDB** and **sentence-transformers** support manual retrieval.
   - **OpenAI** is not core, but acts as a fallback path if local inference is unavailable.

12. **End-to-end request path**
   - A typical chat request flows: **browser UI → authenticated FastAPI endpoint → LLM router**.
   - The router may invoke **RAG** for manual grounding and **MCP tools** for live OPC/server operations.
   - The backend then returns results to the browser through the **streaming layer**, where the frontend renders the assistant reply, citations/tool activity, and any multilingual text.

Main entry points: [`backend/main.py`](https://github.com/johnny-alvarado/ts-expert/blob/main/backend/main.py) (API server), [`backend/llm_router.py`](https://github.com/johnny-alvarado/ts-expert/blob/main/backend/llm_router.py) (Model router), [`frontend/js/app.js`](https://github.com/johnny-alvarado/ts-expert/blob/main/frontend/js/app.js) (App logic), [`frontend/js/i18n.js`](https://github.com/johnny-alvarado/ts-expert/blob/main/frontend/js/i18n.js) (i18n layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser UI"]
  node_ui_shell["Main app<br/>static chat UI<br/>[index.html]"]
  node_login_page["Login page<br/>auth UI<br/>[login.html]"]
  node_ui_app["App logic<br/>client runtime<br/>[app.js]"]
  node_ui_api["API client<br/>browser API layer<br/>[api.js]"]
  node_ui_i18n["i18n layer<br/>bilingual UI<br/>[i18n.js]"]
  node_en_locale["English copy<br/>locale bundle<br/>[en.json]"]
  node_es_locale["Spanish copy<br/>locale bundle<br/>[es.json]"]
end

subgraph group_backend["FastAPI backend"]
  node_api_main["API server<br/>FastAPI app<br/>[main.py]"]
  node_auth_layer["Auth<br/>JWT login<br/>[auth.py]"]
  node_config_layer["Config<br/>[config.py]"]
  node_llm_router["Model router<br/>LLM orchestration<br/>[llm_router.py]"]
  node_rag_layer["Manual search<br/>RAG retrieval<br/>[rag.py]"]
  node_tools_layer["Tool runtime<br/>agent tools<br/>[tools.py]"]
  node_mcp_client["MCP client<br/>stdio bridge<br/>[mcp_client.py]"]
  node_stream_layer["Streaming<br/>event stream<br/>[streaming.py]"]
end

subgraph group_ops["Local integrations"]
  node_ingest_job["Doc ingest<br/>offline indexing<br/>[ingest_docs.py]"]
  node_password_gen["Password gen<br/>provisioning utility<br/>[gen_password.py]"]
  node_cert_gen["Cert gen<br/>https utility<br/>[gen_cert.py]"]
  node_deps["Python deps<br/>package manifest<br/>[requirements.txt]"]
end

node_ui_shell -->|"loads"| node_ui_app
node_login_page -->|"auth flow"| node_ui_api
node_ui_app -->|"calls"| node_ui_api
node_ui_app -->|"localizes"| node_ui_i18n
node_ui_i18n -->|"loads"| node_en_locale
node_ui_i18n -->|"loads"| node_es_locale
node_ui_api -->|"requests"| node_api_main
node_api_main -->|"verifies"| node_auth_layer
node_api_main -->|"routes chat"| node_llm_router
node_api_main -->|"retrieves"| node_rag_layer
node_api_main -->|"executes tools"| node_tools_layer
node_api_main -->|"streams"| node_stream_layer
node_llm_router -->|"grounds"| node_rag_layer
node_llm_router -->|"tool calls"| node_tools_layer
node_tools_layer -->|"bridges"| node_mcp_client
node_rag_layer -->|"indexes"| node_ingest_job
node_auth_layer -->|"reads"| node_config_layer
node_llm_router -->|"reads"| node_config_layer
node_api_main -->|"reads"| node_config_layer
node_ingest_job -->|"uses"| node_deps
node_api_main -->|"runs on"| node_deps
node_password_gen -.->|"supports"| node_auth_layer
node_cert_gen -.->|"supports"| node_api_main

click node_ui_shell "https://github.com/johnny-alvarado/ts-expert/blob/main/frontend/index.html"
click node_login_page "https://github.com/johnny-alvarado/ts-expert/blob/main/frontend/login.html"
click node_ui_app "https://github.com/johnny-alvarado/ts-expert/blob/main/frontend/js/app.js"
click node_ui_api "https://github.com/johnny-alvarado/ts-expert/blob/main/frontend/js/api.js"
click node_ui_i18n "https://github.com/johnny-alvarado/ts-expert/blob/main/frontend/js/i18n.js"
click node_en_locale "https://github.com/johnny-alvarado/ts-expert/blob/main/frontend/lang/en.json"
click node_es_locale "https://github.com/johnny-alvarado/ts-expert/blob/main/frontend/lang/es.json"
click node_api_main "https://github.com/johnny-alvarado/ts-expert/blob/main/backend/main.py"
click node_auth_layer "https://github.com/johnny-alvarado/ts-expert/blob/main/backend/auth.py"
click node_config_layer "https://github.com/johnny-alvarado/ts-expert/blob/main/backend/config.py"
click node_llm_router "https://github.com/johnny-alvarado/ts-expert/blob/main/backend/llm_router.py"
click node_rag_layer "https://github.com/johnny-alvarado/ts-expert/blob/main/backend/rag.py"
click node_tools_layer "https://github.com/johnny-alvarado/ts-expert/blob/main/backend/tools.py"
click node_mcp_client "https://github.com/johnny-alvarado/ts-expert/blob/main/backend/mcp_client.py"
click node_stream_layer "https://github.com/johnny-alvarado/ts-expert/blob/main/backend/streaming.py"
click node_ingest_job "https://github.com/johnny-alvarado/ts-expert/blob/main/ingest_docs.py"
click node_password_gen "https://github.com/johnny-alvarado/ts-expert/blob/main/gen_password.py"
click node_cert_gen "https://github.com/johnny-alvarado/ts-expert/blob/main/gen_cert.py"
click node_deps "https://github.com/johnny-alvarado/ts-expert/blob/main/requirements.txt"

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_ui_shell,node_login_page,node_ui_app,node_ui_api,node_ui_i18n,node_en_locale,node_es_locale toneBlue
class node_api_main,node_auth_layer,node_config_layer,node_llm_router,node_rag_layer,node_tools_layer,node_mcp_client,node_stream_layer toneAmber
class node_ingest_job,node_password_gen,node_cert_gen,node_deps toneMint
```

## Components

### Browser UI

Static client for login, chat, language switching, and rendering streamed assistant output.

- [Main app](https://github.com/johnny-alvarado/ts-expert/blob/main/frontend/index.html): static chat UI · Primary browser entry for the assistant experience. · `frontend/index.html`
- [Login page](https://github.com/johnny-alvarado/ts-expert/blob/main/frontend/login.html): auth UI · Dedicated browser login surface for local users. · `frontend/login.html`
- [App logic](https://github.com/johnny-alvarado/ts-expert/blob/main/frontend/js/app.js): client runtime · Front-end behavior for chat, API calls, and interaction flow. · `frontend/js/app.js`
- [API client](https://github.com/johnny-alvarado/ts-expert/blob/main/frontend/js/api.js): browser API layer · Client-side request wrapper for backend communication. · `frontend/js/api.js`
- [i18n layer](https://github.com/johnny-alvarado/ts-expert/blob/main/frontend/js/i18n.js): bilingual UI · Language selection and locale text loading for the client. · `frontend/js/i18n.js`
- [English copy](https://github.com/johnny-alvarado/ts-expert/blob/main/frontend/lang/en.json): locale bundle · English UI strings and labels. · `frontend/lang/en.json`
- [Spanish copy](https://github.com/johnny-alvarado/ts-expert/blob/main/frontend/lang/es.json): locale bundle · Spanish UI strings and labels. · `frontend/lang/es.json`

### FastAPI backend

Central HTTP and orchestration layer for auth, chat, retrieval, tools, and streaming.

- [API server](https://github.com/johnny-alvarado/ts-expert/blob/main/backend/main.py): FastAPI app · Main HTTP boundary for static assets and backend endpoints. · `backend/main.py`
- [Auth](https://github.com/johnny-alvarado/ts-expert/blob/main/backend/auth.py): JWT login · Local authentication and token verification boundary. · `backend/auth.py`
- [Config](https://github.com/johnny-alvarado/ts-expert/blob/main/backend/config.py): runtime config · Deployment settings, feature flags, and service addresses. · `backend/config.py`
- [Model router](https://github.com/johnny-alvarado/ts-expert/blob/main/backend/llm_router.py): LLM orchestration · Chooses and mediates between local and fallback model paths. · `backend/llm_router.py`
- [Manual search](https://github.com/johnny-alvarado/ts-expert/blob/main/backend/rag.py): RAG retrieval · Retrieves grounded answers from indexed TOP Server documentation. · `backend/rag.py`
- [Tool runtime](https://github.com/johnny-alvarado/ts-expert/blob/main/backend/tools.py): agent tools · Executes assistant tool calls for operational actions. · `backend/tools.py`
- [MCP client](https://github.com/johnny-alvarado/ts-expert/blob/main/backend/mcp_client.py): stdio bridge · Connects the backend to the external MCP server process. · `backend/mcp_client.py`
- [Streaming](https://github.com/johnny-alvarado/ts-expert/blob/main/backend/streaming.py): event stream · Incremental delivery of tokens, tool events, and progress updates. · `backend/streaming.py`

### Local integrations

Offline indexing, runtime configuration, and local service dependencies that shape the system.

- [Doc ingest](https://github.com/johnny-alvarado/ts-expert/blob/main/ingest_docs.py): offline indexing · Builds the retrieval corpus from PDF manuals. · `ingest_docs.py`
- [Password gen](https://github.com/johnny-alvarado/ts-expert/blob/main/gen_password.py): provisioning utility · Creates stored password hashes for local auth setup. · `gen_password.py`
- [Cert gen](https://github.com/johnny-alvarado/ts-expert/blob/main/gen_cert.py): https utility · Optional local certificate generation for secured startup. · `gen_cert.py`
- [Python deps](https://github.com/johnny-alvarado/ts-expert/blob/main/requirements.txt): package manifest · Runtime dependency set for the backend and supporting jobs. · `requirements.txt`

## Connections

- Main app → App logic: loads · Main page boots the client application.
- Login page → API client: auth flow · Login page submits credentials through the client API layer.
- App logic → API client: calls · Chat and app actions use backend APIs.
- App logic → i18n layer: localizes · Client text is resolved through the i18n layer.
- i18n layer → English copy: loads · English strings are one locale source.
- i18n layer → Spanish copy: loads · Spanish strings are one locale source.
- API client → API server: requests · Browser traffic terminates at the FastAPI server.
- API server → Auth: verifies · Protected endpoints validate local JWT sessions.
- API server → Model router: routes chat · Chat requests are handed to the model orchestration layer.
- API server → Manual search: retrieves · Server can ground answers in indexed manuals.
- API server → Tool runtime: executes tools · Assistant actions are dispatched through the tool subsystem.
- API server → Streaming: streams · Responses are delivered incrementally to the browser.
- Model router → Manual search: grounds · Model routing can incorporate retrieved context.
- Model router → Tool runtime: tool calls · Model decisions may invoke operational tools.
- Tool runtime → MCP client: bridges · Tool execution goes through the MCP stdio transport.
- Manual search → Doc ingest: indexes · Offline ingestion populates the retrieval corpus.
- Auth → Config: reads · Auth behavior depends on configured secrets and policy.
- Model router → Config: reads · Model selection and provider settings come from config.
- API server → Config: reads · Server startup and feature wiring depend on configuration.
- Doc ingest → Python deps: uses · Offline indexing relies on the same Python dependency set.
- API server → Python deps: runs on · Backend runtime is defined by the package requirements.
- Password gen → Auth: supports · Provisioning utility supports local auth setup.
- Cert gen → API server: supports · Certificate utility supports secure local deployment.
