# haowasabi/tuvantuyensinh architecture

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

- Interactive diagram: https://gitdiagram.com/haowasabi/tuvantuyensinh
- Repository: https://github.com/haowasabi/tuvantuyensinh

## Overview

1. **Overall shape**
   - This is a **Java desktop application** for admissions consulting, not a web app.
   - The architecture is a classic **layered Swing + Hibernate** stack: **UI views → services → repositories → database models**.
   - The package layout under `com.tuyensinh` is the main clue: `view`, `service`, `repository`, `model`, and `database`.

2. **Presentation layer**
   - The `view` package contains the full Swing UI: login screens, admin/user main frames, sidebars/top bars, panels, dialogs, and import forms.
   - There are two main UX paths:
     - **Admin side**: `AdminLoginFrame`, `AdminMainFrame`, management panels for candidates, majors, roles, users, scores, preferences, and reports.
     - **User side**: `UserLoginFrame`, `UserMainFrame`, `PersonalInfoPanel`, `XetTuyenPanel`, and `KetQuaPanel`.
   - The UI is stateful and screen-based, with panels such as `DashboardPanel`, `LazyPanelCard`, and `Sidebar` suggesting navigation inside a single desktop shell.

3. **Authentication and access control**
   - Authentication is handled by `AuthService`, `SessionManager`, `UserService`, and `RoleService`.
   - The presence of `Role`, `RolePermission`, `RolePermissionId`, and `PermissionCatalog` indicates a **role-based permission model**.
   - `RoleSelectionFrame` and separate admin/user login frames suggest the app chooses behavior and available screens based on the authenticated role.

4. **Domain model**
   - The `model` package defines the core admissions entities:
     - `ThiSinh` for candidates
     - `Nganh` for majors
     - `NguyenVong` for preferences/wish lists
     - `DiemThi` for exam scores
     - `DiemCong` for bonus points
     - `BangQuyDoi` and `TohopMonthi` for conversion tables and subject combinations
     - `NganhToHop` for the relationship between majors and subject groups
     - `User`, `Role`, and permission entities for account management
   - These models are the persistence boundary and likely mirror database tables closely.

5. **Persistence layer**
   - The `repository` package isolates database access per entity: `ThiSinhRepository`, `NganhRepository`, `NguyenVongRepository`, `DiemThiRepository`, `DiemCongRepository`, `UserRepository`, `RoleRepository`, etc.
   - This is a **DAO/repository pattern** on top of Hibernate/JPA-style entities.
   - `HibernateUtil` and the `hibernate.cfg.xml` resource show that ORM is the main persistence mechanism rather than direct JDBC.

6. **Business logic layer**
   - The `service` package contains the actual use-case logic, including:
     - CRUD orchestration for candidates, majors, scores, preferences, roles, and users
     - admissions calculation in `XetTuyenService`
     - import/export and conversion logic in services like `BQDService`, `NTHService`, `TohopMonthiService`
   - This layer is the main separation point between UI and data access, and it likely centralizes validation, transaction boundaries, and application rules.

7. **Admissions workflow**
   - The core domain flow appears to be:
     1. Maintain candidate, major, subject-group, and bonus-score data.
     2. Import/export supporting tables from Excel.
     3. Run admissions evaluation via `XetTuyenService`.
     4. Display results in `KetQuaPanel` and reporting screens.
   - The app seems designed to support **candidate admissions decision-making**, not just record storage.

8. **Excel-driven data ingestion**
   - Several dialogs and resources indicate heavy use of Excel import/export:
     - `ImportExcelDialog`, `ImportDTExcelDialog`, `ImportDCExcelDialog`, `ImportNVExcelDialog`, `MajorImportExcelDialog`
     - sample files in `src/main/resources` such as `Ds thi sinh.xlsx`, `nganh_test.xlsx`, `nguyenvong_test.xlsx`
   - There are also source assets in `src/main/java/com/tuyensinh/database` like `Ds quy doi tieng Anh.xlsx` and `Uu tien xet tuyen.xlsx`.
   - This suggests the system is built around **bulk academic data preparation**, not manual-only CRUD.

9. **Database and seed assets**
   - `xettuyen2026.sql` is the primary database script/seed artifact, implying the schema and starter data can be provisioned from SQL.
   - The repository also includes a `SeedLoginAccount` utility, which likely creates default admin/user accounts for first-run access.
   - `DatabaseConnectionTest` and `BackendAuthTest` imply the application expects a configured DB and authenticated runtime state.

10. **Testing boundary**
   - Tests are split across domain and service behavior:
     - model/domain tests like `DiemCongTest`, `DiemThiTest`, `NganhTest`, `NguyenVongTest`, `TohopMonthiTest`
     - service tests like `ServiceTestBQD`, `ServiceTestNTH`, `ServiceTestRole`, `ServiceTestThiSinh`, `ServiceTestUser`
   - This indicates a strong emphasis on validating business rules separately from the UI, which is important for the admissions calculation logic.

11. **Execution and tooling**
   - The project is built with **Maven** (`pom.xml`), run as a Java desktop program (`Main.java`), and supported by platform scripts such as `compile-java.ps1` and `run-java.ps1`.
   - Python utilities (`read_excel.py`, `check_zeros.py`, `update_sql.py`) appear to support data preparation or validation around Excel/SQL assets.
   - These are auxiliary tools, but they matter because the project relies on imported academic datasets.

12. **Documentation and design artifacts**
   - `docs/erd.md` and `docs/prd.md` indicate the team documented both the **data model** and the **product requirements**.
   - The PDF/LaTeX report files suggest the repository is also the submission source for the course deliverable, not just the runnable codebase.
   - For architecture diagrams, the most important boundaries are: **Swing UI**, **service/business layer**, **Hibernate repositories**, and **SQL/Excel-backed data sources**.

Main entry points: [`src/main/java/com/tuyensinh/repository`](https://github.com/haowasabi/tuvantuyensinh/tree/main/src/main/java/com/tuyensinh/repository) (Repositories), [`src/main/java/com/tuyensinh/service/AuthService.java`](https://github.com/haowasabi/tuvantuyensinh/blob/main/src/main/java/com/tuyensinh/service/AuthService.java) (Auth), [`src/main/java/com/tuyensinh/service/UserService.java`](https://github.com/haowasabi/tuvantuyensinh/blob/main/src/main/java/com/tuyensinh/service/UserService.java) (Accounts), [`src/main/java/com/tuyensinh/view/RoleSelectionFrame.java`](https://github.com/haowasabi/tuvantuyensinh/blob/main/src/main/java/com/tuyensinh/view/RoleSelectionFrame.java) (Role Select)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_main(("Main<br/>desktop entry<br/>[Main.java]"))
  node_role_selection["Role Select<br/>role gate"]
  node_admin_shell["Admin Shell<br/>admin frame"]
  node_user_shell["User Shell<br/>user frame<br/>[UserMainFrame.java]"]
  node_admin_views["Admin Views<br/>admin panels"]
  node_user_views["User Views<br/>user panels"]
end

subgraph group_service["Service Layer"]
  node_auth_service{{"Auth<br/>[AuthService.java]"}}
  node_session_service{{"Session"}}
  node_account_service{{"Accounts<br/>user-role service<br/>[UserService.java]"}}
  node_admissions_service{{"Admissions<br/>domain service"}}
  node_import_service{{"Import/Convert<br/>data prep service<br/>[BQDService.java]"}}
end

subgraph group_persistence["Persistence"]
  node_hibernate_util[("Hibernate<br/>orm bootstrap<br/>[HibernateUtil.java]")]
  node_repositories["Repositories<br/>dao layer"]
end

subgraph group_domain["Domain Model"]
  node_admissions_model["Admissions Models<br/>candidate-major model"]
  node_security_model["Access Models<br/>account model"]
end

subgraph group_data["Data Assets"]
  node_sql_seed["SQL Seed<br/>schema seed<br/>[xettuyen2026.sql]"]
  node_excel_assets["Excel Assets<br/>import data"]
  node_seed_login(("Seed Login<br/>bootstrap utility"))
end

node_main -->|"launches"| node_role_selection
node_role_selection -->|"admin path"| node_admin_shell
node_role_selection -->|"user path"| node_user_shell
node_admin_shell -->|"hosts"| node_admin_views
node_user_shell -->|"hosts"| node_user_views
node_admin_views -->|"checks"| node_auth_service
node_user_views -->|"checks"| node_auth_service
node_auth_service -->|"uses"| node_session_service
node_auth_service -->|"delegates"| node_account_service
node_account_service -->|"manages"| node_security_model
node_admissions_service -->|"operates on"| node_admissions_model
node_import_service -->|"reads/writes"| node_excel_assets
node_admissions_service -->|"persists via"| node_repositories
node_account_service -->|"persists via"| node_repositories
node_repositories -->|"opens sessions"| node_hibernate_util
node_repositories -->|"maps"| node_admissions_model
node_repositories -->|"maps"| node_security_model
node_seed_login -->|"bootstraps"| node_account_service
node_sql_seed -->|"initializes"| node_hibernate_util
node_excel_assets -->|"feeds"| node_import_service

click node_main "https://github.com/haowasabi/tuvantuyensinh/blob/main/src/main/java/com/tuyensinh/Main.java"
click node_role_selection "https://github.com/haowasabi/tuvantuyensinh/blob/main/src/main/java/com/tuyensinh/view/RoleSelectionFrame.java"
click node_admin_shell "https://github.com/haowasabi/tuvantuyensinh/blob/main/src/main/java/com/tuyensinh/view/AdminMainFrame.java"
click node_user_shell "https://github.com/haowasabi/tuvantuyensinh/blob/main/src/main/java/com/tuyensinh/view/UserMainFrame.java"
click node_admin_views "https://github.com/haowasabi/tuvantuyensinh/tree/main/src/main/java/com/tuyensinh/view"
click node_user_views "https://github.com/haowasabi/tuvantuyensinh/tree/main/src/main/java/com/tuyensinh/view"
click node_auth_service "https://github.com/haowasabi/tuvantuyensinh/blob/main/src/main/java/com/tuyensinh/service/AuthService.java"
click node_session_service "https://github.com/haowasabi/tuvantuyensinh/blob/main/src/main/java/com/tuyensinh/service/SessionManager.java"
click node_account_service "https://github.com/haowasabi/tuvantuyensinh/blob/main/src/main/java/com/tuyensinh/service/UserService.java"
click node_admissions_service "https://github.com/haowasabi/tuvantuyensinh/blob/main/src/main/java/com/tuyensinh/service/XetTuyenService.java"
click node_import_service "https://github.com/haowasabi/tuvantuyensinh/blob/main/src/main/java/com/tuyensinh/service/BQDService.java"
click node_hibernate_util "https://github.com/haowasabi/tuvantuyensinh/blob/main/src/main/java/com/tuyensinh/database/HibernateUtil.java"
click node_repositories "https://github.com/haowasabi/tuvantuyensinh/tree/main/src/main/java/com/tuyensinh/repository"
click node_admissions_model "https://github.com/haowasabi/tuvantuyensinh/tree/main/src/main/java/com/tuyensinh/model"
click node_security_model "https://github.com/haowasabi/tuvantuyensinh/tree/main/src/main/java/com/tuyensinh/model"
click node_sql_seed "https://github.com/haowasabi/tuvantuyensinh/blob/main/src/main/java/com/tuyensinh/database/xettuyen2026.sql"
click node_excel_assets "https://github.com/haowasabi/tuvantuyensinh/tree/main/src/main/resources"
click node_seed_login "https://github.com/haowasabi/tuvantuyensinh/blob/main/src/main/java/com/tuyensinh/SeedLoginAccount.java"

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_role_selection,node_admin_shell,node_user_shell,node_admin_views,node_user_views toneBlue
class node_auth_service,node_session_service,node_account_service,node_admissions_service,node_import_service toneAmber
class node_hibernate_util,node_repositories toneMint
class node_admissions_model,node_security_model toneRose
class node_sql_seed,node_excel_assets,node_seed_login toneIndigo
```

## Components

### Presentation

Swing desktop UI, screen navigation, and dialogs

- [Main](https://github.com/haowasabi/tuvantuyensinh/blob/main/src/main/java/com/tuyensinh/Main.java): desktop entry · Application bootstrap and startup flow · `src/main/java/com/tuyensinh/Main.java`
- [Role Select](https://github.com/haowasabi/tuvantuyensinh/blob/main/src/main/java/com/tuyensinh/view/RoleSelectionFrame.java): role gate · Chooses admin or user entry after login · `src/main/java/com/tuyensinh/view/RoleSelectionFrame.java`
- [Admin Shell](https://github.com/haowasabi/tuvantuyensinh/blob/main/src/main/java/com/tuyensinh/view/AdminMainFrame.java): admin frame · Admin desktop frame and navigation chrome · `src/main/java/com/tuyensinh/view/AdminMainFrame.java`
- [User Shell](https://github.com/haowasabi/tuvantuyensinh/blob/main/src/main/java/com/tuyensinh/view/UserMainFrame.java): user frame · User desktop frame and navigation chrome · `src/main/java/com/tuyensinh/view/UserMainFrame.java`
- [Admin Views](https://github.com/haowasabi/tuvantuyensinh/tree/main/src/main/java/com/tuyensinh/view): admin panels · Management screens for candidates, majors, scores, roles, users, and reports · `src/main/java/com/tuyensinh/view`
- [User Views](https://github.com/haowasabi/tuvantuyensinh/tree/main/src/main/java/com/tuyensinh/view): user panels · Personal info, application, and result screens · `src/main/java/com/tuyensinh/view`

### Service Layer

Authentication, admissions logic, and orchestration

- [Auth](https://github.com/haowasabi/tuvantuyensinh/blob/main/src/main/java/com/tuyensinh/service/AuthService.java): authentication service · Login, session, and permission checks · `src/main/java/com/tuyensinh/service/AuthService.java`
- [Session](https://github.com/haowasabi/tuvantuyensinh/blob/main/src/main/java/com/tuyensinh/service/SessionManager.java): session state · Tracks current authenticated user and role · `src/main/java/com/tuyensinh/service/SessionManager.java`
- [Accounts](https://github.com/haowasabi/tuvantuyensinh/blob/main/src/main/java/com/tuyensinh/service/UserService.java): user-role service · User and role management plus permission catalog · `src/main/java/com/tuyensinh/service/UserService.java`
- [Admissions](https://github.com/haowasabi/tuvantuyensinh/blob/main/src/main/java/com/tuyensinh/service/XetTuyenService.java): domain service · Candidate, major, score, preference, and admissions evaluation logic · `src/main/java/com/tuyensinh/service/XetTuyenService.java`
- [Import/Convert](https://github.com/haowasabi/tuvantuyensinh/blob/main/src/main/java/com/tuyensinh/service/BQDService.java): data prep service · Excel import/export and conversion-table handling · `src/main/java/com/tuyensinh/service/BQDService.java`

### Persistence

Hibernate repositories and session bootstrap

- [Hibernate](https://github.com/haowasabi/tuvantuyensinh/blob/main/src/main/java/com/tuyensinh/database/HibernateUtil.java): orm bootstrap · Configures Hibernate session factory and persistence access · `src/main/java/com/tuyensinh/database/HibernateUtil.java`
- [Repositories](https://github.com/haowasabi/tuvantuyensinh/tree/main/src/main/java/com/tuyensinh/repository): dao layer · Entity-specific Hibernate repositories · `src/main/java/com/tuyensinh/repository`

### Domain Model

Admissions entities and access-control tables

- [Admissions Models](https://github.com/haowasabi/tuvantuyensinh/tree/main/src/main/java/com/tuyensinh/model): candidate-major model · ThiSinh, Nganh, NguyenVong, DiemThi, DiemCong, TohopMonthi, BangQuyDoi, NganhToHop · `src/main/java/com/tuyensinh/model`
- [Access Models](https://github.com/haowasabi/tuvantuyensinh/tree/main/src/main/java/com/tuyensinh/model): account model · User, Role, RolePermission, and permission key structures · `src/main/java/com/tuyensinh/model`

### Data Assets

SQL, Excel, and seed inputs used by the app

- [SQL Seed](https://github.com/haowasabi/tuvantuyensinh/blob/main/src/main/java/com/tuyensinh/database/xettuyen2026.sql): schema seed · Primary database script and starter data · `src/main/java/com/tuyensinh/database/xettuyen2026.sql`
- [Excel Assets](https://github.com/haowasabi/tuvantuyensinh/tree/main/src/main/resources): import data · Reference spreadsheets used for imports and exports · `src/main/resources`
- [Seed Login](https://github.com/haowasabi/tuvantuyensinh/blob/main/src/main/java/com/tuyensinh/SeedLoginAccount.java): bootstrap utility · Creates default accounts for first-run access · `src/main/java/com/tuyensinh/SeedLoginAccount.java`

## Connections

- Main → Role Select: launches · Startup routes into role selection and login flow
- Role Select → Admin Shell: admin path · Authenticated admin users open the admin shell
- Role Select → User Shell: user path · Authenticated users open the user shell
- Admin Shell → Admin Views: hosts · Admin shell contains management panels and dialogs
- User Shell → User Views: hosts · User shell contains self-service panels
- Admin Views → Auth: checks · UI screens depend on authentication and role checks
- User Views → Auth: checks · User screens depend on login/session state
- Auth → Session: uses · Authentication updates current session state
- Auth → Accounts: delegates · Authentication and account management consult user/role services
- Accounts → Access Models: manages · User, role, and permission entities are owned here
- Admissions → Admissions Models: operates on · Admissions logic consumes candidate and major domain objects
- Import/Convert → Excel Assets: reads/writes · Bulk import and export flows use spreadsheet assets
- Admissions → Repositories: persists via · Business logic coordinates DAO operations
- Accounts → Repositories: persists via · Account and permission logic uses repositories
- Repositories → Hibernate: opens sessions · Repository implementations rely on Hibernate session setup
- Repositories → Admissions Models: maps · Entity repositories are centered on admissions tables
- Repositories → Access Models: maps · User and role repositories map access-control tables
- Seed Login → Accounts: bootstraps · Default accounts are created through account management logic
- SQL Seed → Hibernate: initializes · Database schema and seed data back the ORM runtime
- Excel Assets → Import/Convert: feeds · Reference spreadsheets support import and conversion workflows
