From cdbf09b6f56120ed9b1ae7e1a9041c0f5fe5549b Mon Sep 17 00:00:00 2001 From: waruneeauy Date: Wed, 17 Dec 2025 22:20:33 +0700 Subject: [PATCH] add docs architecture and design guide --- docs/elearning_architecture.md | 354 +++++++++++++++++++++++++++++++++ 1 file changed, 354 insertions(+) create mode 100644 docs/elearning_architecture.md diff --git a/docs/elearning_architecture.md b/docs/elearning_architecture.md new file mode 100644 index 00000000..46d0cf7d --- /dev/null +++ b/docs/elearning_architecture.md @@ -0,0 +1,354 @@ +# E-Learning System - Technical Architecture & Design Guide + +## 1. System Architecture Overview + +### Technology Stack + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Frontend Layer │ +│ Nuxt 3 + Quasar + Tailwind CSS + TypeScript │ +└─────────────────────────────────────────────────────────────┘ + ↓ HTTP/REST API +┌─────────────────────────────────────────────────────────────┐ +│ Backend Layer │ +│ Node.js + Express + Prisma │ +└─────────────────────────────────────────────────────────────┘ + ↓ SQL Queries +┌─────────────────────────────────────────────────────────────┐ +│ Database Layer │ +│ PostgreSQL 15+ │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## 2. Frontend Architecture + +### 2.1 Core Technologies + +**Nuxt 3 (Vue 3)** +- SSR/SSG capabilities for better SEO +- Auto-imports for components and composables +- File-based routing +- Built-in state management + +**Quasar Framework** +- Rich component library (250+ components) +- Responsive design out of the box +- Cross-platform support (Web, Mobile, Desktop) +- Material Design compliance + +**Tailwind CSS** +- Utility-first CSS framework +- Custom design system +- Dark mode support +- Responsive design utilities + +### 2.2 Project Structure + +``` +frontend/ +├── assets/ +│ ├── css/ +│ │ └── main.css +│ └── images/ +├── components/ +│ ├── common/ +│ │ ├── AppHeader.vue +│ │ ├── AppSidebar.vue +│ │ └── AppFooter.vue +│ ├── course/ +│ │ ├── CourseCard.vue +│ │ ├── CourseList.vue +│ │ └── CourseDetail.vue +│ ├── lesson/ +│ │ ├── LessonPlayer.vue +│ │ └── LessonProgress.vue +│ └── user/ +│ ├── UserProfile.vue +│ └── UserAvatar.vue +├── composables/ +│ ├── useAuth.ts +│ ├── useCourse.ts +│ └── useNotification.ts +├── layouts/ +│ ├── default.vue +│ ├── auth.vue +│ └── dashboard.vue +├── pages/ +│ ├── index.vue +│ ├── login.vue +│ ├── courses/ +│ │ ├── index.vue +│ │ └── [id].vue +│ ├── dashboard/ +│ │ ├── index.vue +│ │ ├── courses.vue +│ │ └── assignments.vue +│ └── admin/ +│ └── index.vue +├── plugins/ +│ ├── quasar.ts +│ └── axios.ts +├── stores/ +│ ├── auth.ts +│ ├── course.ts +│ └── user.ts +├── middleware/ +│ ├── auth.ts +│ └── role.ts +└── nuxt.config.ts +``` + +### 2.3 Key Configuration Files + +**nuxt.config.ts** +```typescript +export default defineNuxtConfig({ + modules: [ + 'nuxt-quasar-ui', + '@pinia/nuxt', + '@nuxtjs/tailwindcss' + ], + + quasar: { + plugins: ['Notify', 'Dialog', 'Loading'], + config: { + brand: { + primary: '#3B82F6', + secondary: '#10B981', + accent: '#F59E0B' + } + } + }, + + runtimeConfig: { + public: { + apiBase: process.env.API_BASE_URL || 'http://localhost:3001/api' + } + } +}) +``` + +**tailwind.config.js** +```javascript +module.exports = { + content: [ + './components/**/*.{vue,js,ts}', + './layouts/**/*.vue', + './pages/**/*.vue', + './plugins/**/*.{js,ts}' + ], + theme: { + extend: { + colors: { + primary: '#3B82F6', + secondary: '#10B981', + accent: '#F59E0B' + } + } + } +} +``` + +--- + +## 3. Backend Architecture + +### 3.1 Core Technologies + +**Node.js + Express** +- RESTful API design +- JWT authentication +- Middleware for validation +- File upload handling + +**Prisma ORM** +- Type-safe database queries +- Auto-generated migrations +- Database introspection +- Relation handling + +**PostgreSQL** +- Relational data integrity +- JSONB support for flexibility +- Full-text search +- Performance optimization + +### 3.2 Project Structure + +``` +backend/ +├── prisma/ +│ ├── schema.prisma +│ └── migrations/ +├── src/ +│ ├── config/ +│ │ ├── database.ts +│ │ └── jwt.ts +│ ├── middleware/ +│ │ ├── auth.ts +│ │ ├── validation.ts +│ │ └── errorHandler.ts +│ ├── modules/ +│ │ ├── auth/ +│ │ │ ├── auth.controller.ts +│ │ │ ├── auth.service.ts +│ │ │ └── auth.routes.ts +│ │ ├── users/ +│ │ │ ├── users.controller.ts +│ │ │ ├── users.service.ts +│ │ │ └── users.routes.ts +│ │ ├── courses/ +│ │ │ ├── courses.controller.ts +│ │ │ ├── courses.service.ts +│ │ │ └── courses.routes.ts +│ │ ├── lessons/ +│ │ ├── assignments/ +│ │ ├── quizzes/ +│ │ └── notifications/ +│ ├── utils/ +│ │ ├── logger.ts +│ │ ├── validator.ts +│ │ └── fileUpload.ts +│ ├── types/ +│ │ └── index.ts +│ ├── app.ts +│ └── server.ts +├── tests/ +├── package.json +└── tsconfig.json +``` +--- + +## 4. Design System & UI Theme + +### 4.1 Modern Design Principles + +**Design Philosophy:** +- **Clean & Minimal** - Focus on content, remove unnecessary elements +- **Modern & Professional** - Contemporary look suitable for global audience +- **Accessible** - WCAG 2.1 AA compliant +- **Consistent** - Uniform spacing, typography, and interactions +- **Responsive** - Mobile-first approach + +### 4.2 Color Palette + +**Primary Colors** +```css +--primary-50: #EFF6FF; +--primary-100: #DBEAFE; +--primary-200: #BFDBFE; +--primary-300: #93C5FD; +--primary-400: #60A5FA; +--primary-500: #3B82F6; /* Main primary */ +--primary-600: #2563EB; +--primary-700: #1D4ED8; +--primary-800: #1E40AF; +--primary-900: #1E3A8A; +``` + +**Secondary Colors** +```css +--secondary-500: #10B981; /* Success/Positive */ +--accent-500: #F59E0B; /* Warning/Attention */ +--error-500: #EF4444; /* Error/Danger */ +``` + +**Neutral Colors** +```css +--gray-50: #F9FAFB; +--gray-100: #F3F4F6; +--gray-200: #E5E7EB; +--gray-300: #D1D5DB; +--gray-400: #9CA3AF; +--gray-500: #6B7280; +--gray-600: #4B5563; +--gray-700: #374151; +--gray-800: #1F2937; +--gray-900: #111827; +``` + +**Dark Mode** +```css +--dark-bg-primary: #0F172A; +--dark-bg-secondary: #1E293B; +--dark-bg-tertiary: #334155; +--dark-text-primary: #F1F5F9; +--dark-text-secondary: #CBD5E1; +``` + +### 4.3 Typography + +**Font Family** +```css +/* Modern, clean, and widely supported */ +font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', + 'Roboto', 'Helvetica Neue', Arial, sans-serif; + +/* Thai font support */ +font-family: 'Prompt', 'Sarabun', 'Inter', sans-serif; +``` + +**Font Scale** +```css +--text-xs: 0.75rem; /* 12px */ +--text-sm: 0.875rem; /* 14px */ +--text-base: 1rem; /* 16px */ +--text-lg: 1.125rem; /* 18px */ +--text-xl: 1.25rem; /* 20px */ +--text-2xl: 1.5rem; /* 24px */ +--text-3xl: 1.875rem; /* 30px */ +--text-4xl: 2.25rem; /* 36px */ +--text-5xl: 3rem; /* 48px */ +``` + +**Font Weights** +```css +--font-normal: 400; +--font-medium: 500; +--font-semibold: 600; +--font-bold: 700; +``` + +### 4.4 Spacing System + +**8px base unit system** +```css +--space-1: 0.25rem; /* 4px */ +--space-2: 0.5rem; /* 8px */ +--space-3: 0.75rem; /* 12px */ +--space-4: 1rem; /* 16px */ +--space-5: 1.25rem; /* 20px */ +--space-6: 1.5rem; /* 24px */ +--space-8: 2rem; /* 32px */ +--space-10: 2.5rem; /* 40px */ +--space-12: 3rem; /* 48px */ +--space-16: 4rem; /* 64px */ +--space-20: 5rem; /* 80px */ +``` + +### 4.5 Border Radius + +```css +--radius-sm: 0.25rem; /* 4px */ +--radius-md: 0.5rem; /* 8px */ +--radius-lg: 0.75rem; /* 12px */ +--radius-xl: 1rem; /* 16px */ +--radius-2xl: 1.5rem; /* 24px */ +--radius-full: 9999px; /* Circle */ +``` + +### 4.6 Shadows + +```css +--shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05); +--shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1); +--shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1); +--shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.1); +--shadow-2xl: 0 25px 50px -12px rgb(0 0 0 / 0.25); +``` + +**Version:** 1.0 +**Last Updated:** December 2024 \ No newline at end of file