# minhhjj5678/do-an-quan-ly-ktx architecture

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

- Interactive diagram: https://gitdiagram.com/minhhjj5678/do-an-quan-ly-ktx
- Repository: https://github.com/minhhjj5678/do-an-quan-ly-ktx

## Overview

Quản Lý Ký Túc Xá is a desktop dormitory-management application. The principal workflow is user interaction through Tkinter screens, routed via the UI adapter and business protocols to domain coordination, which validates and changes dormitory records and persists them as JSON. Major capabilities include authentication, catalog management, contract and invoice payments, violations, reporting, settings, and geographic address selection. The README documents the layer boundaries and capabilities; source excerpts confirm startup loading, coordinator behavior, entities, and JSON safety. Many screen-to-operation and coordinator-to-store calls were not sampled, so those links are omitted or marked unverified.

Main entry points: [`giao_dien/app.py`](https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/giao_dien/app.py) (Management screens), [`thuc_the/thuc_the_goc.py`](https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/thuc_the/thuc_the_goc.py) (Entity foundations), [`nghiep_vu/kiem_cheo_du_lieu.py`](https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/nghiep_vu/kiem_cheo_du_lieu.py) (Cross-entity validation), [`nghiep_vu/dieu_phoi.py`](https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/nghiep_vu/dieu_phoi.py) (Business coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Desktop interface"]
  node_startup["Application startup<br/>[main.py]"]
  node_screens["Management screens<br/>[app.py]"]
  node_catalog["Catalog forms"]
  node_authui["Login and account UI"]
  node_reports["Statistics UI<br/>[thong_ke.py]"]
  node_adapter["UI adapter<br/>[adapter.py]"]
end

subgraph group_business["Business services"]
  node_protocol["Business protocols<br/>[nghiep_vu.py]"]
  node_session["Account sessions<br/>[phien_lam_viec.py]"]
  node_coordinator["Business coordinator<br/>[dieu_phoi.py]"]
  node_crosscheck["Cross-entity validation"]
end

subgraph group_domain["Domain model"]
  node_residents["Resident and room entities<br/>[ky_tuc_xa.py]"]
  node_finance["Contracts and invoices<br/>[tai_chinh.py]"]
  node_accounts["Account entities<br/>[tai_khoan.py]"]
  node_violations["Violation entities<br/>[vi_pham.py]"]
  node_geography["Geographic entities<br/>[dia_ly.py]"]
  node_entitybase["Entity foundations<br/>[thuc_the_goc.py]"]
end

subgraph group_storage["Persistence and utilities"]
  node_jsonstore["Safe JSON storage<br/>[luu_tru_json.py]"]
  node_typedstores[("Entity stores")]
  node_config["Runtime configuration<br/>[cau_hinh_dong.py]"]
  node_validation["Input validation<br/>[regex.py]"]
  node_passwords["Password hashing<br/>[bam_mat_khau.py]"]
  node_filepaths["Data file paths<br/>[tap_tin.py]"]
end

node_user(("Staff or resident"))

node_user -->|"uses"| node_screens
node_startup -->|"starts"| node_screens
node_startup -->|"creates"| node_coordinator
node_startup -->|"creates"| node_session
node_startup -->|"registers"| node_typedstores
node_screens -->|"uses"| node_adapter
node_screens -->|"opens"| node_catalog
node_screens -->|"opens"| node_authui
node_screens -->|"opens"| node_reports
node_adapter -.->|"adapts"| node_protocol
node_protocol -->|"implemented by"| node_coordinator
node_protocol -->|"session contract"| node_session
node_coordinator -->|"validates"| node_crosscheck
node_coordinator -->|"reads and writes"| node_typedstores
node_coordinator -->|"loads settings"| node_config
node_session -->|"authenticates"| node_accounts
node_session -->|"checks passwords"| node_passwords
node_typedstores -->|"specializes"| node_jsonstore
node_jsonstore -->|"resolves paths"| node_filepaths
node_typedstores -->|"serializes"| node_entitybase
node_residents -->|"inherits"| node_entitybase
node_finance -->|"inherits"| node_entitybase
node_accounts -->|"inherits"| node_entitybase
node_violations -->|"inherits"| node_entitybase
node_crosscheck -->|"checks relations"| node_residents
node_crosscheck -->|"checks relations"| node_finance
node_crosscheck -->|"checks relations"| node_accounts
node_crosscheck -->|"checks relations"| node_violations
node_entitybase -->|"uses"| node_validation
node_accounts -->|"verifies"| node_passwords
node_screens -.->|"loads startup data"| node_typedstores

click node_startup "https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/main.py"
click node_screens "https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/giao_dien/app.py"
click node_catalog "https://github.com/minhhjj5678/do-an-quan-ly-ktx/tree/main/giao_dien/danh_muc"
click node_authui "https://github.com/minhhjj5678/do-an-quan-ly-ktx/tree/main/giao_dien/xac_thuc"
click node_reports "https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/giao_dien/thong_ke/thong_ke.py"
click node_adapter "https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/giao_dien/dung_chung/adapter.py"
click node_protocol "https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/giao_thuc/nghiep_vu.py"
click node_session "https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/nghiep_vu/phien_lam_viec.py"
click node_coordinator "https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/nghiep_vu/dieu_phoi.py"
click node_crosscheck "https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/nghiep_vu/kiem_cheo_du_lieu.py"
click node_residents "https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/thuc_the/ky_tuc_xa.py"
click node_finance "https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/thuc_the/tai_chinh.py"
click node_accounts "https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/thuc_the/tai_khoan.py"
click node_violations "https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/thuc_the/vi_pham.py"
click node_geography "https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/thuc_the/dia_ly.py"
click node_entitybase "https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/thuc_the/thuc_the_goc.py"
click node_jsonstore "https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/luu_tru/luu_tru_json.py"
click node_typedstores "https://github.com/minhhjj5678/do-an-quan-ly-ktx/tree/main/luu_tru"
click node_config "https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/tien_ich/cau_hinh_dong.py"
click node_validation "https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/tien_ich/regex.py"
click node_passwords "https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/tien_ich/bam_mat_khau.py"
click node_filepaths "https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/tien_ich/tap_tin.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_startup,node_screens,node_catalog,node_authui,node_reports,node_adapter toneBlue
class node_protocol,node_session,node_coordinator,node_crosscheck toneAmber
class node_residents,node_finance,node_accounts,node_violations,node_geography,node_entitybase toneMint
class node_jsonstore,node_typedstores,node_config,node_validation,node_passwords,node_filepaths toneRose
class node_user toneIndigo
```

## Components

### Desktop interface

- [Application startup](https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/main.py): `main.py`
- [Management screens](https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/giao_dien/app.py): `giao_dien/app.py`
- [Catalog forms](https://github.com/minhhjj5678/do-an-quan-ly-ktx/tree/main/giao_dien/danh_muc): `giao_dien/danh_muc`
- [Login and account UI](https://github.com/minhhjj5678/do-an-quan-ly-ktx/tree/main/giao_dien/xac_thuc): `giao_dien/xac_thuc`
- [Statistics UI](https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/giao_dien/thong_ke/thong_ke.py): `giao_dien/thong_ke/thong_ke.py`
- [UI adapter](https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/giao_dien/dung_chung/adapter.py): `giao_dien/dung_chung/adapter.py`

### Business services

- [Business protocols](https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/giao_thuc/nghiep_vu.py): `giao_thuc/nghiep_vu.py`
- [Account sessions](https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/nghiep_vu/phien_lam_viec.py): `nghiep_vu/phien_lam_viec.py`
- [Business coordinator](https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/nghiep_vu/dieu_phoi.py): `nghiep_vu/dieu_phoi.py`
- [Cross-entity validation](https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/nghiep_vu/kiem_cheo_du_lieu.py): `nghiep_vu/kiem_cheo_du_lieu.py`

### Domain model

- [Resident and room entities](https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/thuc_the/ky_tuc_xa.py): `thuc_the/ky_tuc_xa.py`
- [Contracts and invoices](https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/thuc_the/tai_chinh.py): `thuc_the/tai_chinh.py`
- [Account entities](https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/thuc_the/tai_khoan.py): `thuc_the/tai_khoan.py`
- [Violation entities](https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/thuc_the/vi_pham.py): `thuc_the/vi_pham.py`
- [Geographic entities](https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/thuc_the/dia_ly.py): `thuc_the/dia_ly.py`
- [Entity foundations](https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/thuc_the/thuc_the_goc.py): `thuc_the/thuc_the_goc.py`

### Persistence and utilities

- [Safe JSON storage](https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/luu_tru/luu_tru_json.py): `luu_tru/luu_tru_json.py`
- [Entity stores](https://github.com/minhhjj5678/do-an-quan-ly-ktx/tree/main/luu_tru): `luu_tru`
- [Runtime configuration](https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/tien_ich/cau_hinh_dong.py): `tien_ich/cau_hinh_dong.py`
- [Input validation](https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/tien_ich/regex.py): `tien_ich/regex.py`
- [Password hashing](https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/tien_ich/bam_mat_khau.py): `tien_ich/bam_mat_khau.py`
- [Data file paths](https://github.com/minhhjj5678/do-an-quan-ly-ktx/blob/main/tien_ich/tap_tin.py): `tien_ich/tap_tin.py`

### Other components

- **Staff or resident**

## Connections

- Staff or resident → Management screens: uses (evidence: `README.md`)
- Application startup → Management screens: starts (evidence: `main.py`)
- Application startup → Business coordinator: creates (evidence: `main.py`)
- Application startup → Account sessions: creates (evidence: `main.py`)
- Application startup → Entity stores: registers (evidence: `main.py`)
- Management screens → UI adapter: uses (evidence: `giao_dien/app.py`)
- Management screens → Catalog forms: opens (evidence: `giao_dien/app.py`)
- Management screens → Login and account UI: opens (evidence: `giao_dien/app.py`)
- Management screens → Statistics UI: opens (evidence: `giao_dien/app.py`)
- UI adapter → Business protocols: adapts (evidence: `giao_dien/dung_chung/adapter.py`)
- Business protocols → Business coordinator: implemented by (evidence: `README.md`)
- Business protocols → Account sessions: session contract (evidence: `README.md`)
- Business coordinator → Cross-entity validation: validates (evidence: `nghiep_vu/dieu_phoi.py`)
- Business coordinator → Entity stores: reads and writes (evidence: `README.md`)
- Business coordinator → Runtime configuration: loads settings (evidence: `nghiep_vu/dieu_phoi.py`)
- Account sessions → Account entities: authenticates (evidence: `nghiep_vu/phien_lam_viec.py`)
- Account sessions → Password hashing: checks passwords (evidence: `nghiep_vu/phien_lam_viec.py`)
- Entity stores → Safe JSON storage: specializes (evidence: `luu_tru/luu_tru_json.py`)
- Safe JSON storage → Data file paths: resolves paths (evidence: `luu_tru/luu_tru_json.py`)
- Entity stores → Entity foundations: serializes (evidence: `luu_tru/luu_tru_json.py`)
- Resident and room entities → Entity foundations: inherits (evidence: `thuc_the/ky_tuc_xa.py`)
- Contracts and invoices → Entity foundations: inherits (evidence: `thuc_the/tai_chinh.py`)
- Account entities → Entity foundations: inherits (evidence: `thuc_the/tai_khoan.py`)
- Violation entities → Entity foundations: inherits (evidence: `thuc_the/vi_pham.py`)
- Cross-entity validation → Resident and room entities: checks relations (evidence: `nghiep_vu/kiem_cheo_du_lieu.py`)
- Cross-entity validation → Contracts and invoices: checks relations (evidence: `nghiep_vu/kiem_cheo_du_lieu.py`)
- Cross-entity validation → Account entities: checks relations (evidence: `nghiep_vu/kiem_cheo_du_lieu.py`)
- Cross-entity validation → Violation entities: checks relations (evidence: `nghiep_vu/kiem_cheo_du_lieu.py`)
- Entity foundations → Input validation: uses (evidence: `thuc_the/thuc_the_goc.py`)
- Account entities → Password hashing: verifies (evidence: `thuc_the/tai_khoan.py`)
- Management screens → Entity stores: loads startup data
