# khanhlc2005/unicompare architecture

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

- Interactive diagram: https://gitdiagram.com/khanhlc2005/unicompare
- Repository: https://github.com/khanhlc2005/unicompare

## Overview

UniCompare is a desktop university search, comparison, watchlist, and recommendation application. Users search and filter university records, inspect details, save or select schools, then compare up to five; alternatively, they enter a profile to receive rule-scored recommendations and optional AI explanations/chat. Admins manage university records. The main window selects MongoDB or an in-memory fake repository, with sample data supporting offline use. Edges reflect README capability descriptions and sampled source; several UI pages and service implementations were not sampled, so uncertain internal calls are omitted.

Main entry points: [`services/university_service.py`](https://github.com/khanhlc2005/unicompare/blob/main/services/university_service.py) (University search), [`services/recommend_service.py`](https://github.com/khanhlc2005/unicompare/blob/main/services/recommend_service.py) (Rule scoring and AI), [`repositories/mongo_repo.py`](https://github.com/khanhlc2005/unicompare/blob/main/repositories/mongo_repo.py) (Mongo university repository), [`repositories/fake_repo.py`](https://github.com/khanhlc2005/unicompare/blob/main/repositories/fake_repo.py) (Sample-data repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Desktop interface"]
  node_main["Application entry<br/>[main.py]"]
  node_shell["App shell<br/>[app_shell.py]"]
  node_search["Search page<br/>[search_page.py]"]
  node_detail["University details<br/>[detail_page.py]"]
  node_watchlist_page["Watchlist page<br/>[watchlist_page.py]"]
  node_compare_page["Compare page<br/>[compare_page.py]"]
  node_chatbot["Recommendations and chat<br/>[chatbot_page.py]"]
  node_admin_view["Admin screen<br/>[admin_view.py]"]
end

subgraph group_domain["Application services"]
  node_university_service["University search"]
  node_compare_service["Compare selection<br/>[compare_service.py]"]
  node_watchlist_service["Watchlist operations"]
  node_wizard_service["Profile wizard<br/>[wizard_service.py]"]
  node_recommend_service["Rule scoring and AI"]
end

subgraph group_storage["Data repositories"]
  node_mongo_repo["Mongo university repository<br/>[mongo_repo.py]"]
  node_fake_repo["Sample-data repository<br/>[fake_repo.py]"]
  node_watchlist_repo["Watchlist repository<br/>[watchlist_repo.py]"]
  node_ai_cache_repo["AI response cache<br/>[ai_cache_repo.py]"]
  node_seed_data["Sample university data<br/>[seed_data.json]"]
end

subgraph group_integrations["External systems"]
  node_mongodb[("MongoDB")]
  node_gemini["Gemini API"]
end

node_student(("Student"))
node_admin(("Administrator"))

node_student -->|"uses"| node_shell
node_admin -->|"manages records"| node_admin_view
node_main -->|"starts"| node_shell
node_shell -->|"selects when available"| node_mongo_repo
node_shell -->|"falls back to"| node_fake_repo
node_fake_repo -->|"loads"| node_seed_data
node_search -->|"searches and filters"| node_university_service
node_university_service -->|"queries"| node_mongo_repo
node_university_service -->|"queries"| node_fake_repo
node_search -->|"selects schools"| node_compare_service
node_detail -->|"loads details"| node_university_service
node_detail -->|"saves school"| node_watchlist_service
node_watchlist_page -->|"reads saved schools"| node_watchlist_service
node_watchlist_page -->|"loads school data"| node_university_service
node_watchlist_page -->|"selects schools"| node_compare_service
node_compare_page -->|"reads selections"| node_compare_service
node_compare_page -->|"loads school data"| node_university_service
node_watchlist_service -->|"reads and writes"| node_watchlist_repo
node_watchlist_repo -->|"persists watchlist"| node_mongodb
node_chatbot -->|"validates profile"| node_wizard_service
node_chatbot -->|"requests recommendations"| node_recommend_service
node_recommend_service -->|"gets universities"| node_mongo_repo
node_recommend_service -->|"gets universities"| node_fake_repo
node_recommend_service -->|"checks and stores"| node_ai_cache_repo
node_ai_cache_repo -->|"persists cache"| node_mongodb
node_recommend_service -.->|"requests explanations"| node_gemini
node_chatbot -.->|"sends chat"| node_gemini
node_admin_view -->|"adds edits deletes"| node_mongo_repo
node_admin_view -->|"adds edits deletes"| node_fake_repo
node_mongo_repo -->|"reads and writes"| node_mongodb

click node_main "https://github.com/khanhlc2005/unicompare/blob/main/main.py"
click node_shell "https://github.com/khanhlc2005/unicompare/blob/main/views/app_shell.py"
click node_search "https://github.com/khanhlc2005/unicompare/blob/main/views/components/search_page.py"
click node_detail "https://github.com/khanhlc2005/unicompare/blob/main/views/components/detail_page.py"
click node_watchlist_page "https://github.com/khanhlc2005/unicompare/blob/main/views/components/watchlist_page.py"
click node_compare_page "https://github.com/khanhlc2005/unicompare/blob/main/views/components/compare_page.py"
click node_chatbot "https://github.com/khanhlc2005/unicompare/blob/main/views/components/chatbot_page.py"
click node_admin_view "https://github.com/khanhlc2005/unicompare/blob/main/views/admin_view.py"
click node_university_service "https://github.com/khanhlc2005/unicompare/blob/main/services/university_service.py"
click node_compare_service "https://github.com/khanhlc2005/unicompare/blob/main/services/compare_service.py"
click node_watchlist_service "https://github.com/khanhlc2005/unicompare/blob/main/services/watchlist_service.py"
click node_wizard_service "https://github.com/khanhlc2005/unicompare/blob/main/services/wizard_service.py"
click node_recommend_service "https://github.com/khanhlc2005/unicompare/blob/main/services/recommend_service.py"
click node_mongo_repo "https://github.com/khanhlc2005/unicompare/blob/main/repositories/mongo_repo.py"
click node_fake_repo "https://github.com/khanhlc2005/unicompare/blob/main/repositories/fake_repo.py"
click node_watchlist_repo "https://github.com/khanhlc2005/unicompare/blob/main/repositories/watchlist_repo.py"
click node_ai_cache_repo "https://github.com/khanhlc2005/unicompare/blob/main/repositories/ai_cache_repo.py"
click node_seed_data "https://github.com/khanhlc2005/unicompare/blob/main/data/seed_data.json"

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_main,node_shell,node_search,node_detail,node_watchlist_page,node_compare_page,node_chatbot,node_admin_view toneBlue
class node_university_service,node_compare_service,node_watchlist_service,node_wizard_service,node_recommend_service toneAmber
class node_mongo_repo,node_fake_repo,node_watchlist_repo,node_ai_cache_repo,node_seed_data toneMint
class node_mongodb,node_gemini toneRose
class node_student,node_admin toneIndigo
```

## Components

### Desktop interface

- [Application entry](https://github.com/khanhlc2005/unicompare/blob/main/main.py): `main.py`
- [App shell](https://github.com/khanhlc2005/unicompare/blob/main/views/app_shell.py): `views/app_shell.py`
- [Search page](https://github.com/khanhlc2005/unicompare/blob/main/views/components/search_page.py): `views/components/search_page.py`
- [University details](https://github.com/khanhlc2005/unicompare/blob/main/views/components/detail_page.py): `views/components/detail_page.py`
- [Watchlist page](https://github.com/khanhlc2005/unicompare/blob/main/views/components/watchlist_page.py): `views/components/watchlist_page.py`
- [Compare page](https://github.com/khanhlc2005/unicompare/blob/main/views/components/compare_page.py): `views/components/compare_page.py`
- [Recommendations and chat](https://github.com/khanhlc2005/unicompare/blob/main/views/components/chatbot_page.py): `views/components/chatbot_page.py`
- [Admin screen](https://github.com/khanhlc2005/unicompare/blob/main/views/admin_view.py): `views/admin_view.py`

### Application services

- [University search](https://github.com/khanhlc2005/unicompare/blob/main/services/university_service.py): `services/university_service.py`
- [Compare selection](https://github.com/khanhlc2005/unicompare/blob/main/services/compare_service.py): `services/compare_service.py`
- [Watchlist operations](https://github.com/khanhlc2005/unicompare/blob/main/services/watchlist_service.py): `services/watchlist_service.py`
- [Profile wizard](https://github.com/khanhlc2005/unicompare/blob/main/services/wizard_service.py): `services/wizard_service.py`
- [Rule scoring and AI](https://github.com/khanhlc2005/unicompare/blob/main/services/recommend_service.py): `services/recommend_service.py`

### Data repositories

- [Mongo university repository](https://github.com/khanhlc2005/unicompare/blob/main/repositories/mongo_repo.py): `repositories/mongo_repo.py`
- [Sample-data repository](https://github.com/khanhlc2005/unicompare/blob/main/repositories/fake_repo.py): `repositories/fake_repo.py`
- [Watchlist repository](https://github.com/khanhlc2005/unicompare/blob/main/repositories/watchlist_repo.py): `repositories/watchlist_repo.py`
- [AI response cache](https://github.com/khanhlc2005/unicompare/blob/main/repositories/ai_cache_repo.py): `repositories/ai_cache_repo.py`
- [Sample university data](https://github.com/khanhlc2005/unicompare/blob/main/data/seed_data.json): `data/seed_data.json`

### External systems

- **MongoDB**
- **Gemini API**

### Other components

- **Student**
- **Administrator**

## Connections

- Student → App shell: uses
- Administrator → Admin screen: manages records
- Application entry → App shell: starts
- App shell → Mongo university repository: selects when available
- App shell → Sample-data repository: falls back to
- Sample-data repository → Sample university data: loads
- Search page → University search: searches and filters
- University search → Mongo university repository: queries
- University search → Sample-data repository: queries
- Search page → Compare selection: selects schools
- University details → University search: loads details
- University details → Watchlist operations: saves school
- Watchlist page → Watchlist operations: reads saved schools
- Watchlist page → University search: loads school data
- Watchlist page → Compare selection: selects schools
- Compare page → Compare selection: reads selections
- Compare page → University search: loads school data
- Watchlist operations → Watchlist repository: reads and writes
- Watchlist repository → MongoDB: persists watchlist
- Recommendations and chat → Profile wizard: validates profile
- Recommendations and chat → Rule scoring and AI: requests recommendations
- Rule scoring and AI → Mongo university repository: gets universities
- Rule scoring and AI → Sample-data repository: gets universities
- Rule scoring and AI → AI response cache: checks and stores
- AI response cache → MongoDB: persists cache
- Rule scoring and AI → Gemini API: requests explanations
- Recommendations and chat → Gemini API: sends chat
- Admin screen → Mongo university repository: adds edits deletes
- Admin screen → Sample-data repository: adds edits deletes
- Mongo university repository → MongoDB: reads and writes