How haowasabi/tuvantuyensinh works
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: repository Repositories · AuthService.java Auth · UserService.java Accounts · RoleSelectionFrame.java Role Select
Components 18
Presentation
Swing desktop UI, screen navigation, and dialogs
- Main · Application bootstrap and startup flow
src/main/java/com/tuyensinh/Main.java - Role Select · Chooses admin or user entry after login
src/main/java/com/tuyensinh/view/RoleSelectionFrame.java - Admin Shell · Admin desktop frame and navigation chrome
src/main/java/com/tuyensinh/view/AdminMainFrame.java - User Shell · User desktop frame and navigation chrome
src/main/java/com/tuyensinh/view/UserMainFrame.java - Admin Views · Management screens for candidates, majors, scores, roles, users, and reports
src/main/java/com/tuyensinh/view - User Views · Personal info, application, and result screens
src/main/java/com/tuyensinh/view
Service Layer
Authentication, admissions logic, and orchestration
- Auth · Login, session, and permission checks
src/main/java/com/tuyensinh/service/AuthService.java - Session · Tracks current authenticated user and role
src/main/java/com/tuyensinh/service/SessionManager.java - Accounts · User and role management plus permission catalog
src/main/java/com/tuyensinh/service/UserService.java - Admissions · Candidate, major, score, preference, and admissions evaluation logic
src/main/java/com/tuyensinh/service/XetTuyenService.java - Import/Convert · Excel import/export and conversion-table handling
src/main/java/com/tuyensinh/service/BQDService.java
Persistence
Hibernate repositories and session bootstrap
- Hibernate · Configures Hibernate session factory and persistence access
src/main/java/com/tuyensinh/database/HibernateUtil.java - Repositories · Entity-specific Hibernate repositories
src/main/java/com/tuyensinh/repository
Domain Model
Admissions entities and access-control tables
- Admissions Models · ThiSinh, Nganh, NguyenVong, DiemThi, DiemCong, TohopMonthi, BangQuyDoi, NganhToHop
src/main/java/com/tuyensinh/model - Access Models · 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 · Primary database script and starter data
src/main/java/com/tuyensinh/database/xettuyen2026.sql - Excel Assets · Reference spreadsheets used for imports and exports
src/main/resources - Seed Login · Creates default accounts for first-run access
src/main/java/com/tuyensinh/SeedLoginAccount.java
Connections 20
- 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