# ram333n/uni-agent architecture

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

- Interactive diagram: https://gitdiagram.com/ram333n/uni-agent
- Repository: https://github.com/ram333n/uni-agent

## Overview

Uni Agent combines a Chainlit conversational assistant with a faculty-document MCP service and a Flask dataset-labeling utility. The principal workflow is a user message entering the chat application, being handled by the agent, and optionally invoking faculty semantic search through MCP before returning an answer. Separately, document uploads are parsed, split, embedded, and indexed; REST endpoints also support search and deletion. The README identifies labeling and evaluation datasets as supporting capabilities. Some subsystem links are documented rather than source-verified, so those links are dashed; unsampled implementation details are not inferred.

Main entry points: [`mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/service/impl/FacultyDocumentServiceImpl.java`](https://github.com/ram333n/uni-agent/blob/main/mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/service/impl/FacultyDocumentServiceImpl.java) (Document service), [`agent/src/agent/agent.py`](https://github.com/ram333n/uni-agent/blob/main/agent/src/agent/agent.py) (Agent orchestration), [`mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/controller/mcp/FacultyMcpController.java`](https://github.com/ram333n/uni-agent/blob/main/mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/controller/mcp/FacultyMcpController.java) (Faculty MCP server), [`mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/controller/rest/DocumentController.java`](https://github.com/ram333n/uni-agent/blob/main/mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/controller/rest/DocumentController.java) (Document REST API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_chat["Chat agent"]
  node_chat_app["Chainlit app<br/>[app.py]"]
  node_agent["Agent orchestration<br/>[agent.py]"]
  node_prompts["System prompt<br/>[prompts.py]"]
  node_host_tools["Host tools<br/>[tools.py]"]
end

subgraph group_faculty_api["Faculty search API"]
  node_faculty_mcp["Faculty MCP server"]
  node_rest_api["Document REST API"]
  node_doc_service["Document service"]
  node_search_request["Search request"]
  node_search_results["Search results"]
  node_result_entry["Result entry"]
end

subgraph group_faculty_data["Document indexing"]
  node_splitter["Document splitter"]
  node_token_estimator["Token estimator"]
  node_file_service["File storage service"]
  node_storage_config["Storage settings"]
  node_doc_repository["Document repository"]
  node_faculty_docs[("Document metadata")]
end

subgraph group_label_eval["Labeling and evaluation"]
  node_label_tool["Labeling web app<br/>[app.py]"]
  node_label_ui["Labeling UI<br/>[app.js]"]
  node_eval_data[("Evaluation datasets")]
  node_benchmarks["Search benchmarks"]
end

node_user(("User"))
node_llm{{"Groq LLM"}}
node_vector_store[("PostgreSQL pgvector")]

node_user -.->|"sends message"| node_chat_app
node_chat_app -->|"initializes"| node_agent
node_agent -->|"uses prompt"| node_prompts
node_agent -->|"registers tools"| node_host_tools
node_agent -->|"calls model"| node_llm
node_agent -->|"fetches MCP tools"| node_faculty_mcp
node_faculty_mcp -->|"searches via"| node_doc_service
node_faculty_mcp -->|"accepts"| node_search_request
node_faculty_mcp -->|"returns"| node_search_results
node_rest_api -->|"delegates"| node_doc_service
node_rest_api -->|"accepts"| node_search_request
node_rest_api -->|"returns"| node_search_results
node_doc_service -->|"reads and writes"| node_doc_repository
node_doc_repository -->|"persists"| node_faculty_docs
node_doc_service -->|"stores files"| node_file_service
node_file_service -->|"uses settings"| node_storage_config
node_doc_service -->|"adds and searches"| node_vector_store
node_doc_service -.->|"transforms chunks"| node_splitter
node_splitter -->|"estimates tokens"| node_token_estimator
node_doc_service -->|"maps results"| node_result_entry
node_search_results -->|"contains"| node_result_entry
node_label_tool -.->|"serves UI"| node_label_ui
node_user -.->|"labels datasets"| node_label_tool
node_eval_data -.->|"supports labeling"| node_label_tool

click node_chat_app "https://github.com/ram333n/uni-agent/blob/main/agent/src/application/app.py"
click node_agent "https://github.com/ram333n/uni-agent/blob/main/agent/src/agent/agent.py"
click node_prompts "https://github.com/ram333n/uni-agent/blob/main/agent/src/agent/prompts.py"
click node_host_tools "https://github.com/ram333n/uni-agent/blob/main/agent/src/agent/tools.py"
click node_faculty_mcp "https://github.com/ram333n/uni-agent/blob/main/mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/controller/mcp/FacultyMcpController.java"
click node_rest_api "https://github.com/ram333n/uni-agent/blob/main/mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/controller/rest/DocumentController.java"
click node_doc_service "https://github.com/ram333n/uni-agent/blob/main/mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/service/impl/FacultyDocumentServiceImpl.java"
click node_search_request "https://github.com/ram333n/uni-agent/blob/main/mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/common/dto/SemanticSearchRequest.java"
click node_search_results "https://github.com/ram333n/uni-agent/blob/main/mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/common/dto/SemanticSearchResults.java"
click node_result_entry "https://github.com/ram333n/uni-agent/blob/main/mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/common/dto/SemanticSearchResultEntry.java"
click node_splitter "https://github.com/ram333n/uni-agent/blob/main/mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/ingestion/splitter/OverlappingDocumentSplitter.java"
click node_token_estimator "https://github.com/ram333n/uni-agent/blob/main/mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/ingestion/splitter/CL100KTokenEstimator.java"
click node_file_service "https://github.com/ram333n/uni-agent/blob/main/mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/service/impl/FileServiceImpl.java"
click node_storage_config "https://github.com/ram333n/uni-agent/blob/main/mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/config/properties/StorageProperties.java"
click node_doc_repository "https://github.com/ram333n/uni-agent/blob/main/mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/repository/FacultyDocumentRepository.java"
click node_faculty_docs "https://github.com/ram333n/uni-agent/blob/main/mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/domain/FacultyDocument.java"
click node_label_tool "https://github.com/ram333n/uni-agent/blob/main/labeling-tool/app/app.py"
click node_label_ui "https://github.com/ram333n/uni-agent/blob/main/labeling-tool/app/static/app.js"
click node_eval_data "https://github.com/ram333n/uni-agent/tree/main/test-dataset"
click node_benchmarks "https://github.com/ram333n/uni-agent/tree/main/metrics"

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_chat_app,node_agent,node_prompts,node_host_tools,node_user toneBlue
class node_faculty_mcp,node_rest_api,node_doc_service,node_search_request,node_search_results,node_result_entry,node_vector_store toneAmber
class node_splitter,node_token_estimator,node_file_service,node_storage_config,node_doc_repository,node_faculty_docs toneMint
class node_label_tool,node_label_ui,node_eval_data,node_benchmarks toneRose
class node_llm toneIndigo
```

## Components

### Chat agent

- [Chainlit app](https://github.com/ram333n/uni-agent/blob/main/agent/src/application/app.py): `agent/src/application/app.py`
- [Agent orchestration](https://github.com/ram333n/uni-agent/blob/main/agent/src/agent/agent.py): `agent/src/agent/agent.py`
- [System prompt](https://github.com/ram333n/uni-agent/blob/main/agent/src/agent/prompts.py): `agent/src/agent/prompts.py`
- [Host tools](https://github.com/ram333n/uni-agent/blob/main/agent/src/agent/tools.py): `agent/src/agent/tools.py`

### Faculty search API

- [Faculty MCP server](https://github.com/ram333n/uni-agent/blob/main/mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/controller/mcp/FacultyMcpController.java): `mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/controller/mcp/FacultyMcpController.java`
- [Document REST API](https://github.com/ram333n/uni-agent/blob/main/mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/controller/rest/DocumentController.java): `mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/controller/rest/DocumentController.java`
- [Document service](https://github.com/ram333n/uni-agent/blob/main/mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/service/impl/FacultyDocumentServiceImpl.java): `mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/service/impl/FacultyDocumentServiceImpl.java`
- [Search request](https://github.com/ram333n/uni-agent/blob/main/mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/common/dto/SemanticSearchRequest.java): `mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/common/dto/SemanticSearchRequest.java`
- [Search results](https://github.com/ram333n/uni-agent/blob/main/mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/common/dto/SemanticSearchResults.java): `mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/common/dto/SemanticSearchResults.java`
- [Result entry](https://github.com/ram333n/uni-agent/blob/main/mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/common/dto/SemanticSearchResultEntry.java): `mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/common/dto/SemanticSearchResultEntry.java`

### Document indexing

- [Document splitter](https://github.com/ram333n/uni-agent/blob/main/mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/ingestion/splitter/OverlappingDocumentSplitter.java): `mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/ingestion/splitter/OverlappingDocumentSplitter.java`
- [Token estimator](https://github.com/ram333n/uni-agent/blob/main/mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/ingestion/splitter/CL100KTokenEstimator.java): `mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/ingestion/splitter/CL100KTokenEstimator.java`
- [File storage service](https://github.com/ram333n/uni-agent/blob/main/mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/service/impl/FileServiceImpl.java): `mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/service/impl/FileServiceImpl.java`
- [Storage settings](https://github.com/ram333n/uni-agent/blob/main/mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/config/properties/StorageProperties.java): `mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/config/properties/StorageProperties.java`
- [Document repository](https://github.com/ram333n/uni-agent/blob/main/mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/repository/FacultyDocumentRepository.java): `mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/repository/FacultyDocumentRepository.java`
- [Document metadata](https://github.com/ram333n/uni-agent/blob/main/mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/domain/FacultyDocument.java): `mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/domain/FacultyDocument.java`

### Labeling and evaluation

- [Labeling web app](https://github.com/ram333n/uni-agent/blob/main/labeling-tool/app/app.py): `labeling-tool/app/app.py`
- [Labeling UI](https://github.com/ram333n/uni-agent/blob/main/labeling-tool/app/static/app.js): `labeling-tool/app/static/app.js`
- [Evaluation datasets](https://github.com/ram333n/uni-agent/tree/main/test-dataset): `test-dataset`
- [Search benchmarks](https://github.com/ram333n/uni-agent/tree/main/metrics): `metrics`

### Other components

- **User**
- **Groq LLM**
- **PostgreSQL pgvector**

## Connections

- User → Chainlit app: sends message (evidence: `README.md`)
- Chainlit app → Agent orchestration: initializes (evidence: `agent/src/application/app.py`)
- Agent orchestration → System prompt: uses prompt (evidence: `agent/src/agent/agent.py`)
- Agent orchestration → Host tools: registers tools (evidence: `agent/src/agent/agent.py`)
- Agent orchestration → Groq LLM: calls model (evidence: `agent/src/agent/agent.py`)
- Agent orchestration → Faculty MCP server: fetches MCP tools (evidence: `agent/src/agent/agent.py`)
- Faculty MCP server → Document service: searches via (evidence: `mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/controller/mcp/FacultyMcpController.java`)
- Faculty MCP server → Search request: accepts (evidence: `mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/controller/mcp/FacultyMcpController.java`)
- Faculty MCP server → Search results: returns (evidence: `mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/controller/mcp/FacultyMcpController.java`)
- Document REST API → Document service: delegates (evidence: `mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/controller/rest/DocumentController.java`)
- Document REST API → Search request: accepts (evidence: `mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/controller/rest/DocumentController.java`)
- Document REST API → Search results: returns (evidence: `mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/controller/rest/DocumentController.java`)
- Document service → Document repository: reads and writes (evidence: `mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/service/impl/FacultyDocumentServiceImpl.java`)
- Document repository → Document metadata: persists (evidence: `mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/repository/FacultyDocumentRepository.java`)
- Document service → File storage service: stores files (evidence: `mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/service/impl/FacultyDocumentServiceImpl.java`)
- File storage service → Storage settings: uses settings (evidence: `mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/service/impl/FileServiceImpl.java`)
- Document service → PostgreSQL pgvector: adds and searches (evidence: `mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/service/impl/FacultyDocumentServiceImpl.java`)
- Document service → Document splitter: transforms chunks
- Document splitter → Token estimator: estimates tokens (evidence: `mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/ingestion/splitter/OverlappingDocumentSplitter.java`)
- Document service → Result entry: maps results (evidence: `mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/service/impl/FacultyDocumentServiceImpl.java`)
- Search results → Result entry: contains (evidence: `mcp-servers/faculty-mcp-server/src/main/java/org/prokopchuk/facultymcpserver/common/dto/SemanticSearchResults.java`)
- Labeling web app → Labeling UI: serves UI
- User → Labeling web app: labels datasets (evidence: `README.md`)
- Evaluation datasets → Labeling web app: supports labeling (evidence: `README.md`)
