feat: add guide

docs/ARCHITECTURE.md

@@ -0,0 +1,127 @@
+# 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
+
+```text
+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:
+
+```text
+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 |