# soumanpaul/sovereignforgeai architecture

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

- Interactive diagram: https://gitdiagram.com/soumanpaul/sovereignforgeai
- Repository: https://github.com/soumanpaul/sovereignforgeai

## Overview

SovereignForgeAI is an on-premise agentic workbench for turning industrial documents, code repositories, and vendor quotations into reviewable artifacts. Users submit goals and files through the workbench; the API records and queues tasks, whose worker classifies the workflow, routes to a capable local model, and executes constrained actions. The three main branches are evidence-grounded inspection review, sandbox-checked code repair, and policy-aware procurement comparison. Knowledge indexing/retrieval, artifact validation, persisted execution traces, and security evidence support that flow. Some subsystem links reflect README-level capabilities because their implementations were not sampled.

Main entry points: [`backend/app/tasks`](https://github.com/soumanpaul/sovereignforgeai/tree/main/backend/app/tasks) (Agent workflows), [`backend/app/api/routes/tasks.py`](https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/api/routes/tasks.py) (Task API), [`backend/app/services/knowledge_ingestion.py`](https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/services/knowledge_ingestion.py) (Knowledge ingestion), [`backend/app/tasks/service.py`](https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/tasks/service.py) (Task records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_frontend["Next.js workbench"]
  node_frontend_api["API client<br/>[api.ts]"]
  node_auth_ui["Local authentication<br/>[auth-screen.tsx]"]
  node_review_ui["Trace and security views<br/>[trace-security.tsx]"]
end

subgraph group_api["API and tasks"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_task_routes["Task API<br/>[tasks.py]"]
  node_task_service["Task records<br/>[service.py]"]
  node_worker["Task runtime<br/>[runtime.py]"]
end

subgraph group_knowledge["Knowledge and retrieval"]
  node_extraction["Document extraction"]
  node_ingestion["Knowledge ingestion"]
  node_retrieval["Hybrid retrieval"]
end

subgraph group_execution["Agent execution"]
  node_task_engine["Agent workflows"]
  node_router["Task and model routing<br/>[router.py]"]
  node_ollama["Local model provider<br/>[ollama.py]"]
  node_tools["Tool registry and policies<br/>[registry.py]"]
  node_sandbox_client["Sandbox client<br/>[sandbox_client.py]"]
  node_sandbox["Isolated code runner<br/>[app.py]"]
  node_artifacts["Artifact generation"]
end

subgraph group_state["State and evidence"]
  node_qdrant[("Vector index<br/>[qdrant_store.py]")]
  node_database[("Application database<br/>[models.py]")]
  node_file_storage[("Uploaded files<br/>[file_storage.py]")]
  node_audit["Security and audit API<br/>[security.py]"]
end

node_user(("Workbench user"))

node_user -->|"submits work"| node_frontend
node_frontend -->|"authenticates"| node_auth_ui
node_frontend -->|"requests data"| node_frontend_api
node_frontend_api -->|"calls API"| node_api_app
node_api_app -->|"dispatches routes"| node_task_routes
node_task_routes -->|"creates and reads"| node_task_service
node_task_routes -->|"notifies worker"| node_worker
node_worker -->|"loads task state"| node_task_service
node_worker -->|"executes workflow"| node_task_engine
node_task_engine -->|"classifies and routes"| node_router
node_router -->|"checks model health"| node_ollama
node_task_engine -->|"requests inference"| node_ollama
node_task_engine -->|"retrieves evidence"| node_retrieval
node_task_engine -->|"extracts input"| node_extraction
node_task_engine -->|"dispatches actions"| node_tools
node_tools -->|"requests execution"| node_sandbox_client
node_sandbox_client -->|"runs isolated code"| node_sandbox
node_task_engine -->|"produces deliverables"| node_artifacts
node_task_engine -->|"records run results"| node_task_service
node_task_routes -->|"serves uploads"| node_file_storage
node_ingestion -->|"extracts documents"| node_extraction
node_ingestion -->|"requests embeddings"| node_ollama
node_ingestion -->|"writes vectors"| node_qdrant
node_retrieval -->|"searches vectors"| node_qdrant
node_task_service -->|"persists task state"| node_database
node_ingestion -->|"persists index records"| node_database
node_task_routes -->|"reads trace and artifacts"| node_database
node_api_app -->|"mounts security routes"| node_audit
node_review_ui -->|"loads trace views"| node_frontend_api

click node_frontend "https://github.com/soumanpaul/sovereignforgeai/tree/main/frontend/app"
click node_frontend_api "https://github.com/soumanpaul/sovereignforgeai/blob/main/frontend/lib/api.ts"
click node_auth_ui "https://github.com/soumanpaul/sovereignforgeai/blob/main/frontend/components/auth/auth-screen.tsx"
click node_api_app "https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/main.py"
click node_task_routes "https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/api/routes/tasks.py"
click node_task_service "https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/tasks/service.py"
click node_worker "https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/tasks/runtime.py"
click node_task_engine "https://github.com/soumanpaul/sovereignforgeai/tree/main/backend/app/tasks"
click node_router "https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/routing/router.py"
click node_ollama "https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/model_providers/ollama.py"
click node_tools "https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/tools/registry.py"
click node_sandbox_client "https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/services/sandbox_client.py"
click node_sandbox "https://github.com/soumanpaul/sovereignforgeai/blob/main/sandbox-runner/app.py"
click node_extraction "https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/services/document_extraction.py"
click node_ingestion "https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/services/knowledge_ingestion.py"
click node_retrieval "https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/services/hybrid_retrieval.py"
click node_qdrant "https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/services/qdrant_store.py"
click node_database "https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/db/models.py"
click node_file_storage "https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/services/file_storage.py"
click node_artifacts "https://github.com/soumanpaul/sovereignforgeai/tree/main/backend/app/artifacts"
click node_audit "https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/api/routes/security.py"
click node_review_ui "https://github.com/soumanpaul/sovereignforgeai/blob/main/frontend/components/control-plane/trace-security.tsx"

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_frontend_api,node_auth_ui,node_review_ui,node_user toneBlue
class node_api_app,node_task_routes,node_task_service,node_worker toneAmber
class node_extraction,node_ingestion,node_retrieval toneMint
class node_task_engine,node_router,node_ollama,node_tools,node_sandbox_client,node_sandbox,node_artifacts toneRose
class node_qdrant,node_database,node_file_storage,node_audit toneIndigo
```

## Components

### User experience

- [Next.js workbench](https://github.com/soumanpaul/sovereignforgeai/tree/main/frontend/app): `frontend/app`
- [API client](https://github.com/soumanpaul/sovereignforgeai/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`
- [Local authentication](https://github.com/soumanpaul/sovereignforgeai/blob/main/frontend/components/auth/auth-screen.tsx): `frontend/components/auth/auth-screen.tsx`
- [Trace and security views](https://github.com/soumanpaul/sovereignforgeai/blob/main/frontend/components/control-plane/trace-security.tsx): `frontend/components/control-plane/trace-security.tsx`

### API and tasks

- [FastAPI application](https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/main.py): `backend/app/main.py`
- [Task API](https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/api/routes/tasks.py): `backend/app/api/routes/tasks.py`
- [Task records](https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/tasks/service.py): `backend/app/tasks/service.py`
- [Task runtime](https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/tasks/runtime.py): `backend/app/tasks/runtime.py`

### Knowledge and retrieval

- [Document extraction](https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/services/document_extraction.py): `backend/app/services/document_extraction.py`
- [Knowledge ingestion](https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/services/knowledge_ingestion.py): `backend/app/services/knowledge_ingestion.py`
- [Hybrid retrieval](https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/services/hybrid_retrieval.py): `backend/app/services/hybrid_retrieval.py`

### Agent execution

- [Agent workflows](https://github.com/soumanpaul/sovereignforgeai/tree/main/backend/app/tasks): `backend/app/tasks`
- [Task and model routing](https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/routing/router.py): `backend/app/routing/router.py`
- [Local model provider](https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/model_providers/ollama.py): `backend/app/model_providers/ollama.py`
- [Tool registry and policies](https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/tools/registry.py): `backend/app/tools/registry.py`
- [Sandbox client](https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/services/sandbox_client.py): `backend/app/services/sandbox_client.py`
- [Isolated code runner](https://github.com/soumanpaul/sovereignforgeai/blob/main/sandbox-runner/app.py): `sandbox-runner/app.py`
- [Artifact generation](https://github.com/soumanpaul/sovereignforgeai/tree/main/backend/app/artifacts): `backend/app/artifacts`

### State and evidence

- [Vector index](https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/services/qdrant_store.py): `backend/app/services/qdrant_store.py`
- [Application database](https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/db/models.py): `backend/app/db/models.py`
- [Uploaded files](https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/services/file_storage.py): `backend/app/services/file_storage.py`
- [Security and audit API](https://github.com/soumanpaul/sovereignforgeai/blob/main/backend/app/api/routes/security.py): `backend/app/api/routes/security.py`

### Other components

- **Workbench user**

## Connections

- Workbench user → Next.js workbench: submits work
- Next.js workbench → Local authentication: authenticates
- Next.js workbench → API client: requests data
- API client → FastAPI application: calls API
- FastAPI application → Task API: dispatches routes
- Task API → Task records: creates and reads
- Task API → Task runtime: notifies worker
- Task runtime → Task records: loads task state
- Task runtime → Agent workflows: executes workflow
- Agent workflows → Task and model routing: classifies and routes
- Task and model routing → Local model provider: checks model health
- Agent workflows → Local model provider: requests inference
- Agent workflows → Hybrid retrieval: retrieves evidence
- Agent workflows → Document extraction: extracts input
- Agent workflows → Tool registry and policies: dispatches actions
- Tool registry and policies → Sandbox client: requests execution
- Sandbox client → Isolated code runner: runs isolated code
- Agent workflows → Artifact generation: produces deliverables
- Agent workflows → Task records: records run results
- Task API → Uploaded files: serves uploads
- Knowledge ingestion → Document extraction: extracts documents
- Knowledge ingestion → Local model provider: requests embeddings
- Knowledge ingestion → Vector index: writes vectors
- Hybrid retrieval → Vector index: searches vectors
- Task records → Application database: persists task state
- Knowledge ingestion → Application database: persists index records
- Task API → Application database: reads trace and artifacts
- FastAPI application → Security and audit API: mounts security routes
- Trace and security views → API client: loads trace views