# 🏗️ Architecture & System Design

## System Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                     BROWSER / CLIENT                          │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                    React App (Vite)                  │   │
│  │                                                       │   │
│  │  ┌──────────────────────────────────────────────┐   │   │
│  │  │          Providers (Context)                 │   │   │
│  │  │  ┌──────────────────────────────────────┐   │   │   │
│  │  │  │ AuthProvider (User, Token, Auth)     │   │   │   │
│  │  │  │ ThemeProvider (Dark Mode)            │   │   │   │
│  │  │  └──────────────────────────────────────┘   │   │   │
│  │  └──────────────────────────────────────────────┘   │   │
│  │                                                       │   │
│  │  ┌──────────────────────────────────────────────┐   │   │
│  │  │        React Router (Routes)                 │   │   │
│  │  │  ├─ /login (Public)                         │   │   │
│  │  │  ├─ /register (Public)                      │   │   │
│  │  │  ├─ /dashboard (Protected)                  │   │   │
│  │  │  └─ /users (Protected)                      │   │   │
│  │  └──────────────────────────────────────────────┘   │   │
│  │                                                       │   │
│  │  ┌──────────────────────────────────────────────┐   │   │
│  │  │           Page Components                    │   │   │
│  │  │  ├─ Login.jsx (Form)                        │   │   │
│  │  │  ├─ Register.jsx (Form)                     │   │   │
│  │  │  ├─ Dashboard.jsx (Stats)                   │   │   │
│  │  │  ├─ Users.jsx (Table + CRUD)                │   │   │
│  │  │  └─ DashboardLayout.jsx (Sidebar + Nav)     │   │   │
│  │  └──────────────────────────────────────────────┘   │   │
│  │                                                       │   │
│  │  ┌──────────────────────────────────────────────┐   │   │
│  │  │        Component Library (14 Components)     │   │   │
│  │  │  ├─ Button, Card, Modal, Input              │   │   │
│  │  │  ├─ Badge, Loader, Table, Pagination       │   │   │
│  │  │  ├─ ConfirmDialog, Sidebar, Navbar         │   │   │
│  │  │  └─ ProtectedRoute, User Modals             │   │   │
│  │  └──────────────────────────────────────────────┘   │   │
│  │                                                       │   │
│  │  ┌──────────────────────────────────────────────┐   │   │
│  │  │           State Management                   │   │   │
│  │  │  ├─ AuthContext (User, Token, Auth)         │   │   │
│  │  │  ├─ ThemeContext (Dark Mode)                │   │   │
│  │  │  └─ localStorage (Persistence)               │   │   │
│  │  └──────────────────────────────────────────────┘   │   │
│  │                                                       │   │
│  │  ┌──────────────────────────────────────────────┐   │   │
│  │  │      API Layer & HTTP Client                 │   │   │
│  │  │  ┌────────────────────────────────────────┐  │   │   │
│  │  │  │ Axios Instance (axiosConfig.js)       │  │   │   │
│  │  │  │ ├─ Request Interceptor (Add Token)    │  │   │   │
│  │  │  │ └─ Response Interceptor (401 Refresh) │  │   │   │
│  │  │  └────────────────────────────────────────┘  │   │   │
│  │  │  ┌────────────────────────────────────────┐  │   │   │
│  │  │  │ API Endpoints (endpoints.js)          │  │   │   │
│  │  │  │ ├─ authAPI (login, register, etc.)   │  │   │   │
│  │  │  │ └─ usersAPI (CRUD operations)        │  │   │   │
│  │  │  └────────────────────────────────────────┘  │   │   │
│  │  └──────────────────────────────────────────────┘   │   │
│  │                                                       │   │
│  │  ┌──────────────────────────────────────────────┐   │   │
│  │  │         UI/UX & Utilities                    │   │   │
│  │  │  ├─ Tailwind CSS (Styling)                  │   │   │
│  │  │  ├─ Toast Notifications (Sonner)            │   │   │
│  │  │  ├─ React Icons (Icon Library)              │   │   │
│  │  │  ├─ Helper Functions (debounce, throttle)  │   │   │
│  │  │  └─ Custom Hooks (useAuth, useTheme)       │   │   │
│  │  └──────────────────────────────────────────────┘   │   │
│  │                                                       │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                               │
└─────────────────────────────────────────────────────────────┘
                              ↓
                        localStorage
                    (Token, User, Theme)
                              ↓
            ┌─────────────────────────────────┐
            │      HTTP/HTTPS (Axios)          │
            │  With Bearer Token & Refresh     │
            └─────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                    BACKEND API SERVER                         │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  Authentication Endpoints                                    │
│  ├─ POST /auth/login                                        │
│  ├─ POST /auth/register                                     │
│  ├─ POST /auth/refresh                                      │
│  └─ POST /auth/logout                                       │
│                                                               │
│  User Management Endpoints                                   │
│  ├─ GET /users (Paginated)                                  │
│  ├─ POST /users (Create)                                    │
│  ├─ PUT /users/:id (Update)                                 │
│  ├─ PATCH /users/:id/soft-delete (Soft Delete)             │
│  └─ DELETE /users/:id (Permanent Delete)                    │
│                                                               │
│                    Database                                  │
│  ├─ Users Table                                             │
│  └─ Sessions/Tokens                                         │
│                                                               │
└─────────────────────────────────────────────────────────────┘
```

---

## Component Hierarchy

```
App
├── AuthProvider
│   └── ThemeProvider
│       ├── ToastContainer
│       └── Router
│           ├── Route: /login
│           │   └── Login (Form)
│           │
│           ├── Route: /register
│           │   └── Register (Form)
│           │
│           └── ProtectedRoute
│               ├── DashboardLayout
│               │   ├── Sidebar
│               │   │   ├── Menu Items (Links)
│               │   │   ├── Theme Toggle (useTheme)
│               │   │   └── Logout (useAuth)
│               │   │
│               │   └── Main Content
│               │       ├── /dashboard
│               │       │   ├── Navbar
│               │       │   ├── Card (Stats 1-4)
│               │       │   └── Card (Recent Activity)
│               │       │
│               │       └── /users
│               │           ├── Navbar
│               │           ├── Card (Search/Filter)
│               │           ├── Card (Table)
│               │           │   └── Table Component
│               │           │       ├── Row Actions
│               │           │       │   ├── Edit Button
│               │           │       │   └── Delete Button
│               │           │       └── Status Badges
│               │           ├── Pagination
│               │           ├── AddUserModal
│               │           │   └── Form (Input × 4, Selects × 2)
│               │           ├── EditUserModal
│               │           │   └── Form (Input × 2, Selects × 2)
│               │           └── ConfirmDialog
│               │               └── Delete Confirmation
```

---

## Data Flow Diagram

### Authentication Flow
```
┌────────────┐
│   Login    │
│   Page     │
└─────┬──────┘
      │ 1. User enters email/password
      │ 2. Click "Sign In"
      ↓
┌────────────────────────┐
│ Login.jsx Component    │
│ - Form Validation      │
└────────┬───────────────┘
         │
         │ 3. Call authAPI.login()
         ↓
┌────────────────────────┐
│ Axios Request          │
│ POST /auth/login       │
│ Header: Content-Type   │
└────────┬───────────────┘
         │
         │ 4. HTTP Request
         ↓
┌────────────────────────┐
│ Backend API            │
│ Validates credentials  │
└────────┬───────────────┘
         │
         │ 5. Response with tokens & user
         ↓
┌────────────────────────┐
│ Response Interceptor   │
│ - Extract tokens       │
└────────┬───────────────┘
         │
         │ 6. Call login() from AuthContext
         ↓
┌────────────────────────┐
│ AuthContext.login()    │
│ - Store in Context     │
│ - Save to localStorage │
└────────┬───────────────┘
         │
         │ 7. Redirect to /dashboard
         ↓
┌────────────────────────┐
│ Dashboard              │
│ Authenticated ✓        │
└────────────────────────┘
```

### API Request Flow with Token
```
┌──────────────────┐
│ Component Action │
│ (Click/Submit)   │
└────────┬─────────┘
         │
         │ 1. Call API (usersAPI.getUsers)
         ↓
┌──────────────────────────┐
│ Axios Instance           │
│ api.get('/users')        │
└────────┬─────────────────┘
         │
         │ 2. Request Interceptor
         │    - Get token from localStorage
         │    - Add: Authorization: Bearer {token}
         ↓
┌──────────────────────────┐
│ HTTP Request             │
│ GET /users               │
│ Header: Bearer token     │
└────────┬─────────────────┘
         │
         │ 3. Send to Backend
         ↓
┌──────────────────────────┐
│ Backend API              │
│ - Verify token           │
│ - Process request        │
└────────┬─────────────────┘
         │
         │ 4. Response
         ↓
┌──────────────────────────┐
│ Response Interceptor     │
│ - Check status (200/401) │
└────────┬─────────────────┘
         │
    ┌────┴─────┬────────────┐
    │           │            │
    ↓           ↓            ↓
 200 ✓      401 Unauth   Other Errors
    │           │            │
    │           │ 5. Token Refresh
    │           │ - Call /auth/refresh
    │           │ - Get new token
    │           │ - Retry request
    │           │
    ↓           ↓            ↓
┌────────────────────────────────────┐
│ Component Receives Response        │
│ - Update state                     │
│ - Show toast notification          │
│ - Render updated UI                │
└────────────────────────────────────┘
```

### Token Refresh Flow
```
API Request
    │
    ↓
401 Unauthorized Response
    │
    ├─→ Already Refreshing?
    │   ├─ YES: Queue request, wait
    │   └─ NO: Proceed to refresh
    │
    ↓
POST /auth/refresh
{refreshToken: "..."}
    │
    ├─→ Success (200)
    │   ├─ Store new accessToken
    │   ├─ Process queued requests
    │   └─ Retry original request
    │
    └─→ Failed (401/403)
        ├─ Clear all tokens
        ├─ Process queue with error
        ├─ Redirect to /login
        └─ Show error toast
```

---

## State Management Structure

```
┌─────────────────────────────────────────┐
│         AuthContext                      │
├─────────────────────────────────────────┤
│ State:                                   │
│ - user: {id, name, email, role, status} │
│ - isAuthenticated: boolean               │
│ - loading: boolean                       │
│                                          │
│ Methods:                                 │
│ - login(userData, token, refreshToken)  │
│ - logout()                               │
│                                          │
│ Storage:                                 │
│ - localStorage.accessToken              │
│ - localStorage.refreshToken             │
│ - localStorage.user                     │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│         ThemeContext                     │
├─────────────────────────────────────────┤
│ State:                                   │
│ - isDark: boolean                        │
│                                          │
│ Methods:                                 │
│ - toggleTheme()                          │
│                                          │
│ Storage:                                 │
│ - localStorage.theme-mode                │
│ - html.classList (dark class)            │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│       Component Local State              │
├─────────────────────────────────────────┤
│ - users: User[]                          │
│ - currentPage: number                    │
│ - search: string                         │
│ - isModalOpen: boolean                   │
│ - isLoading: boolean                     │
│ - formData: {...}                        │
│ - errors: {...}                          │
└─────────────────────────────────────────┘
```

---

## Database Schema (Expected)

```
Users Table
├─ id (UUID/Integer, Primary Key)
├─ name (String, Required)
├─ email (String, Required, Unique)
├─ passwordHash (String, Required)
├─ role (Enum: 'user', 'admin', 'superadmin')
├─ status (Enum: 'active', 'inactive')
├─ isDeleted (Boolean, Default: false)
├─ createdAt (Timestamp)
├─ updatedAt (Timestamp)
└─ lastLogin (Timestamp, Nullable)

Sessions/Tokens Table
├─ id (UUID/Integer, Primary Key)
├─ userId (Foreign Key → Users.id)
├─ refreshToken (String, Unique)
├─ expiresAt (Timestamp)
├─ createdAt (Timestamp)
└─ revokedAt (Timestamp, Nullable)
```

---

## API Request/Response Sequence

```
[Client]                          [Server]

  │                                  │
  ├─ POST /auth/login ──────────────→ │
  │ {email, password}                 │
  │                                   ├─ Validate email/password
  │                                   ├─ Generate tokens
  │                                   ├─ Save refresh token
  │ ←─────────────── {user, tokens} ─┤
  │                                   │
  ├─ Store tokens & user             │
  │ in localStorage                   │
  │                                   │
  ├─ GET /users ─────────────────────→ │
  │ Header: Authorization Bearer... │ │
  │                                   ├─ Verify token
  │                                   ├─ Query database
  │ ←────────── {users, pagination} ─┤
  │                                   │
  ├─ POST /users ────────────────────→ │
  │ {name, email, password, ...}     │ │
  │ Header: Bearer token             │ │
  │                                   ├─ Validate input
  │                                   ├─ Check duplicate email
  │                                   ├─ Hash password
  │                                   ├─ Save to database
  │ ←──────────────── {id, user} ───┤
  │                                   │
  ├─ PUT /users/1 ───────────────────→ │
  │ {name, role, status}             │ │
  │ Header: Bearer token             │ │
  │                                   ├─ Verify token & authorization
  │                                   ├─ Update database
  │ ←────────────────── {success} ───┤
  │                                   │
  ├─ PATCH /users/1/soft-delete ────→ │
  │ Header: Bearer token             │ │
  │ (Only superadmin)                │ │
  │                                   ├─ Check role (403 if not superadmin)
  │                                   ├─ Mark isDeleted = true
  │ ←────────────────── {success} ───┤
  │                                   │
  ├─ GET /users (expired token) ─────→ │
  │ Header: Authorization Bearer... │ │
  │                                   ├─ Check token expiry
  │ ←───────────────────── 401 ──────┤
  │                                   │
  ├─ POST /auth/refresh ─────────────→ │
  │ {refreshToken}                    │ │
  │                                   ├─ Verify refresh token
  │                                   ├─ Generate new access token
  │ ←─ {accessToken, refreshToken} ─┤
  │                                   │
  ├─ Update tokens in localStorage   │
  │                                   │
  ├─ Retry GET /users ───────────────→ │
  │ Header: Authorization Bearer... │ │
  │ (new token)                       │ │
  │                                   ├─ Verify token
  │                                   ├─ Process request
  │ ←────────────── {users, pagination}
  │                                   │
```

---

## Error Handling Flow

```
User Action
    │
    ↓
Try API Request
    │
    ├─ Success (2xx)
    │   └─ Toast.success("Operation successful")
    │
    ├─ Client Error (4xx)
    │   ├─ 401: Token expired/invalid
    │   │   └─ Auto-refresh token
    │   ├─ 403: Permission denied
    │   │   └─ Toast.error("You don't have permission")
    │   ├─ 404: Not found
    │   │   └─ Toast.error("Resource not found")
    │   └─ 400: Bad request
    │       └─ Toast.error(error.message)
    │
    ├─ Server Error (5xx)
    │   └─ Toast.error("Server error. Try again later")
    │
    └─ Network Error
        └─ Toast.error("Connection error")
```

---

## Security Architecture

```
┌──────────────────────────────────────────────┐
│           Security Layers                     │
├──────────────────────────────────────────────┤
│                                               │
│ 1. Transport Layer (HTTPS)                   │
│    └─ Encrypted in transit                   │
│                                               │
│ 2. Authentication Layer                      │
│    ├─ JWT tokens (exp, iat claims)           │
│    ├─ Refresh token rotation                 │
│    └─ Bearer token in headers                │
│                                               │
│ 3. Authorization Layer                       │
│    ├─ Role-based access (RBAC)               │
│    ├─ Superadmin-only actions                │
│    └─ Route protection                       │
│                                               │
│ 4. Data Protection                           │
│    ├─ Password hashing (backend)             │
│    ├─ Input validation (frontend)            │
│    └─ XSS protection (React escaping)        │
│                                               │
│ 5. Session Management                        │
│    ├─ Token expiry handling                  │
│    ├─ Auto logout on 401                     │
│    └─ Secure storage (localStorage)          │
│                                               │
└──────────────────────────────────────────────┘
```

---

## Performance Optimization

```
┌──────────────────────────────────────────────┐
│        Optimization Strategies                │
├──────────────────────────────────────────────┤
│                                               │
│ 1. Debouncing                                │
│    └─ Search input: 500ms delay              │
│                                               │
│ 2. Code Splitting                            │
│    └─ Route-based splitting (ready)          │
│                                               │
│ 3. Caching                                   │
│    ├─ Token caching in memory                │
│    └─ User data persistence                  │
│                                               │
│ 4. Component Optimization                    │
│    ├─ Memoization (ready)                    │
│    └─ Event delegation                       │
│                                               │
│ 5. CSS Optimization                          │
│    ├─ Tailwind CSS purging                   │
│    └─ Minimal CSS output                     │
│                                               │
│ 6. API Optimization                          │
│    ├─ Pagination (10 per page)               │
│    └─ Request queuing (interceptors)         │
│                                               │
└──────────────────────────────────────────────┘
```

---

**Architecture designed for scalability, security, and user experience.** ✨

---

**System Design Complete!** 🏗️
