Operator Web Console

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• webapp/chat/AGENTS.md
• webapp/static/index.html
• configs/agents/agents_config.json
• monGARS_structure.txt
• scripts/docker_menu.py

The Operator Web Console is a Django-based web application that serves as the primary user interface for interacting with the monGARS AI assistant. It provides a real-time chat interface, conversation management tools, and system diagnostics. The console is designed as a token-aware operator front-end that proxies authentication and chat functionalities to the core FastAPI service, ensuring a clear separation between the presentation layer and the backend cognitive services.

This architecture allows the web interface to be developed and deployed independently of the main AI engine. It leverages Django's asynchronous capabilities to handle communication efficiently, with a focus on progressive enhancement to ensure functionality even in JavaScript-light environments.

Sources: README.md, webapp/chat/AGENTS.md, configs/agents/agents_config.json

Architecture

The web console operates as an intermediary between the user's browser and the FastAPI backend. It does not contain core business logic but rather delegates requests to the main API, handling the user session and rendering the UI.

Sources: README.md, webapp/chat/AGENTS.md

High-Level Data Flow

The following diagram illustrates the overall interaction between the user, the Django webapp, and the FastAPI backend.

This diagram shows that the Django Webapp is the entry point for the user, and it communicates with the FastAPI backend to perform its functions.

Sources: README.md, webapp/chat/AGENTS.md

Backend (Django)

The Django backend is responsible for serving the HTML pages, handling user authentication against the FastAPI service, and proxying requests.

Sources: monGARS_structure.txt, webapp/chat/AGENTS.md

Views and Services

The application logic is split between asynchronous Django views and a dedicated services module.

• Views (views.py): These are kept lightweight and are primarily responsible for rendering templates. Authenticated routes are protected by a require_token decorator.
• Services (chat/services.py): This module is the core of the Django backend's functionality. It centralizes all outbound HTTP calls to the FastAPI backend. This design encapsulates logic for:
  • Authentication and token exchange.
  • Fetching chat history.
  • Requesting WebSocket tickets for real-time communication.
  • Implementing retries, error handling, and structured logging for all API interactions.

Sources: webapp/chat/AGENTS.md, configs/agents/agents_config.json

Authentication and Chat Sequence

The following diagram shows the sequence of events when a user sends a message.

This sequence illustrates how the Django app facilitates authentication and WebSocket connection setup between the user and the FastAPI server.

Sources: README.md, webapp/chat/AGENTS.md

Configuration

The Django application is configured through environment variables, which are consistent with the main application's settings.

Variable	Description	Default
WEBAPP_PORT	The host port for the Django web server.	8001
DJANGO_SECRET_KEY	The secret key for Django's cryptographic signing.	django-insecure-change-me
FASTAPI_URL	The base URL of the backend FastAPI service.	http://localhost:8000
DJANGO_ALLOWED_HOSTS	A comma-separated list of allowed hostnames.	localhost, 127.0.0.1, ...
WS_ALLOWED_ORIGINS	Comma-separated list of origins for WebSocket connections. Automatically synced with WEBAPP_PORT.	["http://localhost:8001", ...]

Sources: README.md, scripts/docker_menu.py:255-281

Frontend (HTML/JavaScript)

The frontend is a single-page application rendered by index.html, with dynamic functionality powered by JavaScript.

Sources: webapp/static/index.html

UI Components

The main chat interface is composed of several key HTML elements, each with a specific role.

ID / Selector	Description
#chat	The main card containing the entire chat interface.
#ws-status	A badge indicating the WebSocket connection status (Online/Offline).
#connection-diagnostics	A section displaying real-time metrics like latency and connection uptime.
#transcript	The container where chat messages are displayed.
#composer	The form used to write and send new messages.
#prompt	The textarea for user input.
#quick-actions	Buttons for predefined actions like "Code", "Summarize", and "Explain".
#chat-search	An input field to filter and search through the chat history.
#export-json, #export-markdown, #export-copy	Buttons to export the conversation in different formats.
#voice-controls	A section for voice recognition and speech synthesis controls.

Sources: webapp/static/index.html

Client-Side Logic (chat.js)

The client-side JavaScript (/static/js/chat.js) manages all user interactions and communication with the backend. Its responsibilities include:

• Establishing and maintaining the WebSocket connection.
• Displaying incoming messages in the #transcript area, using marked for Markdown rendering and DOMPurify for sanitization.
• Handling user input from the #composer form and sending it over the WebSocket.
• Updating the UI with connection status and diagnostic information.
• Implementing frontend features like dark mode, chat search, message exporting, and voice-to-text/text-to-speech.

The initial configuration, including the fastapiUrl, is passed from the HTML template to the JavaScript via a window.chatConfig object.

<!-- webapp/static/index.html:198-204 -->
<script>
  window.chatConfig = {
    fastapiUrl: window.location.origin,
    embedServiceUrl: null,
    token: null
  };
</script>

Sources: webapp/static/index.html:198-214