aplp.backend.web/docs/MODULES.md

# APLP Backend — Modules

| | |
| --- | --- |
| **Status** | Draft (Candidate) |

Danh sách business module của backend `aplp.backend.spring`, ánh xạ từ từng phase trong `APLP-Project-Phases.md`.

| Module | Phase | Type | Mô tả |
| --- | --- | --- | --- |
| `identity` | 0 ✅ | Generic | AuthN, user credential, session/token, identity provider hook. Nếu dùng IdP: không quản lý password khi không cần. |
| `learner` | 1 | Supporting (cân nhắc Core) | Learner profile, learning preferences, learning goals, mapping với identity. |
| `content` | 2 | Supporting | Content read model (course/module/lesson/activity từ LMS), catalog, enrollment/selection, publication status. |
| `learning` | 3 | Core | Learning experience: start/resume/continue, lesson completion, navigation, activity records, progress. |
| `assessment` | 4 | Supporting | Question, attempt, answer, evaluation, scoring, assessment result. |
| `progress` | 4 | Supporting | Learning progress computation & history (tách khỏi assessment để không lẫn). |
| `adaptive` | 5 | **Core** | Learner state, knowledge/skill state, mastery, prerequisite, adaptation decision, next activity. |
| `recommendation` | 6 | Core (defer) | Recommendation generation, personalized path. `Proposed`: có thể là decision/result. |
| `assistance` | 7 | Supporting | Hint, explanation, Q&A, feedback (AI integration) — phải qua domain validation. |
| `subscription` | 8 | Supporting | Plan, entitlement, usage limit, notification, account. Deferred tới productization. |
| `notification` | 8 | Generic | Notification delivery. |
| `common` | 0 ✅ | Infrastructure | Shared code: error handling, security config, base patterns, DTO conventions. |

> Lưu ý: `common` chỉ chứa infrastructure/shared plumbing, **không** chứa business logic của module khác.

## Phân loại bounded context

| Type | Modules |
| --- | --- |
| Core Domain | `learning`, `adaptive`, `recommendation` (recommendation defer) |
| Supporting Domain | `learner`, `content`, `assessment`, `progress`, `assistance`, `subscription` |
| Generic Domain | `identity`, `notification`, `configuration`/`common` |

## Cấu trúc thư mục gợi ý

```text
src/main/java/com/aplp/backend/
├── common/                    # infrastructure & shared
├── identity/
│   ├── api/
│   ├── application/
│   ├── domain/
│   └── persistence/
├── learner/
├── content/
├── learning/
├── assessment/
├── progress/
├── adaptive/
├── recommendation/
├── assistance/
└── subscription/
```

## Quy tắc module

1. Module A **chỉ** giao tiếp với module B qua public interface/API của B.
2. Không share DB table trực tiếp giữa module; dùng repository/read model.
3. Cross-module side-effect dùng domain event/callback nếu cần rõ ràng, không hard-code import.
4. Mỗi module phải đứng độc lập được về compile (dependency hướng trong ra ngoài).

## Khởi tạo theo phase

- **Phase 0 (done)**: `common`, `identity` (minimal), `learner` (basic profile).
- **Phase 2**: `content`.
- **Phase 3**: `learning`.
- **Phase 4**: `assessment`, `progress`.
- **Phase 5**: `adaptive`.
- **Phase 6**: `recommendation`.
- **Phase 7**: `assistance`.
- **Phase 8**: `subscription`, `notification`.

> Ghi chú Phase 0: `learner` chỉ có basic profile (display name + mapping user identity). Preferences/goals thuộc Phase 1.

## Open Questions

| ID | Question | Impact | Status |
| --- | --- | --- | --- |
| MOD-001 | `progress` tách riêng hay gộp vào `learning`? | Module boundary | Open |
| MOD-002 | `assessment` module độc lập hay trong `learning`? | Cohesion | Open |
| MOD-003 | Cách chia sẻ content model giữa `content` và `learning` (snapshot vs reference)? | Consistency | Open |
| MOD-004 | `recommendation` có cần là module riêng hay chỉ service trong `adaptive`? | Boundary | Open |