aplp.frontend.web/docs/ARCHITECTURE.md

APLP Frontend — Architecture

Module	aplp.frontend.react
Status	Phase 0 hoàn tất

1. Role

Client mỏng cho aplp.web: gọi API của backend aplp.backend.spring, tập trung vào UI/UX.

Frontend không:

• Tính toán master/progress/adaptive (mọi quyết định từ backend).
• Chứa business rules.
• Lưu trữ dữ liệu business ngoài cache phục vụ UI.

2. Tech Stack (confirmed tại Phase 0)

Lĩnh vực	Lựa chọn
Framework	React 19+
Language	TypeScript
Build	Vite 8
Routing	React Router 7
HTTP client	Axios (abstraction)
Server-state	TanStack Query (React Query)
Client-state	Zustand
Styling	Tailwind CSS 4
Testing	Vitest + Testing Library

3. Folder Structure

aplp.frontend.react/
├── docs/
├── public/
└── src/
    ├── app/           # app entry, router, providers, layout
    ├── api/           # api client, endpoints
    ├── features/      # feature modules (vertical per phase)
    │   ├── auth/
    │   ├── learner/
    │   ├── course/
    │   ├── learning/
    │   ├── assessment/
    │   ├── adaptive/
    │   ├── recommendation/
    │   ├── assistance/
    │   └── account/
    ├── shared/        # shared components, hooks, utils
    └── types/         # shared types / DTO contracts

4. Feature Structure

Mỗi feature module nên tự đóng gói:

src/features/<feature>/
├── api/           # calls backend endpoints
├── components/
├── hooks/
├── pages/          # route-level views
└── types.ts        # feature-local types

5. Data Flow

UI (component)
  ↓ hooks (React Query / Zustand)
  ↓ api/ axios wrapper (auth header, refresh token, error mapping)
  ↓ Backend REST API

• Read: React Query quản lý fetch/cache/server-state.
• Write: mutation qua React Query; optimistic update nếu cần.
• Runtime UI state: local/Zustand.
• Token: access token in-memory (src/api/tokenStorage.ts), refresh token HttpOnly cookie do backend quản lý (đã confirm Phase 0).

6. Auth Flow

Login → lưu access token → attach Authorization header
Access token hết hạn → gọi /auth/refresh → retry request
Logout → xóa token → redirect

• Trung tâm qua api client, không scatter trong từng page.
• Route bảo vệ qua ProtectedRoute / auth guard.
• Chi tiết (JWT/session) theo backend (OQ-010 / ARC-002).

7. Error Handling

• Api client chuẩn hóa lỗi (ApiError từ backend) → user-friendly message.
• Error boundary cho crash cấp tree.
• Loading/empty/error states component tái sử dụng.

8. Styling & Design

• Theme tokens dùng chung (colors, spacing, typography).
• Component pattern thống nhất (candidate: component library quyết định Phase 0).

9. Deployment

• Build tĩnh (Vite output) serve qua CDN/nginx hoặc tách container.
• Env qua VITE_* variables; không commit secret vào build config.

10. Guardrails

• Không tính toán domain phía client (adaptive, mastery, progress).
• Không bypass auth guard.
• Không gọi backend API trực tiếp ngoài src/api (except khi có lý do rõ).
• Loại bỏ dead code, không dùng type any tùy tiện (TypeScript).
• Dùng semantic versions; document trong repo.

11. Open Questions

ID	Question	Impact	Status
FE-001	Vite hay framework khác?	Setup	Resolved: Vite
FE-002	TypeScript bắt buộc?	Quality	Resolved: có
FE-003	Component library?	UX	Resolved: Tailwind CSS
FE-004	Client-state tool?	Data flow	Resolved: Zustand
FE-005	SSR/SSG?	SEO	Resolved: không
FE-008	Cách quản lý token (memory/localStorage/refresh)?	Security	Resolved: access token in-memory + refresh token HttpOnly cookie (backend)
FE-009	Có cần end-to-end test (Playwright)?	Testing	Open