# dminh-1810/unifs architecture

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

- Interactive diagram: https://gitdiagram.com/dminh-1810/unifs
- Repository: https://github.com/dminh-1810/unifs

## Overview

UniFs is a student academic-advising assistant for FPTU: students ask questions and receive personalized academic calculations, policy answers, and schedule or attendance guidance. The documented product also includes a nine-semester curriculum roadmap, OJT and graduation eligibility checks, FE scoring, and FAP synchronization; the supplied tree has no app.py, so its Streamlit dashboard workflow cannot be traced here. The shown Telegram entry point authenticates students and routes questions through Gemini tools or keyword fallback. Edges reflect excerpts, SOURCE INDEX references, or README statements; unsampled dashboard wiring is omitted.

Main entry points: [`advisor.py`](https://github.com/dminh-1810/unifs/blob/main/advisor.py) (Academic calculations), [`telegram_bot.py`](https://github.com/dminh-1810/unifs/blob/main/telegram_bot.py) (Telegram bot), [`fallback.py`](https://github.com/dminh-1810/unifs/blob/main/fallback.py) (Keyword fallback), [`tools.py`](https://github.com/dminh-1810/unifs/blob/main/tools.py) (Function tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Student access"]
  node_telegram["Telegram bot<br/>[telegram_bot.py]"]
  node_gemini_agent["Gemini agent<br/>[llm.py]"]
  node_fallback["Keyword fallback<br/>[fallback.py]"]
end

subgraph group_advising["Academic advising"]
  node_tools["Function tools<br/>[tools.py]"]
  node_advisor["Academic calculations<br/>[advisor.py]"]
  node_fe_ojt["FE and OJT checks<br/>[advisor.py]"]
  node_curriculum["Curriculum roadmap<br/>[advisor.py]"]
  node_attendance["Schedule and attendance<br/>[advisor.py]"]
end

subgraph group_knowledge["Policy and syllabus"]
  node_policy_search["Hybrid policy search<br/>[policy_search.py]"]
  node_flm_store["Syllabus lookup<br/>[flm_store.py]"]
end

subgraph group_data["Data and synchronization"]
  node_sync_server["FAP sync server<br/>[server.py]"]
  node_data_loader["Data loader<br/>[data_loader.py]"]
  node_database[("Academic database<br/>[database.py]")]
  node_config["Academic configuration<br/>[config.py]"]
end

node_student(("Student"))
node_telegram_api(("Telegram service"))
node_embedding_service(("Gemini embeddings"))
node_fap_extension(("FAP browser extension"))

node_student -->|"asks questions"| node_telegram
node_telegram -->|"polls and replies"| node_telegram_api
node_telegram -->|"verifies login"| node_database
node_telegram -->|"routes question"| node_gemini_agent
node_telegram -->|"falls back"| node_fallback
node_telegram -->|"creates advisor"| node_advisor
node_gemini_agent -->|"builds tools"| node_tools
node_tools -->|"calls calculations"| node_advisor
node_tools -->|"searches policies"| node_policy_search
node_tools -->|"looks up syllabus"| node_flm_store
node_fallback -->|"calls calculations"| node_advisor
node_fallback -->|"searches policies"| node_policy_search
node_fallback -->|"looks up syllabus"| node_flm_store
node_advisor -->|"loads student data"| node_data_loader
node_advisor -->|"uses academic rules"| node_config
node_data_loader -->|"fetches records"| node_database
node_policy_search -->|"loads policy chunks"| node_data_loader
node_policy_search -.->|"requests embeddings"| node_embedding_service
node_sync_server -->|"stores FAP sync"| node_database
node_fap_extension -->|"posts synced data"| node_sync_server
node_sync_server -->|"writes syllabus data"| node_flm_store
node_fe_ojt -->|"implemented in"| node_advisor
node_curriculum -->|"implemented in"| node_advisor
node_attendance -->|"implemented in"| node_advisor

click node_telegram "https://github.com/dminh-1810/unifs/blob/main/telegram_bot.py"
click node_gemini_agent "https://github.com/dminh-1810/unifs/blob/main/llm.py"
click node_fallback "https://github.com/dminh-1810/unifs/blob/main/fallback.py"
click node_tools "https://github.com/dminh-1810/unifs/blob/main/tools.py"
click node_advisor "https://github.com/dminh-1810/unifs/blob/main/advisor.py"
click node_fe_ojt "https://github.com/dminh-1810/unifs/blob/main/advisor.py"
click node_curriculum "https://github.com/dminh-1810/unifs/blob/main/advisor.py"
click node_attendance "https://github.com/dminh-1810/unifs/blob/main/advisor.py"
click node_policy_search "https://github.com/dminh-1810/unifs/blob/main/policy_search.py"
click node_flm_store "https://github.com/dminh-1810/unifs/blob/main/flm_store.py"
click node_sync_server "https://github.com/dminh-1810/unifs/blob/main/server.py"
click node_data_loader "https://github.com/dminh-1810/unifs/blob/main/data_loader.py"
click node_database "https://github.com/dminh-1810/unifs/blob/main/database.py"
click node_config "https://github.com/dminh-1810/unifs/blob/main/config.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_telegram,node_gemini_agent,node_fallback,node_fap_extension toneBlue
class node_tools,node_advisor,node_fe_ojt,node_curriculum,node_attendance toneAmber
class node_policy_search,node_flm_store toneMint
class node_sync_server,node_data_loader,node_database,node_config toneRose
class node_student,node_telegram_api,node_embedding_service toneIndigo
```

## Components

### Student access

- [Telegram bot](https://github.com/dminh-1810/unifs/blob/main/telegram_bot.py): `telegram_bot.py`
- [Gemini agent](https://github.com/dminh-1810/unifs/blob/main/llm.py): `llm.py`
- [Keyword fallback](https://github.com/dminh-1810/unifs/blob/main/fallback.py): `fallback.py`

### Academic advising

- [Function tools](https://github.com/dminh-1810/unifs/blob/main/tools.py): `tools.py`
- [Academic calculations](https://github.com/dminh-1810/unifs/blob/main/advisor.py): `advisor.py`
- [FE and OJT checks](https://github.com/dminh-1810/unifs/blob/main/advisor.py): `advisor.py`
- [Curriculum roadmap](https://github.com/dminh-1810/unifs/blob/main/advisor.py): `advisor.py`
- [Schedule and attendance](https://github.com/dminh-1810/unifs/blob/main/advisor.py): `advisor.py`

### Policy and syllabus

- [Hybrid policy search](https://github.com/dminh-1810/unifs/blob/main/policy_search.py): `policy_search.py`
- [Syllabus lookup](https://github.com/dminh-1810/unifs/blob/main/flm_store.py): `flm_store.py`

### Data and synchronization

- [FAP sync server](https://github.com/dminh-1810/unifs/blob/main/server.py): `server.py`
- [Data loader](https://github.com/dminh-1810/unifs/blob/main/data_loader.py): `data_loader.py`
- [Academic database](https://github.com/dminh-1810/unifs/blob/main/database.py): `database.py`
- [Academic configuration](https://github.com/dminh-1810/unifs/blob/main/config.py): `config.py`

### Other components

- **Student**
- **Telegram service**
- **Gemini embeddings**
- **FAP browser extension**

## Connections

- Student → Telegram bot: asks questions (evidence: `README.md`)
- Telegram bot → Telegram service: polls and replies (evidence: `telegram_bot.py`)
- Telegram bot → Academic database: verifies login (evidence: `telegram_bot.py`)
- Telegram bot → Gemini agent: routes question (evidence: `telegram_bot.py`)
- Telegram bot → Keyword fallback: falls back (evidence: `telegram_bot.py`)
- Telegram bot → Academic calculations: creates advisor (evidence: `telegram_bot.py`)
- Gemini agent → Function tools: builds tools (evidence: `llm.py`)
- Function tools → Academic calculations: calls calculations (evidence: `tools.py`)
- Function tools → Hybrid policy search: searches policies (evidence: `tools.py`)
- Function tools → Syllabus lookup: looks up syllabus (evidence: `tools.py`)
- Keyword fallback → Academic calculations: calls calculations (evidence: `fallback.py`)
- Keyword fallback → Hybrid policy search: searches policies (evidence: `fallback.py`)
- Keyword fallback → Syllabus lookup: looks up syllabus (evidence: `fallback.py`)
- Academic calculations → Data loader: loads student data (evidence: `advisor.py`)
- Academic calculations → Academic configuration: uses academic rules (evidence: `advisor.py`)
- Data loader → Academic database: fetches records (evidence: `data_loader.py`)
- Hybrid policy search → Data loader: loads policy chunks (evidence: `policy_search.py`)
- Hybrid policy search → Gemini embeddings: requests embeddings (evidence: `policy_search.py`)
- FAP sync server → Academic database: stores FAP sync (evidence: `server.py`)
- FAP browser extension → FAP sync server: posts synced data (evidence: `README.md`)
- FAP sync server → Syllabus lookup: writes syllabus data (evidence: `server.py`)
- FE and OJT checks → Academic calculations: implemented in (evidence: `README.md`)
- Curriculum roadmap → Academic calculations: implemented in (evidence: `README.md`)
- Schedule and attendance → Academic calculations: implemented in (evidence: `README.md`)