# mode1943/security-operations-agent architecture

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

- Interactive diagram: https://gitdiagram.com/mode1943/security-operations-agent
- Repository: https://github.com/mode1943/security-operations-agent

## Overview

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: [`backend/app/main.py`](https://github.com/mode1943/security-operations-agent/blob/main/backend/app/main.py) (API app), [`backend/app/mysql_service.py`](https://github.com/mode1943/security-operations-agent/blob/main/backend/app/mysql_service.py) (MySQL), [`backend/app/routers/agent.py`](https://github.com/mode1943/security-operations-agent/blob/main/backend/app/routers/agent.py) (Agent), [`backend/app/routers/plugins.py`](https://github.com/mode1943/security-operations-agent/blob/main/backend/app/routers/plugins.py) (Plugins)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client/UI"]
  node_frontend["Admin console<br/>Vue 3 SPA"]
  node_ai_chat["AI chat<br/>browser extension"]
  node_gateway_embed["Gateway embed<br/>embed client"]
end

subgraph group_backend["Backend API"]
  node_main_api["API app<br/>FastAPI bootstrap<br/>[main.py]"]
  node_auth_router["Auth<br/>router<br/>[auth.py]"]
  node_user_router["Users<br/>router<br/>[users.py]"]
  node_site_router["Sites<br/>router<br/>[sites.py]"]
  node_file_router["Files<br/>router<br/>[files.py]"]
  node_plugin_router["Plugins<br/>router<br/>[plugins.py]"]
  node_agent_router["Agent<br/>router<br/>[agent.py]"]
  node_rag_pipeline["RAG pipeline<br/>extract-chunk-embed-retrieve"]
  node_llm_service["LLM service<br/>provider abstraction"]
  node_audit_system["Audit<br/>service/router<br/>[audit.py]"]
  node_system_router["System<br/>router<br/>[system.py]"]
  node_license_service["License<br/>verification service<br/>[license_service.py]"]
end

subgraph group_data["Data"]
  node_mysql_db[("MySQL<br/>relational store<br/>[mysql_service.py]")]
  node_file_store[("Uploads<br/>filesystem store<br/>[paths.py]")]
end

subgraph group_external["External deps"]
  node_plugin_endpoints["Plugin APIs<br/>HTTP tools"]
  node_upstream_sites["Upstream sites<br/>external gateway"]
  node_model_providers["Model providers<br/>LLM APIs"]
end

node_frontend -->|"HTTP API"| node_main_api
node_ai_chat -->|"chat API"| node_main_api
node_gateway_embed -->|"embed API"| node_main_api
node_main_api -->|"registers"| node_auth_router
node_main_api -->|"registers"| node_user_router
node_main_api -->|"registers"| node_site_router
node_main_api -->|"registers"| node_file_router
node_main_api -->|"registers"| node_plugin_router
node_main_api -->|"registers"| node_agent_router
node_main_api -->|"registers"| node_audit_system
node_main_api -->|"registers"| node_system_router
node_agent_router -->|"uses"| node_llm_service
node_agent_router -->|"retrieves context"| node_rag_pipeline
node_agent_router -->|"invokes tools"| node_plugin_router
node_file_router -->|"stores"| node_file_store
node_file_router -->|"ingests"| node_rag_pipeline
node_rag_pipeline -->|"persists metadata"| node_mysql_db
node_plugin_router -->|"calls"| node_plugin_endpoints
node_site_router -->|"proxies to"| node_upstream_sites
node_system_router -->|"checks license"| node_license_service
node_license_service -.->|"verifies inputs"| node_model_providers
node_llm_service -->|"requests"| node_model_providers
node_auth_router -->|"reads/writes"| node_mysql_db
node_user_router -->|"reads/writes"| node_mysql_db
node_site_router -->|"reads/writes"| node_mysql_db
node_plugin_router -->|"reads/writes"| node_mysql_db
node_audit_system -->|"logs"| node_mysql_db
node_frontend -.->|"indirect via API"| node_mysql_db

click node_frontend "https://github.com/mode1943/security-operations-agent/tree/main/frontend"
click node_ai_chat "https://github.com/mode1943/security-operations-agent/tree/main/ai-chat"
click node_gateway_embed "https://github.com/mode1943/security-operations-agent/tree/main/anzai-gateway-embed"
click node_main_api "https://github.com/mode1943/security-operations-agent/blob/main/backend/app/main.py"
click node_auth_router "https://github.com/mode1943/security-operations-agent/blob/main/backend/app/routers/auth.py"
click node_user_router "https://github.com/mode1943/security-operations-agent/blob/main/backend/app/routers/users.py"
click node_site_router "https://github.com/mode1943/security-operations-agent/blob/main/backend/app/routers/sites.py"
click node_file_router "https://github.com/mode1943/security-operations-agent/blob/main/backend/app/routers/files.py"
click node_plugin_router "https://github.com/mode1943/security-operations-agent/blob/main/backend/app/routers/plugins.py"
click node_agent_router "https://github.com/mode1943/security-operations-agent/blob/main/backend/app/routers/agent.py"
click node_rag_pipeline "https://github.com/mode1943/security-operations-agent/tree/main/backend/app/rag"
click node_llm_service "https://github.com/mode1943/security-operations-agent/tree/main/backend/app/llm"
click node_audit_system "https://github.com/mode1943/security-operations-agent/blob/main/backend/app/routers/audit.py"
click node_system_router "https://github.com/mode1943/security-operations-agent/blob/main/backend/app/routers/system.py"
click node_license_service "https://github.com/mode1943/security-operations-agent/blob/main/backend/app/license_service.py"
click node_mysql_db "https://github.com/mode1943/security-operations-agent/blob/main/backend/app/mysql_service.py"
click node_file_store "https://github.com/mode1943/security-operations-agent/blob/main/backend/app/paths.py"

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_frontend,node_ai_chat,node_gateway_embed toneBlue
class node_main_api,node_auth_router,node_user_router,node_site_router,node_file_router,node_plugin_router,node_agent_router,node_rag_pipeline,node_llm_service,node_audit_system,node_system_router,node_license_service toneAmber
class node_mysql_db,node_file_store toneMint
class node_plugin_endpoints,node_upstream_sites,node_model_providers toneRose
```

## Components

### Client/UI

Admin console and browser delivery surfaces.

- [Admin console](https://github.com/mode1943/security-operations-agent/tree/main/frontend): Vue 3 SPA · Operations UI for managing sites, files, users, plugins, and system settings. · `frontend`
- [AI chat](https://github.com/mode1943/security-operations-agent/tree/main/ai-chat): browser extension · Chrome-extension-style chat delivery surface for browser workflows. · `ai-chat`
- [Gateway embed](https://github.com/mode1943/security-operations-agent/tree/main/anzai-gateway-embed): embed client · Embedded panel for gateway-oriented client environments. · `anzai-gateway-embed`

### Backend API

FastAPI control plane, orchestration, and domain routers.

- [API app](https://github.com/mode1943/security-operations-agent/blob/main/backend/app/main.py): FastAPI bootstrap · Application entrypoint that wires middleware, logging, dependencies, and routers. · `backend/app/main.py`
- [Auth](https://github.com/mode1943/security-operations-agent/blob/main/backend/app/routers/auth.py): router · JWT login and authentication flows. · `backend/app/routers/auth.py`
- [Users](https://github.com/mode1943/security-operations-agent/blob/main/backend/app/routers/users.py): router · User and admin account management endpoints. · `backend/app/routers/users.py`
- [Sites](https://github.com/mode1943/security-operations-agent/blob/main/backend/app/routers/sites.py): router · Site modes, upstream handling, and gateway-related management. · `backend/app/routers/sites.py`
- [Files](https://github.com/mode1943/security-operations-agent/blob/main/backend/app/routers/files.py): router · File repository and upload management. · `backend/app/routers/files.py`
- [Plugins](https://github.com/mode1943/security-operations-agent/blob/main/backend/app/routers/plugins.py): router · Plugin library import, retrieval, and execution endpoints. · `backend/app/routers/plugins.py`
- [Agent](https://github.com/mode1943/security-operations-agent/blob/main/backend/app/routers/agent.py): router · Chat orchestration and reasoning entrypoint. · `backend/app/routers/agent.py`
- [RAG pipeline](https://github.com/mode1943/security-operations-agent/tree/main/backend/app/rag): extract-chunk-embed-retrieve · File-to-context pipeline for ingestion and retrieval. · `backend/app/rag`
- [LLM service](https://github.com/mode1943/security-operations-agent/tree/main/backend/app/llm): provider abstraction · Model access layer over OpenAI-compatible and Power SDK providers. · `backend/app/llm`
- [Audit](https://github.com/mode1943/security-operations-agent/blob/main/backend/app/routers/audit.py): service/router · Administrative action logging and audit endpoints. · `backend/app/routers/audit.py`
- [System](https://github.com/mode1943/security-operations-agent/blob/main/backend/app/routers/system.py): router · System settings and runtime configuration endpoints. · `backend/app/routers/system.py`
- [License](https://github.com/mode1943/security-operations-agent/blob/main/backend/app/license_service.py): verification service · Signed-license verification tied to device fingerprint and RSA keys. · `backend/app/license_service.py`

### Data

Persistent state and local artifacts.

- [MySQL](https://github.com/mode1943/security-operations-agent/blob/main/backend/app/mysql_service.py): relational store · Primary operational database for persistent backend state. · `backend/app/mysql_service.py`
- [Uploads](https://github.com/mode1943/security-operations-agent/blob/main/backend/app/paths.py): filesystem store · Configured on-disk repository for uploaded files and artifacts. · `backend/app/paths.py`

### External deps

Model providers, upstream sites, plugins, and license inputs.

- **Plugin APIs**: HTTP tools · External HTTP endpoints invoked by plugins.
- **Upstream sites**: external gateway · Proxy targets and site backends managed through site configuration.
- **Model providers**: LLM APIs · OpenAI-compatible and Power SDK model backends.

## Connections

- 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.