# shashwathsd2006-glitch/sovereign-ai architecture

> Architecture diagram of the GitHub repository shashwathsd2006-glitch/sovereign-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shashwathsd2006-glitch/sovereign-ai
- Repository: https://github.com/shashwathsd2006-glitch/sovereign-ai

## Overview

Sovereign AI is an on-premise workbench for industrial maintenance teams. The principal workflow is an engineer’s request through the Next.js client and FastAPI model router, then to direct local text generation, document-grounded RAG, or image analysis; the agent workflow combines vision findings with document retrieval for maintenance assessment. Document upload feeds extraction, chunking, and embeddings into local vector storage. The README also documents model-routing, security, and activity views. The supplied tree contains no application source, so service-level paths and internal wiring are based on README descriptions, not inspected implementations.

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Workbench client"]
  node_ui["Workbench routes"]
  node_api_client["Typed API client"]
  node_assistant["AI assistant"]
  node_knowledge_ui["Knowledge base"]
  node_documents_ui["Document management"]
  node_vision_ui["Image analysis"]
  node_agents_ui["Maintenance agents"]
  node_router_ui["Model router view"]
  node_security_ui["Security center"]
  node_activity_ui["Activity logs"]
end

subgraph group_services["AI services"]
  node_fastapi["FastAPI entry"]
  node_router["Model router"]
  node_vision["Vision analysis"]
  node_agent["Maintenance assessment"]
  node_security["Security status"]
  node_activity["Activity events"]
end

subgraph group_knowledge["Knowledge processing"]
  node_rag["RAG pipeline"]
  node_document_processing["Document processing"]
  node_embeddings["Local embeddings"]
end

subgraph group_local["Local infrastructure"]
  node_chroma[("ChromaDB")]
  node_documents[("Document files")]
  node_ollama["Ollama"]
end

node_engineer(("Engineer"))

node_engineer -->|"uses"| node_ui
node_ui -->|"opens"| node_assistant
node_ui -->|"opens"| node_knowledge_ui
node_ui -->|"opens"| node_documents_ui
node_ui -->|"opens"| node_vision_ui
node_ui -->|"opens"| node_agents_ui
node_ui -->|"opens"| node_router_ui
node_ui -->|"opens"| node_security_ui
node_ui -->|"opens"| node_activity_ui
node_assistant -->|"sends requests"| node_api_client
node_knowledge_ui -->|"sends requests"| node_api_client
node_documents_ui -->|"sends requests"| node_api_client
node_vision_ui -->|"sends requests"| node_api_client
node_agents_ui -->|"sends requests"| node_api_client
node_router_ui -->|"sends requests"| node_api_client
node_security_ui -->|"sends requests"| node_api_client
node_activity_ui -->|"sends requests"| node_api_client
node_api_client -->|"HTTP JSON"| node_fastapi
node_fastapi -->|"dispatches"| node_router
node_router -->|"routes text"| node_rag
node_router -->|"routes images"| node_vision
node_router -->|"routes plain text"| node_ollama
node_rag -->|"embeds query"| node_embeddings
node_rag -->|"retrieves chunks"| node_chroma
node_rag -->|"generates answer"| node_ollama
node_documents_ui -->|"uploads PDFs"| node_fastapi
node_fastapi -->|"dispatches upload"| node_document_processing
node_document_processing -->|"embeds chunks"| node_embeddings
node_document_processing -->|"indexes chunks"| node_chroma
node_document_processing -->|"stores files"| node_documents
node_vision -->|"requests analysis"| node_ollama
node_agent -->|"requests findings"| node_vision
node_agent -->|"retrieves evidence"| node_rag
node_agent -->|"reasons over results"| node_ollama
node_fastapi -->|"serves status"| node_security
node_fastapi -->|"serves events"| node_activity
node_security -->|"checks state"| node_chroma
node_security -->|"checks status"| node_ollama

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_ui,node_api_client,node_assistant,node_knowledge_ui,node_documents_ui,node_vision_ui,node_agents_ui,node_router_ui,node_security_ui,node_activity_ui toneBlue
class node_fastapi,node_router,node_vision,node_agent,node_security,node_activity toneAmber
class node_rag,node_document_processing,node_embeddings toneMint
class node_chroma,node_documents,node_ollama toneRose
class node_engineer toneIndigo
```

## Components

### Workbench client

- **Workbench routes**
- **Typed API client**
- **AI assistant**
- **Knowledge base**
- **Document management**
- **Image analysis**
- **Maintenance agents**
- **Model router view**
- **Security center**
- **Activity logs**

### AI services

- **FastAPI entry**
- **Model router**
- **Vision analysis**
- **Maintenance assessment**
- **Security status**
- **Activity events**

### Knowledge processing

- **RAG pipeline**
- **Document processing**
- **Local embeddings**

### Local infrastructure

- **ChromaDB**
- **Document files**
- **Ollama**

### Other components

- **Engineer**

## Connections

- Engineer → Workbench routes: uses
- Workbench routes → AI assistant: opens
- Workbench routes → Knowledge base: opens
- Workbench routes → Document management: opens
- Workbench routes → Image analysis: opens
- Workbench routes → Maintenance agents: opens
- Workbench routes → Model router view: opens
- Workbench routes → Security center: opens
- Workbench routes → Activity logs: opens
- AI assistant → Typed API client: sends requests
- Knowledge base → Typed API client: sends requests
- Document management → Typed API client: sends requests
- Image analysis → Typed API client: sends requests
- Maintenance agents → Typed API client: sends requests
- Model router view → Typed API client: sends requests
- Security center → Typed API client: sends requests
- Activity logs → Typed API client: sends requests
- Typed API client → FastAPI entry: HTTP JSON
- FastAPI entry → Model router: dispatches
- Model router → RAG pipeline: routes text
- Model router → Vision analysis: routes images
- Model router → Ollama: routes plain text
- RAG pipeline → Local embeddings: embeds query
- RAG pipeline → ChromaDB: retrieves chunks
- RAG pipeline → Ollama: generates answer
- Document management → FastAPI entry: uploads PDFs
- FastAPI entry → Document processing: dispatches upload
- Document processing → Local embeddings: embeds chunks
- Document processing → ChromaDB: indexes chunks
- Document processing → Document files: stores files
- Vision analysis → Ollama: requests analysis
- Maintenance assessment → Vision analysis: requests findings
- Maintenance assessment → RAG pipeline: retrieves evidence
- Maintenance assessment → Ollama: reasons over results
- FastAPI entry → Security status: serves status
- FastAPI entry → Activity events: serves events
- Security status → ChromaDB: checks state
- Security status → Ollama: checks status