How mode1943/security-operations-agent works
1. Overall shape
This repo is a three-part system: a FastAPI backend that contains the business logic and AI orchestration, a Vue 3 + Element Plus admin console for operations, and two browser-side delivery artifacts (ai-chat and anzai-gateway-embed) used to surface the assistant in client or gateway contexts.
2. Backend is the central control plane
backend/app/main.py bootstraps the API, middleware, logging, dependency wiring, and router registration. The backend is split by domain into routers such as auth, users, sites, files, plugins, agent, nl2sql, text2viz, audit, system, and certificates. This is the primary boundary between UI/client entry points and server-side capabilities.
3. Frontend is an admin console, not the AI runtime
frontend/ is a management SPA built with Vue 3. It provides pages for login, dashboards, site list, file repositories, plugin libraries, auth profiles, audit logs, system settings, certificates, and user management. It talks to the backend over HTTP, with Nginx packaging the app and proxying /api to the backend in deployment.
4. Core data stores and persistence
The backend persists operational data in MySQL in the normal deployment, with SQLite supported for local development. The database layer is organized through SQLAlchemy models and migration/bootstrap utilities. Uploaded files are stored on disk under the configured upload directory rather than in the database. This makes the architecture a mix of relational state plus filesystem-based artifacts.
5. Agent orchestration is the main intelligence path
The agent flow combines:
- intent routing
- prompt templates
- RAG context injection
- plugin/tool calls
- chat history persistence
The agent-related code is split across prompt definitions, LLM service/config, plugin execution/retrieval, and the agent router. From an architecture perspective, this is the key “reasoning pipeline” that turns a user question into a grounded answer or action.
6. RAG is a standalone subsystem
The backend/app/rag/ package is its own pipeline with clear stages: extract → chunk → embed → ingest → retrieve. Files flow into this subsystem from the file repository feature, get normalized into chunks, converted to embeddings, and later retrieved as context for agent prompts. The tests around RAG and file retrieval show it is treated as a core product capability, not an add-on.
7. Plugin library provides external action execution
The plugin subsystem handles HTTP-based tools that the agent can invoke automatically. The repo includes plugin import support, retrieval/semantic search over plugins, and execution support. Plugin library status depends on whether plugin definitions are complete and whether embeddings exist for retrieval. This is the primary “actuation” path when the assistant needs to do something outside the model.
8. LLM integration is provider-based
The backend’s llm/ layer abstracts model access and supports at least two provider styles: OpenAI-compatible APIs and a Power SDK provider. Configuration is externalized, so the model backend can be swapped without changing the higher-level agent logic. This keeps model access behind a clean service boundary.
9. Security, auth, and license enforcement are first-class
Authentication is JWT-based, with user/admin management and auth profile support. The system also has a license service that verifies a signed license against a device fingerprint using RS256 public-key verification. That makes deployment authorization part of the runtime architecture, not just a licensing document.
10. Sites and gateway integration define the external-facing boundary
The product models site access in two modes: proxy and plugin. proxy implies upstream/gateway access and certificate handling, while plugin avoids upstream/cert configuration. Site health checks and gateway-related routers indicate the backend also manages how external sites or gateways are connected and monitored.
11. Audit and observability are built in
There is a dedicated audit service/router for admin actions, and middleware for access logging. Logs are written to stdout, which makes container-based collection the expected operational model. This is important for diagramming because audit trails and runtime logs are separate concerns from the main business data flow.
12. Browser-side artifacts are separate delivery channels
ai-chat/ is a Chrome extension-style package with background, content, panel, and options scripts for embedding chat into browser workflows. anzai-gateway-embed/ is another client-side package for embedding a panel in gateway-related environments. These are distribution surfaces for the assistant, not part of the backend service core.
13. Deployment model
The repo is designed for Docker Compose deployment with separate containers for MySQL, backend, and frontend. There are also offline Docker variants and helper scripts for packaging, documentation generation, screenshots, and license issuance. For an architecture diagram, the important runtime flow is: browser/client → frontend/Nginx → backend API → database/files/LLM providers/plugins/external sites.
14. What to draw as the main boundaries
A useful diagram would show four major zones:
- Client/UI zone: web admin console + browser extensions
- API/orchestration zone: FastAPI backend with agent/RAG/plugin/auth/audit/system services
- Data zone: MySQL + uploaded file storage
- External dependency zone: LLM providers, plugin HTTP endpoints, upstream sites/gateway, license verification inputs
Main entry points: main.py API app · mysql_service.py MySQL · agent.py Agent · plugins.py Plugins
Components 20
Client/UI
Admin console and browser delivery surfaces.
- Admin console · Operations UI for managing sites, files, users, plugins, and system settings.
frontend - AI chat · Chrome-extension-style chat delivery surface for browser workflows.
ai-chat - Gateway embed · Embedded panel for gateway-oriented client environments.
anzai-gateway-embed
Backend API
FastAPI control plane, orchestration, and domain routers.
- API app · Application entrypoint that wires middleware, logging, dependencies, and routers.
backend/app/main.py - Auth · JWT login and authentication flows.
backend/app/routers/auth.py - Users · User and admin account management endpoints.
backend/app/routers/users.py - Sites · Site modes, upstream handling, and gateway-related management.
backend/app/routers/sites.py - Files · File repository and upload management.
backend/app/routers/files.py - Plugins · Plugin library import, retrieval, and execution endpoints.
backend/app/routers/plugins.py - Agent · Chat orchestration and reasoning entrypoint.
backend/app/routers/agent.py - RAG pipeline · File-to-context pipeline for ingestion and retrieval.
backend/app/rag - LLM service · Model access layer over OpenAI-compatible and Power SDK providers.
backend/app/llm - Audit · Administrative action logging and audit endpoints.
backend/app/routers/audit.py - System · System settings and runtime configuration endpoints.
backend/app/routers/system.py - License · Signed-license verification tied to device fingerprint and RSA keys.
backend/app/license_service.py
Data
Persistent state and local artifacts.
External deps
Model providers, upstream sites, plugins, and license inputs.
- Plugin APIs · External HTTP endpoints invoked by plugins.
- Upstream sites · Proxy targets and site backends managed through site configuration.
- Model providers · OpenAI-compatible and Power SDK model backends.
Connections 28
- Admin console → API app: HTTP API · Admin console calls backend endpoints over HTTP.
- AI chat → API app: chat API · Browser chat surfaces use backend orchestration APIs.
- Gateway embed → API app: embed API · Embedded gateway UI communicates with the backend.
- API app → Auth: registers · API app exposes auth routes.
- API app → Users: registers · API app exposes user routes.
- API app → Sites: registers · API app exposes site management routes.
- API app → Files: registers · API app exposes file repository routes.
- API app → Plugins: registers · API app exposes plugin routes.
- API app → Agent: registers · API app exposes agent/chat routes.
- API app → Audit: registers · API app exposes audit and audit-log routes.
- API app → System: registers · API app exposes system settings routes.
- Agent → LLM service: uses · Agent orchestration delegates model calls to the LLM layer.
- Agent → RAG pipeline: retrieves context · Agent pulls grounded context from RAG.
- Agent → Plugins: invokes tools · Agent can call plugins for external actions.
- Files → Uploads: stores · Uploaded files are written to disk.
- Files → RAG pipeline: ingests · Files feed the RAG ingestion pipeline.
- RAG pipeline → MySQL: persists metadata · RAG pipeline stores operational state and indexes metadata in the database.
- Plugins → Plugin APIs: calls · Plugin execution reaches external HTTP tools.
- Sites → Upstream sites: proxies to · Site management connects to upstream or gateway targets.
- System → License: checks license · System/runtime flows depend on license validation.
- License → Model providers: verifies inputs · License verification uses signed public-key inputs and device identity context.
- LLM service → Model providers: requests · LLM abstraction forwards prompts to provider backends.
- Auth → MySQL: reads/writes · Authentication state and users are stored in the database.
- Users → MySQL: reads/writes · User management uses relational persistence.
- Sites → MySQL: reads/writes · Site configuration and status are persisted in the database.
- Plugins → MySQL: reads/writes · Plugin definitions and status are stored relationally.
- Audit → MySQL: logs · Audit records are persisted in the database.
- Admin console → MySQL: indirect via API · The SPA depends on backend persistence through API calls.