Sơ đồ thư mục và luồng file

Trang này dùng khi thầy hỏi “code chia thư mục thế nào”, “muốn sửa logic thì mở đâu”, hoặc “vì sao em biết request đi qua file nào”. Nếu cần tra sâu từng file, mở tiếp Vị trí file code, Source map, Symbol index và Full File CodeMap.

Ảnh cây thư mục tổng quan

Sơ đồ cây thư mục tổng quan của LMS Hàng Hải

Ảnh luồng tìm file khi cần sửa code

Sơ đồ luồng tìm file khi sửa UI, frontend logic, backend logic và database

Cây thư mục nên nhớ

LMS_hohulili/
├─ backend/
│  └─ src/main/java/com/example/lms/
│     ├─ identity/              auth, user, role, JWT
│     ├─ course_authoring/      course, chapter, lesson, publication draft
│     ├─ learning_delivery/     class, enrollment, progress, video learning
│     ├─ assessment/            quiz, assignment, question bank, grading
│     ├─ communication/         messages and notifications
│     ├─ ai_assistant/          AI chat and insights
│     ├─ competency_mapping/    STCW competency mapping
│     ├─ shared/                upload, R2, payment, email, shared services
│     └─ config/                security, CORS, JWT, rate limit
├─ fe/
│  └─ src/app/
│     ├─ api/                   typed API clients and endpoint DTOs
│     ├─ core/                  auth, guards, interceptors, global services
│     ├─ features/              admin, teacher, student, learning, payment
│     ├─ shared/                reusable UI components and helpers
│     └─ state/                 global/feature state services
├─ docs-site/
│  ├─ study/                    Just the Docs learning pages
│  ├─ assets/images/            static SVG diagrams
│  ├─ _includes/                Mermaid/search customization
│  └─ _sass/custom/             docs UI polish
├─ docs/reports/                generated long HTML reports
├─ scripts/                     codemap/schema generators
├─ docker-compose*.yml          local/prod container topology
├─ Caddyfile                    HTTPS reverse proxy
└─ deploy.sh                    production deploy script

Luồng mở file theo loại câu hỏi

Nếu bị hỏi/sửa	Mở frontend trước	Mở backend tiếp	DB/docs cần kiểm
Đổi màu/layout	`component.html`, `component.scss`, shared UI primitives, design token	Thường không cần	UX/UI, smoke desktop/mobile
Đổi điều kiện hiển thị nút	Route/component/store/guard trong `fe/src/app/features/*`	Controller/use case nếu điều kiện liên quan quyền hoặc dữ liệu thật	Test role/ownership ở backend
Đổi logic tạo/sửa course	`features/teacher/course-editor` + API client	`course_authoring/infrastructure/web` -> `application/usecase`	`courses`, `chapters`, `lessons`, `content_blocks`
Đổi upload Word/PDF/video	Upload UI/service + `server-upload-adapter`	`shared/application/usecase/PresignedUploadUseCase`, video ingest service	`upload_sessions`, `file_attachments`, `video_assets`
Đổi Shaka/ABR/ARB	`adaptive-video-player`, offline video service	Video asset/playback endpoints, `ShakaPackagerService`	`video_assets`, `video_renditions`, `video_ingest_jobs`
Đổi quiz/grading	Quiz/assignment components	`assessment` controller/use case/domain	`quizzes`, `questions`, `quiz_attempts`, `submissions`, audit
Đổi payment	Payment UI/service	`shared/payment`, VNPay/SePay controller/webhook	`payment_transactions`, enrollment side effect
Đổi Wiii safe action	Teacher/editor DOM metadata, `WiiiContextService`	Preview/apply endpoints nếu có mutate	Luôn giữ preview/diff và backend authorization
Đổi schema	Không sửa FE trước nếu API chưa có dữ liệu	Domain/use case/adapter/entity	Tạo Flyway migration, chạy schema catalog

Clean Architecture backend trong một nhịp

flowchart LR
  UI["Angular screen"]
  Client["API client"]
  Controller["REST controller"]
  UseCase["Use case"]
  Domain["Domain model"]
  Port["Repository port"]
  Adapter["Persistence adapter"]
  Jpa["JpaEntity + JpaRepository"]
  DB["PostgreSQL / Flyway"]

  UI --> Client --> Controller --> UseCase --> Domain
  UseCase --> Port --> Adapter --> Jpa --> DB

Câu chốt nên nhớ: frontend giúp UX, nhưng quyền thật và mutation nguy hiểm phải được backend kiểm ở controller/use case/domain boundary.

Vì sao có lúc thấy 108 file migration?

Trong backend/src/main/resources/db/migration, lệnh liệt kê mọi file có thể ra 108 vì thư mục có cả README.md. Con số SQL migration đúng là 107 file .sql. Schema catalog hiện sinh được 78 application tables và 2 materialized views.

rg --files backend\src\main\resources\db\migration
node scripts\generate-schema-catalog.mjs

Nên nói: “Theo Flyway hiện tại có 107 migration SQL files, sinh ra 78 application tables và 2 materialized views; số 108 là nếu tính cả README trong thư mục migration.”