# 2555jaa/university-agent architecture

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

- Interactive diagram: https://gitdiagram.com/2555jaa/university-agent
- Repository: https://github.com/2555jaa/university-agent

## Overview

Local University AI Agent serves students through a built-in web interface and API, supporting tutoring, academic research, persistent study memory, and restricted PC assistance. The main request path runs from user interface to FastAPI routes, then the agent orchestrator, which coordinates model routing, RAG, memory, and tools. RAG covers document parsing, chunking, embeddings, retrieval, and citations; security validates sensitive actions and records audit events. The README documents capabilities not fully visible in the sampled excerpts; relationships for those are shown only where supported by the README or source index.

Main entry points: [`app/agent/orchestrator.py`](https://github.com/2555jaa/university-agent/blob/master/app/agent/orchestrator.py) (Agent Orchestrator), [`app/knowledge/rag_service.py`](https://github.com/2555jaa/university-agent/blob/master/app/knowledge/rag_service.py) (Grounded RAG), [`app/api/routes.py`](https://github.com/2555jaa/university-agent/blob/master/app/api/routes.py) (FastAPI Routes), [`app/providers/router.py`](https://github.com/2555jaa/university-agent/blob/master/app/providers/router.py) (Hybrid Model Router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Interfaces and API"]
  node_webui["Built-in Web UI<br/>[app.js]"]
  node_api["FastAPI Routes<br/>[routes.py]"]
end

subgraph group_agent["Academic Agent"]
  node_agent_core["Agent Orchestrator<br/>[orchestrator.py]"]
  node_prompts["Mode Prompts<br/>[prompts.py]"]
end

subgraph group_rag["Research and RAG"]
  node_rag_service["Grounded RAG<br/>[rag_service.py]"]
  node_parser["Document Parser<br/>[document_parser.py]"]
  node_chunker["Sliding Chunker<br/>[chunker.py]"]
  node_embeddings["Embedding Manager<br/>[embeddings.py]"]
  node_vector[("Vector Index<br/>[vector_store.py]")]
end

subgraph group_models["Model Providers"]
  node_model_router["Hybrid Model Router<br/>[router.py]"]
  node_ollama["Ollama Provider<br/>[ollama_provider.py]"]
  node_cloud["Cloud Provider<br/>[cloud_provider.py]"]
end

subgraph group_safety["Memory and Safety"]
  node_memory[("SQLite Study Memory<br/>[database.py]")]
  node_filesystem["Filesystem Tools"]
  node_terminal["Restricted Terminal<br/>[terminal_tools.py]"]
  node_validator["Action Validator<br/>[validator.py]"]
  node_file_service["Safe File Service<br/>[file_service.py]"]
  node_sandbox["Execution Sandbox<br/>[sandbox.py]"]
  node_audit[("Audit Logger<br/>[audit.py]")]
end

node_user(("Student"))
node_cloud_service(("Cloud AI Service"))
node_ollama_service(("Ollama Service"))

node_user -->|"uses"| node_webui
node_user -->|"submits requests"| node_api
node_webui -->|"sends requests"| node_api
node_api -->|"dispatches chat"| node_agent_core
node_api -->|"handles documents"| node_rag_service
node_api -->|"manages study records"| node_memory
node_agent_core -->|"uses prompts"| node_prompts
node_agent_core -->|"retrieves context"| node_rag_service
node_agent_core -->|"loads and saves"| node_memory
node_agent_core -->|"routes inference"| node_model_router
node_rag_service -->|"parses documents"| node_parser
node_rag_service -->|"creates chunks"| node_chunker
node_rag_service -->|"indexes and searches"| node_vector
node_vector -->|"embeds text"| node_embeddings
node_model_router -->|"selects local"| node_ollama
node_model_router -->|"selects cloud"| node_cloud
node_ollama -->|"calls inference"| node_ollama_service
node_cloud -.->|"calls inference"| node_cloud_service
node_agent_core -->|"dispatches file tools"| node_filesystem
node_agent_core -->|"dispatches commands"| node_terminal
node_filesystem -->|"validates actions"| node_validator
node_filesystem -->|"delegates file access"| node_file_service
node_terminal -->|"checks permissions"| node_validator
node_agent_core -.->|"uses for execution"| node_sandbox
node_agent_core -->|"records activity"| node_audit
node_rag_service -->|"records deletion"| node_audit
node_validator -.->|"records decisions"| node_audit

click node_webui "https://github.com/2555jaa/university-agent/blob/master/app/web/static/app.js"
click node_api "https://github.com/2555jaa/university-agent/blob/master/app/api/routes.py"
click node_agent_core "https://github.com/2555jaa/university-agent/blob/master/app/agent/orchestrator.py"
click node_prompts "https://github.com/2555jaa/university-agent/blob/master/app/agent/prompts.py"
click node_rag_service "https://github.com/2555jaa/university-agent/blob/master/app/knowledge/rag_service.py"
click node_parser "https://github.com/2555jaa/university-agent/blob/master/app/knowledge/document_parser.py"
click node_chunker "https://github.com/2555jaa/university-agent/blob/master/app/knowledge/chunker.py"
click node_embeddings "https://github.com/2555jaa/university-agent/blob/master/app/knowledge/embeddings.py"
click node_vector "https://github.com/2555jaa/university-agent/blob/master/app/knowledge/vector_store.py"
click node_model_router "https://github.com/2555jaa/university-agent/blob/master/app/providers/router.py"
click node_ollama "https://github.com/2555jaa/university-agent/blob/master/app/providers/ollama_provider.py"
click node_cloud "https://github.com/2555jaa/university-agent/blob/master/app/providers/cloud_provider.py"
click node_memory "https://github.com/2555jaa/university-agent/blob/master/app/memory/database.py"
click node_filesystem "https://github.com/2555jaa/university-agent/blob/master/app/tools/filesystem_tools.py"
click node_terminal "https://github.com/2555jaa/university-agent/blob/master/app/tools/terminal_tools.py"
click node_validator "https://github.com/2555jaa/university-agent/blob/master/app/security/validator.py"
click node_file_service "https://github.com/2555jaa/university-agent/blob/master/app/services/file_service.py"
click node_sandbox "https://github.com/2555jaa/university-agent/blob/master/app/security/sandbox.py"
click node_audit "https://github.com/2555jaa/university-agent/blob/master/app/security/audit.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_webui,node_api toneBlue
class node_agent_core,node_prompts toneAmber
class node_rag_service,node_parser,node_chunker,node_embeddings,node_vector toneMint
class node_model_router,node_ollama,node_cloud toneRose
class node_memory,node_filesystem,node_terminal,node_validator,node_file_service,node_sandbox,node_audit,node_user,node_cloud_service,node_ollama_service toneIndigo
```

## Components

### Interfaces and API

- [Built-in Web UI](https://github.com/2555jaa/university-agent/blob/master/app/web/static/app.js): `app/web/static/app.js`
- [FastAPI Routes](https://github.com/2555jaa/university-agent/blob/master/app/api/routes.py): `app/api/routes.py`

### Academic Agent

- [Agent Orchestrator](https://github.com/2555jaa/university-agent/blob/master/app/agent/orchestrator.py): `app/agent/orchestrator.py`
- [Mode Prompts](https://github.com/2555jaa/university-agent/blob/master/app/agent/prompts.py): `app/agent/prompts.py`

### Research and RAG

- [Grounded RAG](https://github.com/2555jaa/university-agent/blob/master/app/knowledge/rag_service.py): `app/knowledge/rag_service.py`
- [Document Parser](https://github.com/2555jaa/university-agent/blob/master/app/knowledge/document_parser.py): `app/knowledge/document_parser.py`
- [Sliding Chunker](https://github.com/2555jaa/university-agent/blob/master/app/knowledge/chunker.py): `app/knowledge/chunker.py`
- [Embedding Manager](https://github.com/2555jaa/university-agent/blob/master/app/knowledge/embeddings.py): `app/knowledge/embeddings.py`
- [Vector Index](https://github.com/2555jaa/university-agent/blob/master/app/knowledge/vector_store.py): `app/knowledge/vector_store.py`

### Model Providers

- [Hybrid Model Router](https://github.com/2555jaa/university-agent/blob/master/app/providers/router.py): `app/providers/router.py`
- [Ollama Provider](https://github.com/2555jaa/university-agent/blob/master/app/providers/ollama_provider.py): `app/providers/ollama_provider.py`
- [Cloud Provider](https://github.com/2555jaa/university-agent/blob/master/app/providers/cloud_provider.py): `app/providers/cloud_provider.py`

### Memory and Safety

- [SQLite Study Memory](https://github.com/2555jaa/university-agent/blob/master/app/memory/database.py): `app/memory/database.py`
- [Filesystem Tools](https://github.com/2555jaa/university-agent/blob/master/app/tools/filesystem_tools.py): `app/tools/filesystem_tools.py`
- [Restricted Terminal](https://github.com/2555jaa/university-agent/blob/master/app/tools/terminal_tools.py): `app/tools/terminal_tools.py`
- [Action Validator](https://github.com/2555jaa/university-agent/blob/master/app/security/validator.py): `app/security/validator.py`
- [Safe File Service](https://github.com/2555jaa/university-agent/blob/master/app/services/file_service.py): `app/services/file_service.py`
- [Execution Sandbox](https://github.com/2555jaa/university-agent/blob/master/app/security/sandbox.py): `app/security/sandbox.py`
- [Audit Logger](https://github.com/2555jaa/university-agent/blob/master/app/security/audit.py): `app/security/audit.py`

### Other components

- **Student**
- **Cloud AI Service**
- **Ollama Service**

## Connections

- Student → Built-in Web UI: uses (evidence: `README.md`)
- Student → FastAPI Routes: submits requests (evidence: `README.md`)
- Built-in Web UI → FastAPI Routes: sends requests (evidence: `README.md`)
- FastAPI Routes → Agent Orchestrator: dispatches chat (evidence: `app/api/routes.py`)
- FastAPI Routes → Grounded RAG: handles documents (evidence: `app/api/routes.py`)
- FastAPI Routes → SQLite Study Memory: manages study records (evidence: `app/api/routes.py`)
- Agent Orchestrator → Mode Prompts: uses prompts (evidence: `app/agent/orchestrator.py`)
- Agent Orchestrator → Grounded RAG: retrieves context (evidence: `app/agent/orchestrator.py`)
- Agent Orchestrator → SQLite Study Memory: loads and saves (evidence: `app/agent/orchestrator.py`)
- Agent Orchestrator → Hybrid Model Router: routes inference (evidence: `app/agent/orchestrator.py`)
- Grounded RAG → Document Parser: parses documents (evidence: `app/knowledge/rag_service.py`)
- Grounded RAG → Sliding Chunker: creates chunks (evidence: `app/knowledge/rag_service.py`)
- Grounded RAG → Vector Index: indexes and searches (evidence: `app/knowledge/rag_service.py`)
- Vector Index → Embedding Manager: embeds text (evidence: `app/knowledge/vector_store.py`)
- Hybrid Model Router → Ollama Provider: selects local (evidence: `app/providers/router.py`)
- Hybrid Model Router → Cloud Provider: selects cloud (evidence: `app/providers/router.py`)
- Ollama Provider → Ollama Service: calls inference (evidence: `app/providers/ollama_provider.py`)
- Cloud Provider → Cloud AI Service: calls inference (evidence: `README.md`)
- Agent Orchestrator → Filesystem Tools: dispatches file tools (evidence: `app/agent/orchestrator.py`)
- Agent Orchestrator → Restricted Terminal: dispatches commands (evidence: `app/agent/orchestrator.py`)
- Filesystem Tools → Action Validator: validates actions (evidence: `app/tools/filesystem_tools.py`)
- Filesystem Tools → Safe File Service: delegates file access (evidence: `app/tools/filesystem_tools.py`)
- Restricted Terminal → Action Validator: checks permissions (evidence: `app/tools/terminal_tools.py`)
- Agent Orchestrator → Execution Sandbox: uses for execution (evidence: `app/agent/orchestrator.py`)
- Agent Orchestrator → Audit Logger: records activity (evidence: `app/agent/orchestrator.py`)
- Grounded RAG → Audit Logger: records deletion (evidence: `app/knowledge/rag_service.py`)
- Action Validator → Audit Logger: records decisions (evidence: `README.md`)
