System Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:monGARS (Modular Neural Guardian for Autonomous Research & Support) is a privacy-first AI assistant architected for modularity and resilient deployment across diverse environments, from edge devices to research clusters. The system is composed of several loosely-coupled services, including a FastAPI backend, a core cognition pipeline, a Django-based operator console, and optional modules for machine learning and self-improvement tasks. This design allows for independent development, deployment, and scaling of its constituent parts.
The architecture emphasizes clear separation of concerns, hardware-aware performance tuning, and a robust self-improvement loop. Configuration is centralized, and development standards are enforced through a system of AGENTS.md charter files, which are automatically generated and maintained to ensure consistency across the codebase.
Sources: README.md:7-11, AGENTS.md:3-8
Core Components
The monGARS system is divided into distinct, cooperative components, each with a specific set of responsibilities. This modular structure is reflected in the repository's file layout.
Sources: README.md:43-52, monGARS_structure.txt
Component Interaction
The following diagram illustrates the high-level interactions between the primary services of the monGARS platform.
This diagram shows the Django webapp acting as a client to the FastAPI service, which in turn orchestrates the core cognition and optional ML modules. Data persistence is handled by PostgreSQL and Redis, while external services like Ollama/Ray Serve provide LLM inference capabilities.
Sources: README.md:43-52, configs/agents/agents_config.json:70-90
Service Breakdown
The responsibilities of each major component are summarized below.
| Component | Location | Responsibilities |
|---|---|---|
| FastAPI service | monGARS/api | Handles authentication (OAuth2), REST/WebSocket endpoints, dependency injection, and routing requests to the core engine. |
| Cognition core | monGARS/core | Manages memory (Hippocampus), reasoning, LLM integration (Ollama/Ray Serve), and adaptive response generation. |
| Evolution modules | modules/ | Contains optional systems for ML model adapter training, diagnostics, self-improvement, and research tooling. Designed to degrade gracefully if heavy dependencies are absent. |
| Django UI | webapp/ | Provides an operator-facing chat console that acts as a token-aware proxy to the FastAPI backend. |
| Persistence | init_db.py, monGARS/core/persistence.py | Defines SQLModel schemas for PostgreSQL, manages the Hippocampus caching layer, and handles Redis/disk-based state. |
| Tooling | scripts/, k8s/ | Includes automation scripts for deployment (docker_menu.py), agent management (manage_agents.py), and Kubernetes manifests. |
Sources: README.md:96-104, monGARS_structure.txt
Data and Persistence Layer
monGARS utilizes a multi-tiered persistence strategy to balance performance and durability.
- PostgreSQL: The primary database for persistent storage, managed via SQLModel and Alembic for migrations. It stores user accounts, conversation history, and personality profiles.
- Redis: Used as a high-speed caching layer.
- In-Memory
Hippocampus: A short-term memory store for conversational context. - Disk Snapshots: Stores ML model artifacts, such as LoRA adapters, which are managed by the Evolution Engine.
Sources: README.md:16-17, 51-52, monGARS/AGENTS.md:50-52
The following diagram shows the relationship between the different data stores.
Core Workflows
The architecture supports several key operational workflows, from handling a single conversational turn to long-term self-improvement.
Conversational Pipeline
A user request is processed through a multi-stage pipeline within the ConversationalModule to enrich the query and generate an adaptive response.
This flow ensures that each response is context-aware, potentially enriched with external research, and tailored to the user's personality before being persisted and sent.
Sources: README.md:56-62, scripts/generate_monGARS_llm_dataset.py:440-457
Evolution & Self-Training Loop
The Evolution Engine facilitates the system's self-improvement by periodically retraining model adapters based on collected data and system metrics.
This loop enables monGARS to adapt and optimize its performance and behavior over time without manual intervention, using real-world interaction data. Heavy dependencies like Torch are gated behind runtime checks to allow the system to function without the full ML toolchain.
Sources: README.md:65-72, modules/AGENTS.md:32-35
Django UI to FastAPI Communication
The operator console is a Django application that securely interacts with the main FastAPI backend. It does not directly handle business logic but rather proxies requests.
This sequence shows how webapp/chat/services.py manages token exchange and ticket acquisition to bootstrap a secure WebSocket connection for the chat interface.
Sources: README.md:79-84, monGARS/api/AGENTS.md:28-32
Configuration Management
Configuration is loaded from environment variables and .env files, and accessed throughout the application via a centralized, cached function monGARS.config.get_settings(). This ensures consistency across services.
Sources: AGENTS.md:58-59
Key Configuration Variables
| Setting | Description | Default | Source |
|---|---|---|---|
SECRET_KEY | JWT signing and Fernet encryption key. | - | README.md |
API_PORT / WEBAPP_PORT | Host ports for FastAPI and Django services. | 8000 / 8001 | README.md |
USE_RAY_SERVE | Toggles distributed inference via Ray Serve. | false | README.md |
RAY_SERVE_URL | The HTTP endpoint for the Ray Serve deployment. | http://rayserve:8000/generate | README.md |
DATABASE_URL | Connection string for the PostgreSQL database. | - | README.md |
REDIS_URL | Connection string for the Redis cache. | - | README.md |
RAG_ENABLED | Toggles repository-aware RAG enrichment for chat. | false | README.md |
WS_ALLOWED_ORIGINS | Comma-separated list of allowed WebSocket origins. | - | README.md |
TRAINING_PIPELINE_ENABLED | Controls whether the background evolution training workflow runs. | false | README.md |
Sources: README.md:143-180
Development Standards & AGENTS.md
A unique aspect of the monGARS architecture is its use of AGENTS.md files throughout the repository. These are auto-generated markdown files that act as "charters" or "contracts" for their respective directories.
- Purpose: They define scope, responsibilities, development rules, and roadmap alignment for each component.
- Source of Truth: All
AGENTS.mdfiles are generated from a central JSON configuration file:configs/agents/agents_config.json. - Automation: The
scripts/manage_agents.pyscript is used torefreshexisting files orcreatenew ones, ensuring that documentation and development standards stay in sync with the central configuration and project roadmap.
This system enforces architectural consistency and provides developers with clear, scoped guidelines for contributing to any part of the project.
Sources: AGENTS.md:5-12, configs/agents/agents_config.json:1-20, scripts/manage_agents.py
Conclusion
The monGARS system architecture is intentionally designed to be modular, extensible, and resilient. By separating the API surface, cognitive core, and optional ML modules, the platform can be adapted for various deployment targets and use cases. Key workflows like the conversational pipeline and the self-training loop are clearly defined, and a unique, automated system of AGENTS.md files ensures that development practices remain consistent with the architectural vision. The multi-layered persistence and caching strategy provides a balance of performance and data integrity, supporting both real-time interaction and long-term evolution.
Sources: README.md:7-11, 43-52