# darshani8/guru-ji architecture

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

- Interactive diagram: https://gitdiagram.com/darshani8/guru-ji
- Repository: https://github.com/darshani8/guru-ji

## Overview

Agent Saffron is an institutional intelligence platform: staff and other authorised users import institutional data, then query it or ask an agent to perform work through text or voice. The main flow includes reviewed ingestion into canonical tenant-isolated data, permission-bound tool execution, and generated answers or reports. Separate capabilities provide cited document search, public-web intelligence, and read-only federated data access. The graph follows README workflows and the supplied source excerpts; wiring among unsampled subsystems is shown only where the documentation supports it.

Main entry points: [`apps/web/assistant/app.js`](https://github.com/darshani8/guru-ji/blob/main/apps/web/assistant/app.js) (Text and voice client), [`apps/api/app/ingestion/service.py`](https://github.com/darshani8/guru-ji/blob/main/apps/api/app/ingestion/service.py) (Ingestion pipeline), [`apps/api/app/documents/rag.py`](https://github.com/darshani8/guru-ji/blob/main/apps/api/app/documents/rag.py) (Document RAG), [`apps/api/app/orchestration/assistant_service.py`](https://github.com/darshani8/guru-ji/blob/main/apps/api/app/orchestration/assistant_service.py) (Assistant orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Experience"]
  node_assistant["Text and voice client<br/>[app.js]"]
  node_voice_api["Voice API<br/>[voice.py]"]
  node_voice_sessions["Voice sessions<br/>[session_manager.py]"]
end

subgraph group_ingestion["Data Ingestion"]
  node_ingest_api["Ingestion API<br/>[ingestion.py]"]
  node_ingestion_service["Ingestion pipeline<br/>[service.py]"]
  node_parsers["File parsers<br/>[registry.py]"]
  node_canonical_data[("Canonical institution data<br/>[store.py]")]
  node_object_store[("Uploaded file storage<br/>[object_store.py]")]
end

subgraph group_agent["Agent Runtime"]
  node_agent_api["Agent commands API<br/>[agent.py]"]
  node_assistant_runtime["Assistant orchestration"]
  node_policy_gateway["Policy tool gateway<br/>[gateway.py]"]
  node_tool_registry["Registered tools<br/>[registry.py]"]
  node_report_actions["Report generation<br/>[reports.py]"]
end

subgraph group_intelligence["Research Intelligence"]
  node_docs_api["Documents API<br/>[documents.py]"]
  node_research_api["Intelligence API<br/>[intelligence.py]"]
  node_document_rag["Document RAG<br/>[rag.py]"]
  node_vector_store[("Document vector store<br/>[vector_store.py]")]
  node_embedding["Document embeddings<br/>[embeddings.py]"]
  node_internet_service["Internet intelligence<br/>[service.py]"]
  node_map_service["Institution web map<br/>[service.py]"]
end

subgraph group_platform["Platform Services"]
  node_data_api["Unified data API<br/>[data.py]"]
  node_data_access["Scoped data access<br/>[service.py]"]
  node_connector_registry["Federated connectors<br/>[registry.py]"]
end

node_user(("Institutional user"))
node_external_model{{"Model provider"}}
node_public_web{{"Public web sources"}}

node_user -->|"uses"| node_assistant
node_assistant -->|"sends commands"| node_agent_api
node_assistant -->|"uploads data"| node_ingest_api
node_assistant -->|"searches documents"| node_docs_api
node_assistant -->|"requests research"| node_research_api
node_assistant -->|"queries data"| node_data_api
node_assistant -->|"opens voice"| node_voice_api
node_ingest_api -->|"creates jobs"| node_ingestion_service
node_ingestion_service -->|"parses files"| node_parsers
node_ingestion_service -->|"stores uploads"| node_object_store
node_ingestion_service -->|"commits records"| node_canonical_data
node_agent_api -->|"runs commands"| node_assistant_runtime
node_assistant_runtime -->|"dispatches tools"| node_policy_gateway
node_policy_gateway -->|"resolves tools"| node_tool_registry
node_tool_registry -->|"invokes reports"| node_report_actions
node_assistant_runtime -.->|"plans and answers"| node_external_model
node_docs_api -->|"answers queries"| node_document_rag
node_document_rag -->|"embeds queries"| node_embedding
node_document_rag -->|"retrieves passages"| node_vector_store
node_document_rag -.->|"synthesizes cited answers"| node_external_model
node_research_api -->|"investigates"| node_internet_service
node_internet_service -.->|"searches sources"| node_public_web
node_research_api -->|"manages map"| node_map_service
node_data_api -->|"reads scoped data"| node_data_access
node_data_access -->|"reads records"| node_canonical_data
node_data_access -->|"uses connectors"| node_connector_registry
node_voice_api -->|"manages sessions"| node_voice_sessions

click node_assistant "https://github.com/darshani8/guru-ji/blob/main/apps/web/assistant/app.js"
click node_agent_api "https://github.com/darshani8/guru-ji/blob/main/apps/api/app/api/routes/agent.py"
click node_ingest_api "https://github.com/darshani8/guru-ji/blob/main/apps/api/app/api/routes/ingestion.py"
click node_docs_api "https://github.com/darshani8/guru-ji/blob/main/apps/api/app/api/routes/documents.py"
click node_research_api "https://github.com/darshani8/guru-ji/blob/main/apps/api/app/api/routes/intelligence.py"
click node_data_api "https://github.com/darshani8/guru-ji/blob/main/apps/api/app/api/routes/data.py"
click node_voice_api "https://github.com/darshani8/guru-ji/blob/main/apps/api/app/api/routes/voice.py"
click node_ingestion_service "https://github.com/darshani8/guru-ji/blob/main/apps/api/app/ingestion/service.py"
click node_parsers "https://github.com/darshani8/guru-ji/blob/main/apps/api/app/ingestion/registry.py"
click node_canonical_data "https://github.com/darshani8/guru-ji/blob/main/apps/api/app/institution_data/store.py"
click node_object_store "https://github.com/darshani8/guru-ji/blob/main/apps/api/app/storage/object_store.py"
click node_assistant_runtime "https://github.com/darshani8/guru-ji/blob/main/apps/api/app/orchestration/assistant_service.py"
click node_policy_gateway "https://github.com/darshani8/guru-ji/blob/main/apps/api/app/gateway/gateway.py"
click node_tool_registry "https://github.com/darshani8/guru-ji/blob/main/apps/api/app/tools/registry.py"
click node_report_actions "https://github.com/darshani8/guru-ji/blob/main/apps/api/app/actions/reports.py"
click node_document_rag "https://github.com/darshani8/guru-ji/blob/main/apps/api/app/documents/rag.py"
click node_vector_store "https://github.com/darshani8/guru-ji/blob/main/apps/api/app/documents/vector_store.py"
click node_embedding "https://github.com/darshani8/guru-ji/blob/main/apps/api/app/documents/embeddings.py"
click node_internet_service "https://github.com/darshani8/guru-ji/blob/main/apps/api/app/internet_intelligence/service.py"
click node_map_service "https://github.com/darshani8/guru-ji/blob/main/apps/api/app/internet_intelligence/map/service.py"
click node_data_access "https://github.com/darshani8/guru-ji/blob/main/apps/api/app/data_access/service.py"
click node_connector_registry "https://github.com/darshani8/guru-ji/blob/main/apps/api/app/connectors/registry.py"
click node_voice_sessions "https://github.com/darshani8/guru-ji/blob/main/apps/api/app/voice/session_manager.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_assistant,node_voice_api,node_voice_sessions,node_user toneBlue
class node_ingest_api,node_ingestion_service,node_parsers,node_canonical_data,node_object_store toneAmber
class node_agent_api,node_assistant_runtime,node_policy_gateway,node_tool_registry,node_report_actions toneMint
class node_docs_api,node_research_api,node_document_rag,node_vector_store,node_embedding,node_internet_service,node_map_service toneRose
class node_data_api,node_data_access,node_connector_registry,node_external_model,node_public_web toneIndigo
```

## Components

### User Experience

- [Text and voice client](https://github.com/darshani8/guru-ji/blob/main/apps/web/assistant/app.js): `apps/web/assistant/app.js`
- [Voice API](https://github.com/darshani8/guru-ji/blob/main/apps/api/app/api/routes/voice.py): `apps/api/app/api/routes/voice.py`
- [Voice sessions](https://github.com/darshani8/guru-ji/blob/main/apps/api/app/voice/session_manager.py): `apps/api/app/voice/session_manager.py`

### Data Ingestion

- [Ingestion API](https://github.com/darshani8/guru-ji/blob/main/apps/api/app/api/routes/ingestion.py): `apps/api/app/api/routes/ingestion.py`
- [Ingestion pipeline](https://github.com/darshani8/guru-ji/blob/main/apps/api/app/ingestion/service.py): `apps/api/app/ingestion/service.py`
- [File parsers](https://github.com/darshani8/guru-ji/blob/main/apps/api/app/ingestion/registry.py): `apps/api/app/ingestion/registry.py`
- [Canonical institution data](https://github.com/darshani8/guru-ji/blob/main/apps/api/app/institution_data/store.py): `apps/api/app/institution_data/store.py`
- [Uploaded file storage](https://github.com/darshani8/guru-ji/blob/main/apps/api/app/storage/object_store.py): `apps/api/app/storage/object_store.py`

### Agent Runtime

- [Agent commands API](https://github.com/darshani8/guru-ji/blob/main/apps/api/app/api/routes/agent.py): `apps/api/app/api/routes/agent.py`
- [Assistant orchestration](https://github.com/darshani8/guru-ji/blob/main/apps/api/app/orchestration/assistant_service.py): `apps/api/app/orchestration/assistant_service.py`
- [Policy tool gateway](https://github.com/darshani8/guru-ji/blob/main/apps/api/app/gateway/gateway.py): `apps/api/app/gateway/gateway.py`
- [Registered tools](https://github.com/darshani8/guru-ji/blob/main/apps/api/app/tools/registry.py): `apps/api/app/tools/registry.py`
- [Report generation](https://github.com/darshani8/guru-ji/blob/main/apps/api/app/actions/reports.py): `apps/api/app/actions/reports.py`

### Research Intelligence

- [Documents API](https://github.com/darshani8/guru-ji/blob/main/apps/api/app/api/routes/documents.py): `apps/api/app/api/routes/documents.py`
- [Intelligence API](https://github.com/darshani8/guru-ji/blob/main/apps/api/app/api/routes/intelligence.py): `apps/api/app/api/routes/intelligence.py`
- [Document RAG](https://github.com/darshani8/guru-ji/blob/main/apps/api/app/documents/rag.py): `apps/api/app/documents/rag.py`
- [Document vector store](https://github.com/darshani8/guru-ji/blob/main/apps/api/app/documents/vector_store.py): `apps/api/app/documents/vector_store.py`
- [Document embeddings](https://github.com/darshani8/guru-ji/blob/main/apps/api/app/documents/embeddings.py): `apps/api/app/documents/embeddings.py`
- [Internet intelligence](https://github.com/darshani8/guru-ji/blob/main/apps/api/app/internet_intelligence/service.py): `apps/api/app/internet_intelligence/service.py`
- [Institution web map](https://github.com/darshani8/guru-ji/blob/main/apps/api/app/internet_intelligence/map/service.py): `apps/api/app/internet_intelligence/map/service.py`

### Platform Services

- [Unified data API](https://github.com/darshani8/guru-ji/blob/main/apps/api/app/api/routes/data.py): `apps/api/app/api/routes/data.py`
- [Scoped data access](https://github.com/darshani8/guru-ji/blob/main/apps/api/app/data_access/service.py): `apps/api/app/data_access/service.py`
- [Federated connectors](https://github.com/darshani8/guru-ji/blob/main/apps/api/app/connectors/registry.py): `apps/api/app/connectors/registry.py`

### Other components

- **Institutional user**
- **Model provider**
- **Public web sources**

## Connections

- Institutional user → Text and voice client: uses
- Text and voice client → Agent commands API: sends commands
- Text and voice client → Ingestion API: uploads data
- Text and voice client → Documents API: searches documents
- Text and voice client → Intelligence API: requests research
- Text and voice client → Unified data API: queries data
- Text and voice client → Voice API: opens voice
- Ingestion API → Ingestion pipeline: creates jobs
- Ingestion pipeline → File parsers: parses files
- Ingestion pipeline → Uploaded file storage: stores uploads
- Ingestion pipeline → Canonical institution data: commits records
- Agent commands API → Assistant orchestration: runs commands
- Assistant orchestration → Policy tool gateway: dispatches tools
- Policy tool gateway → Registered tools: resolves tools
- Registered tools → Report generation: invokes reports
- Assistant orchestration → Model provider: plans and answers
- Documents API → Document RAG: answers queries
- Document RAG → Document embeddings: embeds queries
- Document RAG → Document vector store: retrieves passages
- Document RAG → Model provider: synthesizes cited answers
- Intelligence API → Internet intelligence: investigates
- Internet intelligence → Public web sources: searches sources
- Intelligence API → Institution web map: manages map
- Unified data API → Scoped data access: reads scoped data
- Scoped data access → Canonical institution data: reads records
- Scoped data access → Federated connectors: uses connectors
- Voice API → Voice sessions: manages sessions