How johnny-alvarado/ts-expert works
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: main.py API server · llm_router.py Model router · app.js App logic · i18n.js i18n layer
Components 19
Browser UI
Static client for login, chat, language switching, and rendering streamed assistant output.
- Main app · Primary browser entry for the assistant experience.
frontend/index.html - Login page · Dedicated browser login surface for local users.
frontend/login.html - App logic · Front-end behavior for chat, API calls, and interaction flow.
frontend/js/app.js - API client · Client-side request wrapper for backend communication.
frontend/js/api.js - i18n layer · Language selection and locale text loading for the client.
frontend/js/i18n.js - English copy · English UI strings and labels.
frontend/lang/en.json - Spanish copy · 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 · Main HTTP boundary for static assets and backend endpoints.
backend/main.py - Auth · Local authentication and token verification boundary.
backend/auth.py - Config · Deployment settings, feature flags, and service addresses.
backend/config.py - Model router · Chooses and mediates between local and fallback model paths.
backend/llm_router.py - Manual search · Retrieves grounded answers from indexed TOP Server documentation.
backend/rag.py - Tool runtime · Executes assistant tool calls for operational actions.
backend/tools.py - MCP client · Connects the backend to the external MCP server process.
backend/mcp_client.py - Streaming · 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 · Builds the retrieval corpus from PDF manuals.
ingest_docs.py - Password gen · Creates stored password hashes for local auth setup.
gen_password.py - Cert gen · Optional local certificate generation for secured startup.
gen_cert.py - Python deps · Runtime dependency set for the backend and supporting jobs.
requirements.txt
Connections 23
- 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.