diff --git a/.cursor/plans/ui_design_modern_ai_chat.plan.md b/.cursor/plans/ui_design_modern_ai_chat.plan.md
new file mode 100644
index 00000000..1a10759f
--- /dev/null
+++ b/.cursor/plans/ui_design_modern_ai_chat.plan.md
@@ -0,0 +1,2285 @@
+# Plan: Modern AI Chat UI Design
+
+## Tổng quan kiến trúc UI
+
+Dự án sẽ có 2 ứng dụng web chính với design language thống nhất:
+
+### Web Client (User-facing)
+
+- **Mục đích**: Chat interface cho end users tương tác với AI
+- **Design inspiration**: x.ai Grok, OpenAI ChatGPT
+- **Key features**:
+  - Minimalistic và intuitive
+  - Dark mode as default với light mode option
+  - Real-time chat với typing indicators
+  - Message history và conversation management
+  - Multi-modal input (text, voice future)
+
+### Web Admin (Admin-facing)
+
+- **Mục đích**: Dashboard quản lý users, analytics, system settings
+- **Design inspiration**: Modern admin dashboards với AI-powered insights
+- **Key features**:
+  - Analytics dashboard với charts/graphs
+  - User management với advanced filtering
+  - System monitoring và health checks
+  - Content moderation tools
+  - Configuration management
+```mermaid
+graph TB
+    subgraph Design System
+        Colors[Color Palette<br/>Dark + Light Mode]
+        Typo[Typography<br/>System Fonts]
+        Comp[Components<br/>Radix UI]
+        Icons[Icons<br/>Lucide React]
+    end
+
+    subgraph Web Client
+        Auth1[Authentication]
+        Chat[Chat Interface]
+        History[Conversation History]
+        Settings1[User Settings]
+    end
+
+    subgraph Web Admin
+        Dashboard[Analytics Dashboard]
+        Users[User Management]
+        Monitor[System Monitoring]
+        Settings2[Admin Settings]
+    end
+
+    Colors --> Web Client
+    Colors --> Web Admin
+    Typo --> Web Client
+    Typo --> Web Admin
+    Comp --> Web Client
+    Comp --> Web Admin
+    Icons --> Web Client
+    Icons --> Web Admin
+```
+
+
+## I. Design System Foundation
+
+### 1.1 Color Palette
+
+#### Dark Mode (Primary Theme)
+
+Dựa trên research, dark mode giảm eye strain 67% và là xu hướng chính cho AI chat interfaces.
+
+**Background Colors:**
+
+```css
+--bg-primary: #0A0A0A        /* Main background - Almost black */
+--bg-secondary: #121212      /* Card/Panel background - Dark grey (better depth) */
+--bg-tertiary: #1A1A1A       /* Hover states */
+--bg-elevated: #242424       /* Elevated surfaces (modals, dropdowns) */
+```
+
+**Text Colors (WCAG Compliant):**
+
+```css
+--text-primary: #FAFAFA      /* Primary text - Off-white (4.5:1 contrast) */
+--text-secondary: #E0E0E0    /* Secondary text - Light grey */
+--text-tertiary: #A0A0A0     /* Tertiary/disabled text */
+--text-inverse: #1A1A1A      /* Text on light backgrounds */
+```
+
+**Brand/Accent Colors:**
+
+```css
+--accent-primary: #3B82F6    /* Primary blue - CTAs, links */
+--accent-secondary: #8B5CF6  /* Purple - Highlights */
+--accent-success: #10B981    /* Green - Success states */
+--accent-warning: #F59E0B    /* Amber - Warnings */
+--accent-error: #EF4444      /* Red - Errors */
+--accent-info: #06B6D4       /* Cyan - Info */
+```
+
+**Chat Specific Colors:**
+
+```css
+--chat-user-bubble: #2563EB        /* User message - Deep blue */
+--chat-ai-bubble: #374151          /* AI message - Dark grey */
+--chat-user-text: #FFFFFF          /* White text on blue */
+--chat-ai-text: #F3F4F6            /* Light text on grey */
+--chat-timestamp: #9CA3AF          /* Timestamp grey */
+--chat-divider: #1F2937            /* Divider between messages */
+```
+
+**Border Colors:**
+
+```css
+--border-primary: #2A2A2A    /* Default borders */
+--border-secondary: #3A3A3A  /* Hover borders */
+--border-focus: #3B82F6      /* Focus state - Blue */
+```
+
+#### Light Mode (Secondary Theme)
+
+```css
+/* Light mode variants */
+--bg-primary-light: #FFFFFF
+--bg-secondary-light: #F9FAFB
+--bg-tertiary-light: #F3F4F6
+--text-primary-light: #111827
+--text-secondary-light: #4B5563
+--border-primary-light: #E5E7EB
+```
+
+**Semantic Color Usage:**
+
+- Primary blue (#3B82F6): CTAs, primary buttons, active states
+- Purple (#8B5CF6): Premium features, AI-related highlights
+- Success green (#10B981): Confirmations, success messages
+- Warning amber (#F59E0B): Warnings, caution states
+- Error red (#EF4444): Errors, destructive actions
+
+### 1.2 Typography
+
+Theo OpenAI guidelines, sử dụng **system fonts** để ensure readability và accessibility.
+
+**Font Stack:**
+
+```css
+--font-sans:
+  -apple-system,
+  BlinkMacSystemFont,
+  "SF Pro Display",    /* iOS/macOS */
+  "Segoe UI",          /* Windows */
+  Roboto,              /* Android */
+  "Helvetica Neue",
+  Arial,
+  sans-serif;
+
+--font-mono:
+  "SF Mono",
+  Consolas,
+  "Liberation Mono",
+  Menlo,
+  monospace;
+```
+
+**Type Scale (Tailwind-based):**
+
+```css
+/* Display - Headers */
+--text-6xl: 3.75rem / 1      /* 60px - Hero titles */
+--text-5xl: 3rem / 1         /* 48px - Page titles */
+--text-4xl: 2.25rem / 1.1    /* 36px - Section headers */
+--text-3xl: 1.875rem / 1.2   /* 30px - Card headers */
+
+/* Body */
+--text-2xl: 1.5rem / 1.3     /* 24px - Large body */
+--text-xl: 1.25rem / 1.4     /* 20px - Emphasized text */
+--text-lg: 1.125rem / 1.5    /* 18px - Large body */
+--text-base: 1rem / 1.5      /* 16px - Default body */
+--text-sm: 0.875rem / 1.5    /* 14px - Small text */
+--text-xs: 0.75rem / 1.5     /* 12px - Captions */
+```
+
+**Font Weights:**
+
+```css
+--font-light: 300     /* Light text */
+--font-normal: 400    /* Body text */
+--font-medium: 500    /* Emphasized */
+--font-semibold: 600  /* Headings */
+--font-bold: 700      /* Strong emphasis */
+```
+
+**Chat Typography:**
+
+- Message text: 16px (text-base), regular weight
+- Timestamps: 12px (text-xs), light weight
+- User names: 14px (text-sm), medium weight
+- System messages: 14px (text-sm), italic
+
+### 1.3 Spacing & Layout
+
+**Base Unit: 4px (0.25rem)**
+
+**Spacing Scale:**
+
+```css
+--space-0: 0           /* 0px */
+--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 */
+```
+
+**Container Widths:**
+
+```css
+--container-sm: 640px    /* Small devices */
+--container-md: 768px    /* Medium devices */
+--container-lg: 1024px   /* Large devices */
+--container-xl: 1280px   /* Extra large */
+--container-2xl: 1536px  /* 2X large */
+
+/* Chat specific */
+--chat-max-width: 768px  /* Max width for chat messages */
+--sidebar-width: 280px   /* Conversation history sidebar */
+```
+
+**Border Radius:**
+
+```css
+--radius-sm: 0.25rem    /* 4px - Small elements */
+--radius-md: 0.5rem     /* 8px - Buttons, inputs */
+--radius-lg: 0.75rem    /* 12px - Cards */
+--radius-xl: 1rem       /* 16px - Large cards */
+--radius-2xl: 1.5rem    /* 24px - Modals */
+--radius-full: 9999px   /* Full round - Avatars, pills */
+```
+
+**Shadows (Dark Mode Optimized):**
+
+```css
+--shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.5);
+--shadow-md: 0 4px 6px rgba(0, 0, 0, 0.5);
+--shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.6);
+--shadow-xl: 0 20px 25px rgba(0, 0, 0, 0.7);
+--shadow-glow: 0 0 20px rgba(59, 130, 246, 0.3); /* Blue glow for focus */
+```
+
+### 1.4 Grid System
+
+**Responsive Breakpoints:**
+
+```css
+--screen-sm: 640px   /* Mobile landscape */
+--screen-md: 768px   /* Tablet */
+--screen-lg: 1024px  /* Desktop */
+--screen-xl: 1280px  /* Large desktop */
+--screen-2xl: 1536px /* Extra large desktop */
+```
+
+**Layout Patterns:**
+
+- **Single Column (Mobile)**: < 768px - Full width content
+- **Two Column (Tablet)**: 768px - 1024px - Sidebar + Main
+- **Three Column (Desktop)**: > 1024px - Sidebar + Main + Panel
+
+### 1.5 Animation & Transitions
+
+**Timing Functions:**
+
+```css
+--ease-in: cubic-bezier(0.4, 0, 1, 1);
+--ease-out: cubic-bezier(0, 0, 0.2, 1);
+--ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
+--ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
+```
+
+**Duration:**
+
+```css
+--duration-fast: 150ms      /* Hover effects */
+--duration-normal: 250ms    /* Default transitions */
+--duration-slow: 350ms      /* Complex animations */
+--duration-slower: 500ms    /* Page transitions */
+```
+
+**Common Transitions:**
+
+```css
+/* Smooth hover */
+transition: all var(--duration-fast) var(--ease-out);
+
+/* Button press */
+transition: transform var(--duration-fast) var(--ease-in-out);
+
+/* Modal open */
+transition: opacity var(--duration-normal) var(--ease-in-out),
+            transform var(--duration-normal) var(--ease-spring);
+```
+
+**Micro-interactions (2026 Trend):**
+
+- Button hover: Subtle scale (1.02) + brightness
+- Card hover: Lift effect (translateY -2px) + shadow
+- Input focus: Glow effect (box-shadow) + border color
+- Message send: Slide up + fade in
+- Typing indicator: Pulsing dots animation
+
+## II. Component Library
+
+### 2.1 Core Components (Radix UI based)
+
+#### Button
+
+**Variants:**
+
+```typescript
+// Primary - Main CTAs
+<Button variant="primary" size="md">
+  Send Message
+</Button>
+
+// Secondary - Less emphasis
+<Button variant="secondary" size="md">
+  Cancel
+</Button>
+
+// Ghost - Minimal
+<Button variant="ghost" size="sm">
+  Edit
+</Button>
+
+// Danger - Destructive actions
+<Button variant="danger" size="md">
+  Delete
+</Button>
+```
+
+**Sizes:**
+
+- `xs`: 28px height, 12px text, 12px padding
+- `sm`: 32px height, 14px text, 16px padding
+- `md`: 40px height, 16px text, 20px padding (default)
+- `lg`: 48px height, 18px text, 24px padding
+- `xl`: 56px height, 20px text, 28px padding
+
+**States:**
+
+- Default: Normal appearance
+- Hover: Brightness 110%, slight scale (1.02)
+- Active: Brightness 90%, scale (0.98)
+- Focus: Blue glow shadow
+- Disabled: Opacity 50%, cursor not-allowed
+- Loading: Spinner icon, disabled state
+
+**Implementation:**
+
+```css
+/* Primary Button */
+.btn-primary {
+  background: var(--accent-primary);
+  color: white;
+  border-radius: var(--radius-md);
+  padding: var(--space-3) var(--space-5);
+  font-weight: var(--font-medium);
+  transition: all var(--duration-fast) var(--ease-out);
+}
+
+.btn-primary:hover {
+  filter: brightness(1.1);
+  transform: scale(1.02);
+}
+
+.btn-primary:focus-visible {
+  outline: none;
+  box-shadow: var(--shadow-glow);
+}
+```
+
+#### Input Fields
+
+**Types:**
+
+- Text Input
+- Textarea
+- Select
+- Multi-select
+- Date Picker
+- Search (with icon)
+
+**Structure:**
+
+```tsx
+<div className="input-group">
+  <label htmlFor="email">Email Address</label>
+  <input
+    id="email"
+    type="email"
+    placeholder="you@example.com"
+    className="input"
+  />
+  <span className="input-hint">We'll never share your email</span>
+</div>
+```
+
+**Styles:**
+
+```css
+.input {
+  background: var(--bg-secondary);
+  border: 1px solid var(--border-primary);
+  color: var(--text-primary);
+  border-radius: var(--radius-md);
+  padding: var(--space-3) var(--space-4);
+  font-size: var(--text-base);
+  transition: all var(--duration-fast) var(--ease-out);
+}
+
+.input:focus {
+  border-color: var(--accent-primary);
+  box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);
+  outline: none;
+}
+
+.input::placeholder {
+  color: var(--text-tertiary);
+}
+
+.input-hint {
+  color: var(--text-tertiary);
+  font-size: var(--text-sm);
+  margin-top: var(--space-1);
+}
+```
+
+**States:**
+
+- Default
+- Focus (blue border + glow)
+- Error (red border + error message)
+- Success (green border + checkmark)
+- Disabled (grey + cursor not-allowed)
+
+#### Card
+
+**Variants:**
+
+```tsx
+// Default Card
+<Card>
+  <CardHeader>
+    <CardTitle>Card Title</CardTitle>
+    <CardDescription>Card description</CardDescription>
+  </CardHeader>
+  <CardContent>
+    Content goes here
+  </CardContent>
+  <CardFooter>
+    Footer actions
+  </CardFooter>
+</Card>
+
+// Interactive Card (hover effect)
+<Card hover>
+  ...
+</Card>
+
+// Bordered Card
+<Card bordered>
+  ...
+</Card>
+```
+
+**Styles:**
+
+```css
+.card {
+  background: var(--bg-secondary);
+  border-radius: var(--radius-lg);
+  padding: var(--space-6);
+  transition: all var(--duration-normal) var(--ease-out);
+}
+
+.card.hover:hover {
+  transform: translateY(-2px);
+  box-shadow: var(--shadow-lg);
+}
+
+.card-header {
+  margin-bottom: var(--space-4);
+}
+
+.card-title {
+  font-size: var(--text-xl);
+  font-weight: var(--font-semibold);
+  color: var(--text-primary);
+}
+
+.card-description {
+  font-size: var(--text-sm);
+  color: var(--text-secondary);
+  margin-top: var(--space-1);
+}
+```
+
+#### Modal/Dialog
+
+**Structure:**
+
+```tsx
+<Dialog open={isOpen} onOpenChange={setIsOpen}>
+  <DialogTrigger asChild>
+    <Button>Open Dialog</Button>
+  </DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Dialog Title</DialogTitle>
+      <DialogDescription>
+        Dialog description text
+      </DialogDescription>
+    </DialogHeader>
+    <div className="dialog-body">
+      {/* Content */}
+    </div>
+    <DialogFooter>
+      <Button variant="secondary" onClick={() => setIsOpen(false)}>
+        Cancel
+      </Button>
+      <Button variant="primary">
+        Confirm
+      </Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+**Animation:**
+
+```css
+/* Overlay fade in */
+@keyframes overlay-fade {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+/* Content scale + fade */
+@keyframes content-show {
+  from {
+    opacity: 0;
+    transform: translate(-50%, -48%) scale(0.96);
+  }
+  to {
+    opacity: 1;
+    transform: translate(-50%, -50%) scale(1);
+  }
+}
+
+.dialog-overlay {
+  background: rgba(0, 0, 0, 0.6);
+  backdrop-filter: blur(8px);
+  animation: overlay-fade var(--duration-normal) var(--ease-out);
+}
+
+.dialog-content {
+  background: var(--bg-elevated);
+  border-radius: var(--radius-2xl);
+  box-shadow: var(--shadow-xl);
+  animation: content-show var(--duration-normal) var(--ease-spring);
+}
+```
+
+#### Avatar
+
+**Sizes:**
+
+- `xs`: 24px
+- `sm`: 32px
+- `md`: 40px (default)
+- `lg`: 48px
+- `xl`: 64px
+
+**States:**
+
+- Image loaded
+- Fallback (initials)
+- Loading (skeleton)
+- Status indicator (online/offline/away)
+```tsx
+<Avatar size="md" status="online">
+  <AvatarImage src="/user.jpg" alt="John Doe" />
+  <AvatarFallback>JD</AvatarFallback>
+</Avatar>
+```
+
+
+### 2.2 Chat-Specific Components
+
+#### Message Bubble
+
+**Structure:**
+
+```tsx
+<div className="message user">
+  <div className="message-header">
+    <span className="message-author">You</span>
+    <span className="message-time">2:30 PM</span>
+  </div>
+  <div className="message-bubble">
+    <p className="message-text">Hello, how can I help you?</p>
+  </div>
+</div>
+
+<div className="message ai">
+  <Avatar size="sm" src="/ai-avatar.png" />
+  <div className="message-content">
+    <div className="message-header">
+      <span className="message-author">AI Assistant</span>
+      <span className="message-time">2:31 PM</span>
+    </div>
+    <div className="message-bubble">
+      <p className="message-text">I can help you with...</p>
+    </div>
+  </div>
+</div>
+```
+
+**Styles:**
+
+```css
+/* User Message (Right aligned, blue) */
+.message.user {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  margin-bottom: var(--space-4);
+}
+
+.message.user .message-bubble {
+  background: var(--chat-user-bubble);
+  color: var(--chat-user-text);
+  border-radius: var(--radius-lg) var(--radius-lg) var(--radius-sm) var(--radius-lg);
+  padding: var(--space-3) var(--space-4);
+  max-width: 70%;
+  word-wrap: break-word;
+}
+
+/* AI Message (Left aligned, grey) */
+.message.ai {
+  display: flex;
+  gap: var(--space-3);
+  margin-bottom: var(--space-4);
+}
+
+.message.ai .message-bubble {
+  background: var(--chat-ai-bubble);
+  color: var(--chat-ai-text);
+  border-radius: var(--radius-lg) var(--radius-lg) var(--radius-lg) var(--radius-sm);
+  padding: var(--space-3) var(--space-4);
+  max-width: 70%;
+}
+
+/* Message Header */
+.message-header {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  margin-bottom: var(--space-1);
+}
+
+.message-author {
+  font-size: var(--text-sm);
+  font-weight: var(--font-medium);
+  color: var(--text-secondary);
+}
+
+.message-time {
+  font-size: var(--text-xs);
+  color: var(--chat-timestamp);
+}
+```
+
+**Message Animations:**
+
+```css
+/* Slide up + fade in */
+@keyframes message-in {
+  from {
+    opacity: 0;
+    transform: translateY(10px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.message {
+  animation: message-in var(--duration-normal) var(--ease-out);
+}
+```
+
+#### Typing Indicator
+
+```tsx
+<div className="typing-indicator">
+  <div className="typing-dot"></div>
+  <div className="typing-dot"></div>
+  <div className="typing-dot"></div>
+</div>
+```
+```css
+.typing-indicator {
+  display: flex;
+  gap: 4px;
+  padding: var(--space-3);
+}
+
+.typing-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--text-tertiary);
+  animation: typing 1.4s infinite;
+}
+
+.typing-dot:nth-child(2) {
+  animation-delay: 0.2s;
+}
+
+.typing-dot:nth-child(3) {
+  animation-delay: 0.4s;
+}
+
+@keyframes typing {
+  0%, 60%, 100% {
+    opacity: 0.3;
+    transform: scale(0.8);
+  }
+  30% {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+```
+
+#### Chat Input
+
+```tsx
+<div className="chat-input-container">
+  <div className="chat-input-wrapper">
+    <button className="chat-input-action" aria-label="Attach file">
+      <PaperclipIcon />
+    </button>
+
+    <textarea
+      className="chat-input"
+      placeholder="Type a message..."
+      rows={1}
+      onKeyDown={handleKeyDown}
+    />
+
+    <button className="chat-input-send" aria-label="Send message">
+      <SendIcon />
+    </button>
+  </div>
+
+  <div className="chat-input-hint">
+    Press Enter to send, Shift+Enter for new line
+  </div>
+</div>
+```
+```css
+.chat-input-container {
+  position: sticky;
+  bottom: 0;
+  background: var(--bg-primary);
+  border-top: 1px solid var(--border-primary);
+  padding: var(--space-4);
+}
+
+.chat-input-wrapper {
+  display: flex;
+  align-items: flex-end;
+  gap: var(--space-2);
+  background: var(--bg-secondary);
+  border: 1px solid var(--border-primary);
+  border-radius: var(--radius-xl);
+  padding: var(--space-2);
+  transition: border-color var(--duration-fast) var(--ease-out);
+}
+
+.chat-input-wrapper:focus-within {
+  border-color: var(--accent-primary);
+  box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);
+}
+
+.chat-input {
+  flex: 1;
+  background: transparent;
+  border: none;
+  color: var(--text-primary);
+  font-size: var(--text-base);
+  resize: none;
+  max-height: 120px;
+  padding: var(--space-2);
+}
+
+.chat-input:focus {
+  outline: none;
+}
+
+.chat-input-action,
+.chat-input-send {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 36px;
+  height: 36px;
+  border-radius: var(--radius-md);
+  background: transparent;
+  border: none;
+  color: var(--text-secondary);
+  cursor: pointer;
+  transition: all var(--duration-fast) var(--ease-out);
+}
+
+.chat-input-action:hover {
+  background: var(--bg-tertiary);
+  color: var(--text-primary);
+}
+
+.chat-input-send {
+  background: var(--accent-primary);
+  color: white;
+}
+
+.chat-input-send:hover {
+  filter: brightness(1.1);
+  transform: scale(1.05);
+}
+
+.chat-input-send:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.chat-input-hint {
+  font-size: var(--text-xs);
+  color: var(--text-tertiary);
+  margin-top: var(--space-2);
+  text-align: center;
+}
+```
+
+#### Conversation Sidebar
+
+```tsx
+<aside className="conversation-sidebar">
+  <div className="sidebar-header">
+    <h2>Conversations</h2>
+    <button className="new-chat-btn">
+      <PlusIcon />
+      New Chat
+    </button>
+  </div>
+
+  <div className="sidebar-search">
+    <SearchIcon />
+    <input type="search" placeholder="Search conversations..." />
+  </div>
+
+  <div className="conversation-list">
+    <button className="conversation-item active">
+      <div className="conversation-title">Project Discussion</div>
+      <div className="conversation-preview">Last message preview...</div>
+      <div className="conversation-time">2m ago</div>
+    </button>
+
+    <button className="conversation-item">
+      <div className="conversation-title">Design Review</div>
+      <div className="conversation-preview">Can you check...</div>
+      <div className="conversation-time">1h ago</div>
+    </button>
+  </div>
+</aside>
+```
+```css
+.conversation-sidebar {
+  width: var(--sidebar-width);
+  height: 100vh;
+  background: var(--bg-secondary);
+  border-right: 1px solid var(--border-primary);
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+.sidebar-header {
+  padding: var(--space-4);
+  border-bottom: 1px solid var(--border-primary);
+}
+
+.sidebar-header h2 {
+  font-size: var(--text-lg);
+  font-weight: var(--font-semibold);
+  margin-bottom: var(--space-3);
+}
+
+.new-chat-btn {
+  width: 100%;
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  padding: var(--space-3);
+  background: var(--accent-primary);
+  color: white;
+  border: none;
+  border-radius: var(--radius-md);
+  font-weight: var(--font-medium);
+  cursor: pointer;
+  transition: all var(--duration-fast) var(--ease-out);
+}
+
+.new-chat-btn:hover {
+  filter: brightness(1.1);
+}
+
+.sidebar-search {
+  padding: var(--space-4);
+  border-bottom: 1px solid var(--border-primary);
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+}
+
+.sidebar-search input {
+  flex: 1;
+  background: var(--bg-tertiary);
+  border: 1px solid var(--border-primary);
+  border-radius: var(--radius-md);
+  padding: var(--space-2) var(--space-3);
+  color: var(--text-primary);
+  font-size: var(--text-sm);
+}
+
+.conversation-list {
+  flex: 1;
+  overflow-y: auto;
+  padding: var(--space-2);
+}
+
+.conversation-item {
+  width: 100%;
+  padding: var(--space-3);
+  background: transparent;
+  border: none;
+  border-radius: var(--radius-md);
+  text-align: left;
+  cursor: pointer;
+  transition: background var(--duration-fast) var(--ease-out);
+  margin-bottom: var(--space-1);
+}
+
+.conversation-item:hover {
+  background: var(--bg-tertiary);
+}
+
+.conversation-item.active {
+  background: var(--bg-tertiary);
+  border-left: 3px solid var(--accent-primary);
+}
+
+.conversation-title {
+  font-size: var(--text-sm);
+  font-weight: var(--font-medium);
+  color: var(--text-primary);
+  margin-bottom: var(--space-1);
+}
+
+.conversation-preview {
+  font-size: var(--text-xs);
+  color: var(--text-tertiary);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.conversation-time {
+  font-size: var(--text-xs);
+  color: var(--text-tertiary);
+  margin-top: var(--space-1);
+}
+```
+
+### 2.3 Admin Components
+
+#### Data Table
+
+```tsx
+<DataTable
+  columns={columns}
+  data={data}
+  searchable
+  filterable
+  sortable
+  pagination
+/>
+```
+
+**Features:**
+
+- Column sorting
+- Global search
+- Column filters
+- Pagination
+- Row selection
+- Bulk actions
+- Export to CSV/Excel
+- Column visibility toggle
+
+#### Analytics Card
+
+```tsx
+<AnalyticsCard
+  title="Total Users"
+  value="12,345"
+  change="+12.5%"
+  trend="up"
+  icon={<UsersIcon />}
+/>
+```
+
+**Variants:**
+
+- Metric card (single value)
+- Chart card (with graph)
+- Progress card (with progress bar)
+- Comparison card (multiple metrics)
+
+#### Charts
+
+Using Recharts or Tremor library:
+
+- Line Chart (Trends over time)
+- Bar Chart (Comparisons)
+- Pie/Donut Chart (Distributions)
+- Area Chart (Cumulative data)
+- Heatmap (Activity patterns)
+
+## III. Web Client - Detailed Screens
+
+### 3.1 Authentication Pages
+
+#### Login Page
+
+**Layout:**
+
+```
+┌─────────────────────────────────────┐
+│                                     │
+│           [Logo]                    │
+│                                     │
+│       Sign in to GoodGo            │
+│                                     │
+│   ┌───────────────────────────┐   │
+│   │ Email                      │   │
+│   │ [                    ]     │   │
+│   └───────────────────────────┘   │
+│                                     │
+│   ┌───────────────────────────┐   │
+│   │ Password                   │   │
+│   │ [                    ]     │   │
+│   └───────────────────────────┘   │
+│                                     │
+│   [ ] Remember me    Forgot password? │
+│                                     │
+│   ┌───────────────────────────┐   │
+│   │      Sign in              │   │
+│   └───────────────────────────┘   │
+│                                     │
+│   ─────── OR ───────               │
+│                                     │
+│   ┌───────────────────────────┐   │
+│   │  🔵 Continue with Google  │   │
+│   └───────────────────────────┘   │
+│                                     │
+│   Don't have an account? Sign up   │
+│                                     │
+└─────────────────────────────────────┘
+```
+
+**Key Elements:**
+
+- Centered card (max-width: 400px)
+- Logo at top
+- H1: "Sign in to GoodGo"
+- Email input (with validation)
+- Password input (with show/hide toggle)
+- Remember me checkbox
+- Forgot password link
+- Primary button: "Sign in"
+- Divider: "OR"
+- OAuth buttons (Google, optionally GitHub)
+- Sign up link at bottom
+
+**Validation:**
+
+- Real-time email format validation
+- Password strength indicator (on sign up)
+- Error messages below inputs
+- Success message on successful login
+- Loading state on button during auth
+
+#### Register Page
+
+Similar to login with additional fields:
+
+- Full Name
+- Email
+- Password
+- Confirm Password
+- Terms & Conditions checkbox
+- Password strength meter
+- Sign up button
+- Already have account? Sign in link
+
+**Password Strength Indicator:**
+
+```tsx
+<div className="password-strength">
+  <div className="strength-bar">
+    <div className="strength-fill" style={{ width: `${strength}%` }} />
+  </div>
+  <span className="strength-text">{strengthLabel}</span>
+</div>
+```
+
+Levels:
+
+- Weak (0-25%): Red
+- Fair (26-50%): Orange
+- Good (51-75%): Yellow
+- Strong (76-100%): Green
+
+#### Forgot Password Page
+
+**Flow:**
+
+1. Enter email → Send reset link
+2. Check email → Click link
+3. Enter new password → Confirm
+4. Success → Redirect to login
+
+### 3.2 Main Chat Interface
+
+**Layout (Desktop):**
+
+```
+┌──────────┬─────────────────────────────────────────┬────────────┐
+│          │                                         │            │
+│  SIDEBAR │           MAIN CHAT AREA               │   PANEL    │
+│          │                                         │  (optional) │
+│  Convos  │                                         │            │
+│          │  ┌─────────────────────────────────┐   │  Settings  │
+│  [+New]  │  │ AI: How can I help you?        │   │  or        │
+│          │  └─────────────────────────────┘   │  Info      │
+│  • Chat1 │                                         │            │
+│  • Chat2 │  ┌─────────────────────────────────┐   │            │
+│  • Chat3 │  │           You: Hello           │   │            │
+│          │  └─────────────────────────────────┘   │            │
+│          │                                         │            │
+│          │  ┌─────────────────────────────────┐   │            │
+│          │  │ AI: Hi! I'm here to help...    │   │            │
+│          │  └─────────────────────────────────┘   │            │
+│          │                                         │            │
+│  [User]  │  ┌─────────────────────────────────┐   │            │
+│  Avatar  │  │  [Type a message...]      [Send]│   │            │
+│  Settings│  └─────────────────────────────────┘   │            │
+│          │                                         │            │
+└──────────┴─────────────────────────────────────────┴────────────┘
+```
+
+**Components Breakdown:**
+
+1. **Left Sidebar** (280px wide)
+
+   - New Chat button (sticky top)
+   - Search conversations
+   - Conversation list (scrollable)
+   - User profile (sticky bottom)
+
+2. **Main Chat Area** (flex-1, max 768px centered)
+
+   - Header (conversation title, options)
+   - Messages container (scrollable, auto-scroll to bottom)
+   - Typing indicator
+   - Input area (sticky bottom)
+
+3. **Right Panel** (320px, optional, collapsible)
+
+   - Conversation settings
+   - Participants
+   - Shared files
+   - Quick actions
+
+**Message Types:**
+
+1. **Text Message**
+
+   - Plain text with markdown support
+   - Code blocks with syntax highlighting
+   - Links with preview cards
+
+2. **System Message**
+
+   - Centered, grey text
+   - Used for timestamps, status updates
+
+3. **Error Message**
+
+   - Red border, error icon
+   - Retry button
+
+4. **Loading Message**
+
+   - Skeleton or typing indicator
+   - Shown while AI is generating
+
+**Message Actions (on hover):**
+
+- Copy message
+- Edit (user messages only)
+- Delete (user messages only)
+- Regenerate (AI messages)
+- Like/Dislike (feedback)
+- Share
+
+### 3.3 User Settings
+
+**Navigation Tabs:**
+
+- Profile
+- Preferences
+- Security
+- Notifications
+- Billing (if applicable)
+- API Keys (for developers)
+
+**Profile Tab:**
+
+```
+Avatar Upload
+┌──────────┐
+│  [👤]    │  Change avatar
+└──────────┘
+
+Full Name:    [John Doe              ]
+Email:        [john@example.com      ] (verified ✓)
+Username:     [@johndoe              ]
+Bio:          [Software developer... ]
+              [                       ]
+
+[Save Changes]  [Cancel]
+```
+
+**Preferences Tab:**
+
+- Language selection
+- Theme (Dark/Light/Auto)
+- Chat settings
+  - Auto-scroll to new messages
+  - Show timestamps
+  - Message grouping
+  - Font size
+- Accessibility
+  - High contrast mode
+  - Screen reader optimizations
+
+**Security Tab:**
+
+- Change password
+- Two-factor authentication (2FA)
+  - Enable/Disable
+  - QR code for setup
+- Active sessions
+  - List of devices
+  - Revoke access option
+- Delete account (danger zone)
+
+## IV. Web Admin - Detailed Screens
+
+### 4.1 Dashboard (Overview)
+
+**Layout:**
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  HEADER: Dashboard                        [User] [Settings] │
+├────────────┬────────────────────────────────────────────────┤
+│            │                                                 │
+│  SIDEBAR   │  METRICS ROW                                   │
+│            │  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │
+│ • Dashboard│  │ Users  │ │Messages│ │ Active │ │Revenue │ │
+│ • Users    │  │ 12.3K  │ │  45K   │ │  892   │ │ $1.2K  │ │
+│ • Analytics│  │ +12%   │ │  +8%   │ │  +5%   │ │ +15%   │ │
+│ • Messages │  └────────┘ └────────┘ └────────┘ └────────┘ │
+│ • Settings │                                                 │
+│            │  CHARTS ROW                                    │
+│ Admin      │  ┌─────────────────────┐ ┌──────────────────┐ │
+│            │  │                     │ │                  │ │
+│ [Logout]   │  │  User Growth Chart  │ │  Revenue Chart   │ │
+│            │  │                     │ │                  │ │
+│            │  └─────────────────────┘ └──────────────────┘ │
+│            │                                                 │
+│            │  RECENT ACTIVITY TABLE                         │
+│            │  ┌──────────────────────────────────────────┐ │
+│            │  │ User  │ Action  │ Time    │ Status      │ │
+│            │  ├──────────────────────────────────────────┤ │
+│            │  │ John  │ Signed  │ 2m ago  │ Success     │ │
+│            │  │ Jane  │ Message │ 5m ago  │ Completed   │ │
+│            │  └──────────────────────────────────────────┘ │
+│            │                                                 │
+└────────────┴────────────────────────────────────────────────┘
+```
+
+**Metric Cards (Top Row):**
+
+Each card shows:
+
+- Icon (relevant to metric)
+- Label (e.g., "Total Users")
+- Large number value
+- Percentage change (with trend arrow)
+- Sparkline chart (mini trend)
+- Time period (e.g., "vs last month")
+
+**Charts:**
+
+1. **User Growth Chart** (Line Chart)
+
+   - X-axis: Time (days/weeks/months)
+   - Y-axis: User count
+   - Multiple lines (total, active, new)
+   - Interactive tooltip on hover
+
+2. **Revenue Chart** (Area Chart)
+
+   - Cumulative revenue over time
+   - Color gradient fill
+   - Comparison to previous period
+
+3. **Message Activity Heatmap**
+
+   - Days of week vs hours
+   - Color intensity = activity level
+
+**Recent Activity Table:**
+
+- User avatar + name
+- Action performed
+- Timestamp (relative)
+- Status badge
+- Quick actions (view, edit)
+- Pagination at bottom
+
+### 4.2 User Management
+
+**Features:**
+
+- User list with search/filter
+- User details modal
+- Bulk actions (activate, deactivate, delete)
+- User roles management
+- Activity logs
+
+**User List Table:**
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ Users                                    [+ Add User]       │
+├────────────────────────────────────────────────────────────┤
+│ 🔍 Search users...          🔽 Filter    📊 Export         │
+├────────────────────────────────────────────────────────────┤
+│ ☐ │Avatar│ Name      │ Email          │ Role  │ Status  │ │
+├────────────────────────────────────────────────────────────┤
+│ ☐ │ [👤] │ John Doe  │ john@mail.com  │ Admin │ Active  │ │
+│ ☐ │ [👤] │ Jane Doe  │ jane@mail.com  │ User  │ Active  │ │
+│ ☐ │ [👤] │ Bob Smith │ bob@mail.com   │ User  │ Inactive│ │
+├────────────────────────────────────────────────────────────┤
+│ Showing 1-10 of 150              [< 1 2 3 4 5 >]          │
+└────────────────────────────────────────────────────────────┘
+```
+
+**Filters:**
+
+- Role (Admin, User, Moderator)
+- Status (Active, Inactive, Banned)
+- Date range (Created, Last active)
+- Sort by (Name, Email, Date, Activity)
+
+**User Details Modal:**
+
+- Profile information
+- Activity timeline
+- Message history
+- Edit user button
+- Deactivate/Delete buttons
+
+### 4.3 Analytics
+
+**Tabs:**
+
+- Overview
+- Users
+- Messages
+- Performance
+- Custom Reports
+
+**Overview Tab:**
+
+- Key metrics summary
+- Trends visualization
+- Comparison charts (day/week/month/year)
+- Export to PDF/CSV
+
+**Users Tab:**
+
+- User acquisition funnel
+- Retention chart
+- Cohort analysis
+- Geographic distribution map
+- Device/browser breakdown
+
+**Messages Tab:**
+
+- Total messages sent
+- Average messages per user
+- Peak activity times
+- Popular topics/keywords
+- Sentiment analysis
+
+**Performance Tab:**
+
+- API response times
+- Error rates
+- Uptime statistics
+- Server resources (CPU, Memory, Disk)
+
+### 4.4 System Settings
+
+**Categories:**
+
+- General
+- Email
+- Security
+- API
+- Advanced
+
+**General Settings:**
+
+- Site name
+- Site logo
+- Default language
+- Timezone
+- Maintenance mode toggle
+
+**Email Settings:**
+
+- SMTP configuration
+- Email templates
+- Test email function
+
+**Security Settings:**
+
+- Password policy
+- Session timeout
+- IP whitelist/blacklist
+- Rate limiting
+- CORS settings
+
+**API Settings:**
+
+- API keys management
+- Webhooks configuration
+- Rate limits
+- Documentation link
+
+## V. Responsive Design
+
+### 5.1 Breakpoints Strategy
+
+**Mobile First Approach:**
+
+```css
+/* Mobile (default) */
+/* < 640px */
+
+/* Tablet */
+@media (min-width: 768px) {
+  /* Tablet styles */
+}
+
+/* Desktop */
+@media (min-width: 1024px) {
+  /* Desktop styles */
+}
+
+/* Large Desktop */
+@media (min-width: 1280px) {
+  /* Large desktop styles */
+}
+```
+
+### 5.2 Mobile Layout (< 768px)
+
+**Web Client Mobile:**
+
+```
+┌──────────────────┐
+│  [☰] GoodGo [⚙] │ ← Header (fixed)
+├──────────────────┤
+│                  │
+│  ┌────────────┐  │
+│  │ AI: Hello  │  │
+│  └────────────┘  │
+│                  │
+│  ┌────────────┐  │
+│  │ You: Hi    │  │
+│  └────────────┘  │
+│                  │
+│                  │
+│                  │ ← Messages (scrollable)
+│                  │
+├──────────────────┤
+│ [Type...] [Send] │ ← Input (fixed)
+└──────────────────┘
+```
+
+**Mobile Adaptations:**
+
+- Hide sidebar by default (hamburger menu)
+- Full-width messages
+- Sticky header + input
+- Swipe gestures (back, delete)
+- Bottom tab navigation (optional)
+
+**Web Admin Mobile:**
+
+```
+┌──────────────────┐
+│ [☰] Dashboard    │ ← Header with menu
+├──────────────────┤
+│                  │
+│ ┌──────────────┐ │
+│ │ Users: 12.3K │ │
+│ │ +12% ↗       │ │
+│ └──────────────┘ │
+│                  │
+│ ┌──────────────┐ │ ← Stacked metrics
+│ │ Messages:45K │ │
+│ │ +8% ↗        │ │
+│ └──────────────┘ │
+│                  │
+│ [View Details]   │
+│                  │
+└──────────────────┘
+```
+
+**Admin Mobile Adaptations:**
+
+- Collapsible sidebar
+- Stacked metric cards
+- Horizontal scroll for tables
+- Simplified charts
+- Touch-friendly buttons (min 44px)
+
+### 5.3 Tablet Layout (768px - 1024px)
+
+**Two-column layout:**
+
+- Show sidebar (toggleable)
+- Medium-width messages (60%)
+- Side-by-side charts (admin)
+
+### 5.4 Touch Interactions
+
+**Touch Targets:**
+
+- Minimum size: 44x44px (iOS HIG)
+- Spacing between: 8px minimum
+- Active state feedback (scale down on press)
+
+**Gestures:**
+
+- Swipe left: Delete message/conversation
+- Swipe right: Archive/mark as read
+- Pull down: Refresh
+- Long press: Context menu
+
+## VI. Accessibility (WCAG 2.1 AA)
+
+### 6.1 Color Contrast
+
+**Requirements:**
+
+- Normal text (< 18px): 4.5:1 minimum
+- Large text (≥ 18px): 3:1 minimum
+- UI components: 3:1 minimum
+
+**Testing Tools:**
+
+- WebAIM Contrast Checker
+- Chrome DevTools Accessibility tab
+- WAVE browser extension
+
+### 6.2 Keyboard Navigation
+
+**Focus Indicators:**
+
+```css
+*:focus-visible {
+  outline: 2px solid var(--accent-primary);
+  outline-offset: 2px;
+}
+```
+
+**Tab Order:**
+
+Logical flow:
+
+1. Skip to main content link
+2. Header navigation
+3. Main content
+4. Sidebar
+5. Footer
+
+**Keyboard Shortcuts:**
+
+- `Tab`: Next element
+- `Shift + Tab`: Previous element
+- `Enter`: Activate button/link
+- `Space`: Toggle checkbox/select
+- `Escape`: Close modal/dropdown
+- `Arrow keys`: Navigate lists/menus
+
+**Custom Shortcuts (Chat):**
+
+- `Ctrl/Cmd + K`: Open search
+- `Ctrl/Cmd + N`: New conversation
+- `Ctrl/Cmd + /`: Show shortcuts help
+- `Alt + ↑/↓`: Navigate conversations
+
+### 6.3 Screen Reader Support
+
+**Semantic HTML:**
+
+```html
+<header>
+<nav aria-label="Main navigation">
+<main>
+<aside aria-label="Conversation history">
+<footer>
+```
+
+**ARIA Labels:**
+
+```html
+<!-- Button with icon only -->
+<button aria-label="Send message">
+  <SendIcon aria-hidden="true" />
+</button>
+
+<!-- Status indicator -->
+<span role="status" aria-live="polite">
+  AI is typing...
+</span>
+
+<!-- Form validation -->
+<input
+  type="email"
+  aria-required="true"
+  aria-invalid="true"
+  aria-describedby="email-error"
+/>
+<span id="email-error" role="alert">
+  Please enter a valid email
+</span>
+```
+
+**Live Regions:**
+
+```html
+<!-- Announcement for new messages -->
+<div role="status" aria-live="polite" aria-atomic="true">
+  New message from AI Assistant
+</div>
+```
+
+### 6.4 Visual Accessibility
+
+**Font Size:**
+
+- Minimum base: 16px
+- User can zoom up to 200% without breaking layout
+
+**Text Spacing:**
+
+- Line height: 1.5 minimum
+- Paragraph spacing: 2x font size
+- Letter spacing: 0.12x font size (for headings)
+
+**Focus Management:**
+
+- Trap focus in modals
+- Return focus after modal close
+- Skip to main content link
+
+**Alternative Text:**
+
+- All images have alt text
+- Decorative images: `alt=""`
+- Avatar images: `alt="John Doe's avatar"`
+
+## VII. Performance Optimization
+
+### 7.1 Loading Strategy
+
+**Critical Rendering Path:**
+
+1. Inline critical CSS (above fold)
+2. Defer non-critical CSS
+3. Async load JavaScript
+4. Lazy load images
+
+**Code Splitting:**
+
+```typescript
+// Route-based splitting
+const Dashboard = lazy(() => import('./pages/Dashboard'));
+const Chat = lazy(() => import('./pages/Chat'));
+
+// Component-based splitting
+const HeavyChart = lazy(() => import('./components/HeavyChart'));
+```
+
+**Image Optimization:**
+
+- Next.js Image component (automatic optimization)
+- WebP format with fallback
+- Responsive images (srcset)
+- Lazy loading (loading="lazy")
+- Blur placeholder (base64)
+
+### 7.2 Perceived Performance
+
+**Skeleton Screens:**
+
+Show content structure while loading:
+
+```tsx
+<div className="skeleton">
+  <div className="skeleton-avatar" />
+  <div className="skeleton-text" />
+  <div className="skeleton-text short" />
+</div>
+```
+
+**Optimistic UI:**
+
+Show immediate feedback before API response:
+
+- Message appears instantly when sent
+- Update UI immediately on action
+- Revert if API call fails
+
+**Loading States:**
+
+- Button loading (spinner inside)
+- Page loading (full-screen or top bar)
+- Partial loading (specific sections)
+
+### 7.3 Caching
+
+**Browser Caching:**
+
+- Static assets: 1 year
+- API responses: Vary by endpoint
+- User data: Session storage
+
+**Service Worker:**
+
+- Cache static assets
+- Offline support (basic)
+- Background sync for messages
+
+## VIII. Tech Stack Implementation
+
+### 8.1 Frontend Stack
+
+**Core:**
+
+- Next.js 14+ (App Router)
+- TypeScript 5+
+- React 18+
+
+**Styling:**
+
+- Tailwind CSS 4
+- CSS Variables (theme tokens)
+- clsx / cn utility (conditional classes)
+
+**UI Components:**
+
+- Radix UI (unstyled primitives)
+- Lucide React (icons)
+- Framer Motion (animations)
+
+**State Management:**
+
+- Zustand (global state)
+- React Query (server state)
+- Context API (theme, auth)
+
+**Forms:**
+
+- React Hook Form
+- Zod (validation)
+
+**Charts:**
+
+- Recharts or Tremor
+
+**Utilities:**
+
+- date-fns (date formatting)
+- clsx (conditional classes)
+- nanoid (unique IDs)
+
+### 8.2 Project Structure
+
+```
+apps/web-client/
+├── public/
+│   ├── fonts/
+│   ├── images/
+│   └── icons/
+├── src/
+│   ├── app/                    # Next.js App Router
+│   │   ├── (auth)/
+│   │   │   ├── login/
+│   │   │   └── register/
+│   │   ├── (dashboard)/
+│   │   │   ├── chat/
+│   │   │   └── settings/
+│   │   ├── layout.tsx
+│   │   └── page.tsx
+│   ├── components/
+│   │   ├── ui/                 # Base components
+│   │   │   ├── button.tsx
+│   │   │   ├── input.tsx
+│   │   │   ├── card.tsx
+│   │   │   └── ...
+│   │   ├── chat/               # Chat components
+│   │   │   ├── message-bubble.tsx
+│   │   │   ├── chat-input.tsx
+│   │   │   └── typing-indicator.tsx
+│   │   ├── layouts/
+│   │   │   ├── header.tsx
+│   │   │   ├── sidebar.tsx
+│   │   │   └── footer.tsx
+│   │   └── features/
+│   ├── hooks/
+│   │   ├── use-chat.ts
+│   │   ├── use-auth.ts
+│   │   └── use-theme.ts
+│   ├── lib/
+│   │   ├── api.ts
+│   │   ├── utils.ts
+│   │   └── constants.ts
+│   ├── stores/
+│   │   ├── auth-store.ts
+│   │   ├── chat-store.ts
+│   │   └── theme-store.ts
+│   ├── styles/
+│   │   ├── globals.css
+│   │   └── theme.css
+│   └── types/
+│       ├── api.ts
+│       └── models.ts
+├── .env.local
+├── next.config.js
+├── tailwind.config.js
+├── tsconfig.json
+└── package.json
+```
+
+### 8.3 Component Example
+
+**Button Component:**
+
+```typescript
+// components/ui/button.tsx
+import * as React from "react"
+import { Slot } from "@radix-ui/react-slot"
+import { cva, type VariantProps } from "class-variance-authority"
+import { cn } from "@/lib/utils"
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center rounded-md text-sm font-medium transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
+  {
+    variants: {
+      variant: {
+        primary: "bg-blue-600 text-white hover:bg-blue-700",
+        secondary: "bg-gray-600 text-white hover:bg-gray-700",
+        ghost: "hover:bg-gray-800 text-gray-300",
+        danger: "bg-red-600 text-white hover:bg-red-700",
+      },
+      size: {
+        xs: "h-7 px-3 text-xs",
+        sm: "h-8 px-4 text-sm",
+        md: "h-10 px-5 text-base",
+        lg: "h-12 px-6 text-lg",
+        xl: "h-14 px-7 text-xl",
+      },
+    },
+    defaultVariants: {
+      variant: "primary",
+      size: "md",
+    },
+  }
+)
+
+export interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  asChild?: boolean
+  loading?: boolean
+}
+
+const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ className, variant, size, asChild = false, loading, children, ...props }, ref) => {
+    const Comp = asChild ? Slot : "button"
+    return (
+      <Comp
+        className={cn(buttonVariants({ variant, size, className }))}
+        ref={ref}
+        disabled={loading || props.disabled}
+        {...props}
+      >
+        {loading && <Spinner className="mr-2" />}
+        {children}
+      </Comp>
+    )
+  }
+)
+Button.displayName = "Button"
+
+export { Button, buttonVariants }
+```
+
+**Usage:**
+
+```tsx
+<Button variant="primary" size="md">
+  Send Message
+</Button>
+
+<Button variant="ghost" size="sm" loading={isLoading}>
+  Loading...
+</Button>
+```
+
+## IX. Implementation Phases
+
+### Phase 1: Design System Setup (Week 1)
+
+- [ ] Initialize Tailwind with design tokens
+- [ ] Create CSS variables for colors, spacing, typography
+- [ ] Build base UI components (Button, Input, Card, etc.)
+- [ ] Setup theme switching (dark/light)
+- [ ] Create Storybook for component documentation
+
+### Phase 2: Web Client - Authentication (Week 2)
+
+- [ ] Login page with validation
+- [ ] Register page with password strength
+- [ ] Forgot password flow
+- [ ] OAuth integration (Google)
+- [ ] Auth state management with Zustand
+
+### Phase 3: Web Client - Chat Interface (Week 3-4)
+
+- [ ] Chat layout (sidebar + main + panel)
+- [ ] Message components (user/AI bubbles)
+- [ ] Chat input with auto-resize
+- [ ] Typing indicator
+- [ ] Conversation list with search
+- [ ] Message actions (copy, delete, regenerate)
+- [ ] WebSocket integration for real-time
+
+### Phase 4: Web Client - Settings & Profile (Week 5)
+
+- [ ] User profile page
+- [ ] Settings with tabs
+- [ ] Theme preferences
+- [ ] Security settings (2FA)
+- [ ] API keys management
+
+### Phase 5: Web Admin - Dashboard (Week 6-7)
+
+- [ ] Analytics dashboard layout
+- [ ] Metric cards with trends
+- [ ] Charts (line, bar, area)
+- [ ] Recent activity table
+- [ ] Real-time updates
+
+### Phase 6: Web Admin - User Management (Week 8)
+
+- [ ] User list with data table
+- [ ] Search, filter, sort functionality
+- [ ] User details modal
+- [ ] Edit user form
+- [ ] Bulk actions
+- [ ] Role management
+
+### Phase 7: Web Admin - System Settings (Week 9)
+
+- [ ] Settings navigation
+- [ ] General settings form
+- [ ] Email configuration
+- [ ] Security policies
+- [ ] API settings
+
+### Phase 8: Responsive & Accessibility (Week 10)
+
+- [ ] Mobile responsive design
+- [ ] Tablet optimizations
+- [ ] Keyboard navigation
+- [ ] Screen reader support
+- [ ] WCAG 2.1 AA compliance testing
+
+### Phase 9: Performance & Optimization (Week 11)
+
+- [ ] Code splitting
+- [ ] Image optimization
+- [ ] Lazy loading
+- [ ] Caching strategy
+- [ ] Lighthouse optimization (score 90+)
+
+### Phase 10: Testing & Polish (Week 12)
+
+- [ ] Unit tests (80%+ coverage)
+- [ ] E2E tests (critical flows)
+- [ ] Cross-browser testing
+- [ ] Performance testing
+- [ ] Bug fixes and polish
+
+## X. Design Resources & References
+
+### 10.1 Inspiration Sources
+
+- [x.ai Grok UI](https://grok.x.ai/) - Minimalistic, intuitive chat interface
+- [OpenAI ChatGPT](https://chat.openai.com/) - Industry-standard AI chat
+- [Claude.ai](https://claude.ai/) - Clean, professional design
+- [Vercel AI Chat](https://sdk.vercel.ai/) - Modern chat SDK examples
+- [Linear App](https://linear.app/) - Beautiful dark mode UI
+
+### 10.2 Design Tools
+
+- **Figma**: UI design and prototyping
+- **Storybook**: Component development and documentation
+- **Chromatic**: Visual regression testing
+- **Tailwind UI**: Premium component examples
+- **Shadcn UI**: High-quality component library
+
+### 10.3 Color Tools
+
+- **Coolors**: Color palette generation
+- **Contrast Checker**: WCAG compliance
+- **ColorBox**: Dark mode palette creation
+- **Palettte**: Color scheme explorer
+
+### 10.4 Typography Resources
+
+- **Fontsource**: Self-hosted fonts
+- **Modern Font Stacks**: System font combinations
+- **Type Scale**: Typography scale generator
+
+### 10.5 Icon Libraries
+
+- **Lucide React**: Modern icon set (recommended)
+- **Heroicons**: Tailwind's icon library
+- **Phosphor Icons**: Flexible icon family
+- **Feather Icons**: Minimalist icons
+
+## XI. Common Patterns & Best Practices
+
+### 11.1 Component Patterns
+
+**Compound Components:**
+
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Title</CardTitle>
+  </CardHeader>
+  <CardContent>Content</CardContent>
+</Card>
+```
+
+**Render Props:**
+
+```tsx
+<DataTable
+  data={users}
+  renderRow={(user) => (
+    <UserRow user={user} />
+  )}
+/>
+```
+
+**Controlled Components:**
+
+```tsx
+const [value, setValue] = useState("")
+<Input value={value} onChange={setValue} />
+```
+
+### 11.2 State Management Patterns
+
+**Zustand Store:**
+
+```typescript
+// stores/chat-store.ts
+import { create } from 'zustand'
+
+interface ChatState {
+  messages: Message[]
+  isTyping: boolean
+  addMessage: (message: Message) => void
+  setTyping: (typing: boolean) => void
+}
+
+export const useChatStore = create<ChatState>((set) => ({
+  messages: [],
+  isTyping: false,
+  addMessage: (message) =>
+    set((state) => ({ messages: [...state.messages, message] })),
+  setTyping: (typing) => set({ isTyping: typing }),
+}))
+```
+
+**Usage:**
+
+```tsx
+const { messages, addMessage } = useChatStore()
+```
+
+### 11.3 API Integration Pattern
+
+**React Query:**
+
+```typescript
+// hooks/use-chat.ts
+import { useQuery, useMutation } from '@tanstack/react-query'
+
+export function useMessages(conversationId: string) {
+  return useQuery({
+    queryKey: ['messages', conversationId],
+    queryFn: () => api.getMessages(conversationId),
+  })
+}
+
+export function useSendMessage() {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: api.sendMessage,
+    onSuccess: () => {
+      queryClient.invalidateQueries(['messages'])
+    },
+  })
+}
+```
+
+### 11.4 Error Handling
+
+**Error Boundary:**
+
+```tsx
+<ErrorBoundary fallback={<ErrorPage />}>
+  <App />
+</ErrorBoundary>
+```
+
+**Toast Notifications:**
+
+```tsx
+import { toast } from 'sonner'
+
+try {
+  await sendMessage(text)
+  toast.success('Message sent')
+} catch (error) {
+  toast.error('Failed to send message')
+}
+```
+
+## XII. Deployment Considerations
+
+### 12.1 Build Optimization
+
+**Next.js Config:**
+
+```javascript
+// next.config.js
+module.exports = {
+  images: {
+    domains: ['cdn.example.com'],
+    formats: ['image/webp', 'image/avif'],
+  },
+  compiler: {
+    removeConsole: process.env.NODE_ENV === 'production',
+  },
+  experimental: {
+    optimizeCss: true,
+  },
+}
+```
+
+### 12.2 Environment Variables
+
+```bash
+# .env.local (development)
+NEXT_PUBLIC_API_URL=http://localhost:5001/api/v1
+NEXT_PUBLIC_WS_URL=ws://localhost:5001
+NEXT_PUBLIC_ENV=development
+
+# .env.production
+NEXT_PUBLIC_API_URL=https://api.goodgo.vn/api/v1
+NEXT_PUBLIC_WS_URL=wss://api.goodgo.vn
+NEXT_PUBLIC_ENV=production
+```
+
+### 12.3 Performance Metrics
+
+**Target Lighthouse Scores:**
+
+- Performance: 90+
+- Accessibility: 95+
+- Best Practices: 95+
+- SEO: 100
+
+**Core Web Vitals:**
+
+- LCP (Largest Contentful Paint): < 2.5s
+- FID (First Input Delay): < 100ms
+- CLS (Cumulative Layout Shift): < 0.1
+
+---
+
+## Research Sources
+
+Based on research from:
+
+- [xAI UI & Management Console](https://cobusgreyling.medium.com/xai-ui-management-console-35500fa967fe)
+- [Grok UI Figma Community](https://www.figma.com/community/file/1514056350765003193/grok-ui)
+- [OpenAI Apps SDK UI](https://developers.openai.com/apps-sdk/build/chatgpt-ui/)
+- [OpenAI UI Guidelines](https://developers.openai.com/apps-sdk/concepts/ui-guidelines/)
+- [16 Chat UI Design Patterns](https://bricxlabs.com/blogs/message-screen-ui-deisgn)
+- [UI/UX Design Trends 2026](https://www.index.dev/blog/ui-ux-design-trends)
+- [Modern Web Experience Design](https://digitalhouse.ae/blog/ui-and-ux-design/)
+
+---
+
+**Document Version:** 1.0
+
+**Last Updated:** 2026-01-02
+
+**Status:** Ready for Implementation
\ No newline at end of file
diff --git a/services/iam-service/docs/ARCHITECTURE.en.md b/services/iam-service/docs/ARCHITECTURE.en.md
index 60fe60d5..803d796e 100644
--- a/services/iam-service/docs/ARCHITECTURE.en.md
+++ b/services/iam-service/docs/ARCHITECTURE.en.md
@@ -1,552 +1,1189 @@
-# Service Template Architecture
+# IAM Service Architecture
 
-This document describes the architecture of a single microservice built from this template and how it integrates with the GoodGo microservices platform.
+> **Enterprise-Grade Identity & Access Management Platform**
+>
+> This document describes the complete architecture of the IAM Service, including system components, data flows, security model, and integration patterns.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Overall Architecture](#overall-architecture)
+- [Authentication Flows](#authentication-flows)
+- [Authorization Model](#authorization-model)
+- [Caching Strategy](#caching-strategy)
+- [Module Dependencies](#module-dependencies)
+- [Data Architecture](#data-architecture)
+- [Security Architecture](#security-architecture)
+- [Observability](#observability)
+- [Deployment Architecture](#deployment-architecture)
+
+---
 
 ## Overview
 
-This template provides a complete, production-ready foundation for building individual microservices with:
+The IAM Service is a comprehensive Identity and Access Management platform providing:
 
-- **Security**: Authentication, authorization, input validation, and security headers
-- **Observability**: Comprehensive logging, metrics, tracing, and health checks
-- **Data Management**: Repository pattern, database migrations, and seeding
-- **API Documentation**: OpenAPI/Swagger documentation with interactive UI
-- **Error Handling**: Structured error responses with proper HTTP status codes
-- **Docker Support**: Multi-stage builds and production optimization
+### Core Capabilities
 
-**Important Context**: This template represents a **single microservice**. For platform-level deployment and orchestration, services are registered in `deployments/local/docker-compose.yml` and routed through the Traefik API Gateway configured in `infra/traefik/`.
+| Capability | Description | Modules |
+|------------|-------------|---------|
+| **Authentication** | User identity verification | Auth, Social, OIDC, MFA |
+| **Authorization** | Access control and permissions | RBAC, ABAC, Policy Engine |
+| **Identity Management** | User lifecycle and profiles | Users, Profiles, Organizations, Groups |
+| **Access Governance** | Request workflows and reviews | Requests, Reviews, Analytics |
+| **Compliance** | Regulatory compliance reporting | GDPR, SOC2, ISO27001, Risk Management |
+| **Security** | Zero-trust and threat protection | Zero-Trust, Audit, Encryption |
+| **Performance** | High-speed access with caching | Multi-layer Cache, Connection Pool |
+
+### Key Metrics
+
+- **50+ API Endpoints** across 10 feature modules
+- **30+ Database Models** with comprehensive relationships
+- **7 Authentication Methods** (password, social x3, OIDC, MFA x2)
+- **Multi-layer Caching** (Memory → Redis → PostgreSQL)
+- **Zero-Trust Security** with device fingerprinting
+- **Enterprise Compliance** (GDPR, SOC2, ISO27001, HIPAA)
 
 ---
 
-# Part 1: Single Service Architecture (Internal)
+## Overall Architecture
 
-This section describes the internal architecture of a single microservice built from this template.
+The IAM Service follows a layered architecture pattern with clear separation of concerns:
 
-## Internal Service Components
+```mermaid
+graph TB
+    subgraph "Client Layer"
+        WebApp[Web Application<br/>React/Vue/Angular]
+        MobileApp[Mobile App<br/>iOS/Android/React Native]
+        Service[Other Microservices<br/>Product/Order/Payment]
+    end
+
+    subgraph "API Gateway"
+        Traefik[Traefik Gateway<br/>Load Balancer + Routing<br/>Port 80/443]
+    end
+
+    subgraph "IAM Service - Port 3001"
+        subgraph "Middleware Stack"
+            Correlation[Correlation ID<br/>Request Tracking]
+            Logger[Request Logger<br/>Winston]
+            ZeroTrust[Zero-Trust Validator<br/>Device + Location + Behavior]
+            RateLimit[Dynamic Rate Limiter<br/>Redis-backed<br/>50-1000 req/15min]
+            Auth[Authentication<br/>JWT Verification]
+            RBAC[Authorization<br/>RBAC + ABAC]
+        end
+
+        subgraph "Core Authentication Modules"
+            AuthModule[Auth Module<br/>Login/Register/Logout]
+            TokenModule[Token Module<br/>JWT + Cookie Management]
+            SessionModule[Session Module<br/>Device Fingerprinting]
+            SocialModule[Social Auth<br/>Google/FB/GitHub]
+            OIDCModule[OIDC Provider<br/>OpenID Connect]
+            MFAModule[MFA Module<br/>TOTP/WebAuthn]
+            RBACModule[RBAC Module<br/>Roles + Permissions]
+        end
+
+        subgraph "Identity Management Modules"
+            UserModule[User Lifecycle<br/>CRUD + Bulk Ops]
+            ProfileModule[Profile Management<br/>Avatar + Custom Fields]
+            VerificationModule[Identity Verification<br/>Email/Phone/Document]
+            OrgModule[Organizations<br/>Multi-tenant Hierarchy]
+            GroupModule[Groups<br/>Group-based Access]
+        end
+
+        subgraph "Access Management Modules"
+            RequestModule[Access Requests<br/>Approval Workflows]
+            ReviewModule[Access Reviews<br/>Certification Campaigns]
+            AnalyticsModule[Access Analytics<br/>Usage + Risk Analysis]
+        end
+
+        subgraph "Governance Modules"
+            ComplianceModule[Compliance<br/>GDPR/SOC2/ISO27001]
+            PolicyModule[Policy Governance<br/>Templates + Versioning]
+            RiskModule[Risk Management<br/>Scoring + Detection]
+            ReportingModule[Reporting<br/>Dashboards + Exports]
+        end
+
+        subgraph "Core Services"
+            CacheService[Multi-layer Cache<br/>Memory → Redis<br/>TTL: 60s-15min]
+            AuditService[Audit Logging<br/>Event Sourcing<br/>AuthEvent Model]
+            SecurityService[Security Services<br/>Encryption + Hashing]
+        end
+    end
+
+    subgraph "Data Layer"
+        PostgreSQL[(PostgreSQL 14+<br/>Primary Database<br/>Connection Pool<br/>30+ Models)]
+        Redis[(Redis 6+<br/>Cache + Sessions<br/>Rate Limits + Locks)]
+    end
+
+    subgraph "External Services (Future)"
+        EmailService[Email Service<br/>Verification + Notifications]
+        SMSService[SMS Service<br/>OTP + Phone Verification]
+        FileStorage[File Storage<br/>S3/GCS for Avatars]
+    end
+
+    subgraph "Observability Stack"
+        Prometheus[Prometheus<br/>Metrics Collection]
+        Jaeger[Jaeger<br/>Distributed Tracing]
+        Logs[Structured Logs<br/>Winston + Loki]
+    end
+
+    %% Client to Gateway
+    WebApp --> Traefik
+    MobileApp --> Traefik
+    Service --> Traefik
+
+    %% Gateway to Middleware
+    Traefik --> Correlation
+    Correlation --> Logger
+    Logger --> ZeroTrust
+    ZeroTrust --> RateLimit
+    RateLimit --> Auth
+    Auth --> RBAC
+
+    %% Middleware to Modules
+    RBAC --> AuthModule
+    RBAC --> UserModule
+    RBAC --> RequestModule
+    RBAC --> ComplianceModule
+
+    %% Module Dependencies
+    AuthModule --> TokenModule
+    AuthModule --> SessionModule
+    AuthModule --> SocialModule
+    AuthModule --> OIDCModule
+    AuthModule --> MFAModule
+    AuthModule --> RBACModule
+
+    UserModule --> ProfileModule
+    UserModule --> VerificationModule
+    UserModule --> OrgModule
+    UserModule --> GroupModule
+
+    RequestModule --> ReviewModule
+    RequestModule --> AnalyticsModule
+
+    ComplianceModule --> PolicyModule
+    ComplianceModule --> RiskModule
+    ComplianceModule --> ReportingModule
+
+    %% Core Services
+    AuthModule --> CacheService
+    UserModule --> CacheService
+    RBACModule --> CacheService
+
+    AuthModule --> AuditService
+    RequestModule --> AuditService
+    ComplianceModule --> AuditService
+
+    AuthModule --> SecurityService
+
+    %% Data Layer
+    CacheService --> Redis
+    CacheService --> PostgreSQL
+
+    AuthModule --> PostgreSQL
+    UserModule --> PostgreSQL
+    RequestModule --> PostgreSQL
+    ComplianceModule --> PostgreSQL
+
+    %% External Services (dashed - not yet integrated)
+    VerificationModule -.-> EmailService
+    VerificationModule -.-> SMSService
+    ProfileModule -.-> FileStorage
+
+    %% Observability
+    AuthModule -.-> Prometheus
+    UserModule -.-> Prometheus
+    RequestModule -.-> Prometheus
+    ComplianceModule -.-> Prometheus
+
+    CacheService -.-> Jaeger
+    AuditService -.-> Logs
+
+    style ZeroTrust fill:#ff9999
+    style CacheService fill:#99ccff
+    style PostgreSQL fill:#cc99ff
+    style Redis fill:#ffcc99
+    style AuditService fill:#99ff99
+```
+
+### Architecture Highlights
+
+1. **Layered Middleware**: Every request passes through 6 middleware layers (correlation, logging, zero-trust, rate limiting, authentication, authorization)
+2. **Modular Design**: 10 independent feature modules with clear boundaries
+3. **Multi-layer Caching**: Memory (60s) → Redis (5-15min) → PostgreSQL for optimal performance
+4. **Event Sourcing**: All authentication and authorization events logged for audit compliance
+5. **Zero-Trust Security**: Continuous validation of device, location, and behavior
+6. **Dynamic Rate Limiting**: Role-based limits (50-1000 req/15min)
+
+---
+
+## Authentication Flows
+
+### Password-Based Authentication
+
+Standard email/password authentication with bcrypt hashing and JWT token generation:
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Middleware
+    participant AuthService
+    participant RBACService
+    participant Database
+    participant Redis
+    participant AuditService
+
+    Client->>Middleware: POST /api/v1/auth/login<br/>{email, password}
+
+    Middleware->>Middleware: 1. Correlation ID
+    Middleware->>Middleware: 2. Zero-Trust Validation<br/>(Device + IP + Behavior)
+    Middleware->>Middleware: 3. Rate Limit Check<br/>(5 login/15min)
+
+    Middleware->>AuthService: login(email, password)
+
+    AuthService->>Database: Find user by email
+    Database-->>AuthService: User record
+
+    AuthService->>AuthService: Verify password<br/>(bcrypt compare, cost=12)
+
+    alt Password Invalid
+        AuthService->>AuditService: Log LOGIN_FAILED event
+        AuditService->>Database: Save AuthEvent
+        AuthService-->>Client: 401 Unauthorized<br/>"Invalid credentials"
+    else Password Valid & MFA Disabled
+        AuthService->>RBACService: Get user roles + permissions
+        RBACService->>Database: Query UserRole, UserPermission
+        Database-->>RBACService: Roles + Permissions
+        RBACService-->>AuthService: ["ADMIN"], ["users:read:all"]
+
+        AuthService->>AuthService: Generate JWT tokens<br/>Access: 15min<br/>Refresh: 7 days
+
+        AuthService->>Database: Save refresh token
+        AuthService->>Redis: Cache user data<br/>TTL: 15min
+        AuthService->>Redis: Cache permissions<br/>TTL: 5min
+        AuthService->>Database: Create session<br/>(device fingerprint)
+
+        AuthService->>Database: Update lastLoginAt, loginCount
+        AuthService->>AuditService: Log LOGIN_SUCCESS event
+
+        AuthService-->>Client: 200 OK<br/>{user, tokens}<br/>Set-Cookie: refresh_token
+    else Password Valid & MFA Enabled
+        AuthService-->>Client: 200 OK<br/>{mfaRequired: true}
+        Note over Client: Prompt for MFA code
+        Client->>Middleware: POST /api/v1/mfa/verify<br/>{token: "123456"}
+        Note over Middleware,AuthService: MFA verification flow...
+    end
+```
+
+**Key Security Features:**
+- Bcrypt password hashing (cost factor 12 in production)
+- Token family tracking for rotation security
+- Device fingerprinting for session management
+- Zero-trust validation before authentication
+- Comprehensive audit logging
+
+### Social Authentication Flow
+
+OAuth 2.0 integration with Google, Facebook, and GitHub:
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant IAM
+    participant Google as Google OAuth
+    participant Database
+    participant Redis
+
+    Client->>IAM: GET /api/v1/auth/social/google
+    IAM->>IAM: Generate state token<br/>(CSRF protection)
+    IAM->>Redis: Store state token<br/>TTL: 10min
+    IAM-->>Client: 302 Redirect to Google<br/>with state param
+
+    Client->>Google: OAuth consent screen
+    Google-->>Client: Authorization code + state
+
+    Client->>IAM: GET /api/v1/auth/social/google/callback<br/>?code=xxx&state=yyy
+
+    IAM->>Redis: Verify state token
+    alt State Invalid
+        IAM-->>Client: 401 CSRF token invalid
+    else State Valid
+        IAM->>Google: Exchange code for tokens
+        Google-->>IAM: Access token + User profile
+
+        IAM->>Database: Find or create user<br/>by provider + providerId
+
+        alt User Found
+            IAM->>Database: Update social account tokens
+        else New User
+            IAM->>Database: Create user + social account
+            IAM->>Database: Assign default role (USER)
+        end
+
+        IAM->>IAM: Generate IAM JWT tokens
+        IAM->>Redis: Cache user + permissions
+        IAM->>Database: Create session
+
+        IAM-->>Client: 302 Redirect to app<br/>with tokens in URL/cookie
+    end
+```
+
+**Supported Providers:**
+- Google OAuth 2.0
+- Facebook OAuth
+- GitHub OAuth
+- Apple Sign-In (future)
+- Microsoft OAuth (future)
+
+### MFA (Multi-Factor Authentication) Flow
+
+TOTP-based two-factor authentication using authenticator apps:
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant IAM
+    participant Authenticator as Authenticator App
+    participant Database
+
+    Note over Client,Database: MFA Enrollment Phase
+
+    Client->>IAM: POST /api/v1/mfa/totp/enable
+    Note over Client: User must be authenticated
+
+    IAM->>IAM: Generate TOTP secret (32 chars)
+    IAM->>IAM: Generate QR code<br/>(otpauth://totp/...)
+    IAM-->>Client: {secret, qrCode, backupCodes}
+
+    Client->>Authenticator: Scan QR code
+    Authenticator-->>Client: Display 6-digit TOTP
+
+    Client->>IAM: POST /api/v1/mfa/totp/verify<br/>{token: "123456"}
+
+    IAM->>IAM: Verify TOTP token<br/>(30s window, ±1 interval)
+
+    alt Token Valid
+        IAM->>Database: Create MFADevice record<br/>(type: TOTP, secret: encrypted)
+        IAM->>Database: Update user.mfaEnabled = true
+        IAM-->>Client: 200 OK MFA enabled
+    else Token Invalid
+        IAM-->>Client: 401 Invalid TOTP token
+    end
+
+    Note over Client,Database: MFA Login Phase
+
+    Client->>IAM: POST /api/v1/auth/login<br/>{email, password}
+    IAM->>Database: Verify credentials
+
+    alt MFA Required
+        IAM-->>Client: 200 OK {mfaRequired: true}
+
+        Client->>Authenticator: Get current TOTP
+        Authenticator-->>Client: Current 6-digit code
+
+        Client->>IAM: POST /api/v1/mfa/totp/validate<br/>{userId, token}
+
+        IAM->>Database: Get MFADevice for user
+        IAM->>IAM: Verify TOTP token
+
+        alt Token Valid
+            IAM->>IAM: Generate full JWT tokens
+            IAM->>Database: Create session
+            IAM->>Database: Update device.lastUsedAt
+            IAM-->>Client: 200 OK {user, tokens}
+        else Token Invalid
+            IAM-->>Client: 401 Invalid MFA token
+        end
+    end
+```
+
+**MFA Features:**
+- TOTP (Time-based One-Time Password) via authenticator apps
+- QR code generation for easy enrollment
+- Backup codes for account recovery
+- Multiple MFA devices per user
+- WebAuthn/FIDO2 framework (future implementation)
+
+---
+
+## Authorization Model
+
+The IAM Service implements a hybrid authorization model combining RBAC (Role-Based Access Control) and ABAC (Attribute-Based Access Control):
+
+### Authorization Decision Flow
+
+```mermaid
+flowchart TD
+    Start[Request to Protected Resource] --> Auth{Authenticated?}
+
+    Auth -->|No| Deny401[401 Unauthorized<br/>Authentication required]
+    Auth -->|Yes| Cache{Permission<br/>in Cache?}
+
+    Cache -->|Hit| CacheValue{Cache<br/>Value?}
+    CacheValue -->|Allow| Allow[Access Granted]
+    CacheValue -->|Deny| Deny403Cache[403 Forbidden<br/>Cached denial]
+
+    Cache -->|Miss| LoadPerms[Load Permissions<br/>from Database]
+
+    LoadPerms --> DirectPerms{Has Direct<br/>User Permission?}
+
+    DirectPerms -->|Explicit Deny| Deny403A[403 Forbidden<br/>Explicit permission denial]
+    DirectPerms -->|Explicit Allow| Allow
+    DirectPerms -->|None| RolePerms{Has Role<br/>Permission?}
+
+    RolePerms -->|Yes| CheckExpiry{Role<br/>Expired?}
+    RolePerms -->|No| GroupPerms{Has Group<br/>Permission?}
+
+    CheckExpiry -->|Yes| GroupPerms
+    CheckExpiry -->|No| Allow
+
+    GroupPerms -->|Yes| Allow
+    GroupPerms -->|No| ABACCheck{ABAC Policy<br/>Exists?}
+
+    ABACCheck -->|No Policies| DefaultDeny[403 Forbidden<br/>Default deny - No permissions]
+    ABACCheck -->|Has Policies| EvaluatePolicies[Evaluate Policies<br/>by Priority]
+
+    EvaluatePolicies --> EvalConditions{Policy<br/>Conditions?}
+
+    EvalConditions -->|Time-based| CheckTime{Current time<br/>in range?}
+    EvalConditions -->|Location-based| CheckLocation{IP in<br/>allowed range?}
+    EvalConditions -->|Attribute-based| CheckAttrs{Attributes<br/>match?}
+
+    CheckTime -->|Yes| PolicyEffect{Policy<br/>Effect?}
+    CheckTime -->|No| NextPolicy{More<br/>Policies?}
+
+    CheckLocation -->|Yes| PolicyEffect
+    CheckLocation -->|No| NextPolicy
+
+    CheckAttrs -->|Yes| PolicyEffect
+    CheckAttrs -->|No| NextPolicy
+
+    PolicyEffect -->|ALLOW| Allow
+    PolicyEffect -->|DENY| Deny403Policy[403 Forbidden<br/>Policy denial]
+
+    NextPolicy -->|Yes| EvaluatePolicies
+    NextPolicy -->|No| DefaultDeny
+
+    Allow --> CacheResult[Cache Result<br/>TTL: 5min]
+    CacheResult --> AuditLog[Log Access Event<br/>to AuthEvent]
+    AuditLog --> Success[200 OK<br/>Process request]
+
+    style Auth fill:#e1f5fe
+    style DirectPerms fill:#fff3e0
+    style RolePerms fill:#f3e5f5
+    style GroupPerms fill:#e8f5e9
+    style ABACCheck fill:#fce4ec
+    style Allow fill:#c8e6c9
+    style Deny401 fill:#ffcdd2
+    style Deny403A fill:#ffcdd2
+    style Deny403Cache fill:#ffcdd2
+    style Deny403Policy fill:#ffcdd2
+    style DefaultDeny fill:#ffcdd2
+```
+
+### Permission Model
+
+The IAM Service uses a hierarchical permission model:
+
+**Permission Format**: `resource:action:scope`
+
+- **Resource**: The entity being accessed (e.g., `users`, `products`, `orders`)
+- **Action**: The operation being performed (e.g., `read`, `create`, `update`, `delete`)
+- **Scope**: The access boundary (e.g., `own`, `team`, `all`)
+
+**Examples**:
+- `users:read:all` - Read all users
+- `users:update:own` - Update own user profile
+- `products:create:team` - Create products for team
+- `orders:delete:all` - Delete any order (admin)
+
+### Authorization Hierarchy
+
+```
+1. Direct User Permissions (HIGHEST PRIORITY)
+   ↓ (if not found or not denied)
+2. Role Permissions
+   ↓ (if not found)
+3. Group Permissions
+   ↓ (if not found)
+4. ABAC Policies (evaluated by priority)
+   ↓ (if no policies match)
+5. Default Deny (LOWEST PRIORITY)
+```
+
+### RBAC (Role-Based Access Control)
+
+```mermaid
+graph LR
+    User[User] --> UserRole1[UserRole]
+    User --> UserRole2[UserRole]
+    User --> UserPerm[UserPermission<br/>Direct Override]
+
+    UserRole1 --> Role1[ADMIN Role]
+    UserRole2 --> Role2[MANAGER Role]
+
+    Role1 --> RolePerm1[RolePermission]
+    Role1 --> RolePerm2[RolePermission]
+    Role2 --> RolePerm3[RolePermission]
+
+    RolePerm1 --> Perm1[users:*:all]
+    RolePerm2 --> Perm2[products:*:all]
+    RolePerm3 --> Perm3[orders:read:team]
+
+    UserPerm --> Perm4[analytics:read:all]
+
+    Group[Group] --> GroupMember[GroupMember]
+    GroupMember --> User
+    Group --> GroupPerm[GroupPermission]
+    GroupPerm --> Perm5[reports:read:all]
+
+    style User fill:#e1f5fe
+    style Role1 fill:#f3e5f5
+    style Role2 fill:#f3e5f5
+    style Group fill:#e8f5e9
+    style Perm1 fill:#fff3e0
+    style Perm2 fill:#fff3e0
+    style Perm3 fill:#fff3e0
+    style Perm4 fill:#ffccbc
+    style Perm5 fill:#c8e6c9
+```
+
+**Features:**
+- Multiple roles per user
+- Temporary role assignments with expiration
+- Direct user permissions (can override roles)
+- Group-based permissions
+- Permission caching (5 minutes TTL)
+
+### ABAC (Attribute-Based Access Control)
 
 ```mermaid
 graph TD
-    Request[HTTP Request] -->|From Traefik| Middleware[Middleware Chain]
-    
-    subgraph SingleService[Single Service Boundary]
-        Middleware --> Correlation[Correlation ID Middleware]
-        Correlation --> Auth[Authentication Middleware]
-        Auth --> Validation[Validation Middleware]
-        Validation --> Error[Error Handler]
-        Error --> Logger[Request Logger]
-        Logger --> Metrics[Metrics Collector]
-        
-        Metrics --> Router[Router Layer]
-        Router --> Controller[Controller Layer]
-        Controller --> Service[Service Layer]
-        Service --> Repository[Repository Layer]
-        
-        Repository --> Database[(PostgreSQL)]
-        Service --> Cache[(Redis)]
-        
-        Service -.->|Health Status| Health[Health Checks]
-        Service -.->|API Docs| OpenAPI[OpenAPI/Swagger]
-    end
-    
-    Service -.->|Metrics| Prometheus[Prometheus]
-    Service -.->|Traces| Jaeger[Jaeger]
-    
-    style Correlation fill:#e1f5fe
-    style Auth fill:#f3e5f5
-    style Validation fill:#e8f5e8
-    style Error fill:#fff3e0
-    style Logger fill:#f3e5f5
-    style Metrics fill:#e8f5e8
+    Request[Access Request] --> PolicyEngine[Policy Engine]
+
+    PolicyEngine --> LoadPolicies[Load Policies<br/>for Resource]
+    LoadPolicies --> SortPolicies[Sort by Priority<br/>Descending]
+
+    SortPolicies --> EvaluatePolicy[Evaluate Policy<br/>Conditions]
+
+    EvaluatePolicy --> TimeCondition{Time-based<br/>Condition?}
+    EvaluatePolicy --> LocationCondition{Location-based<br/>Condition?}
+    EvaluatePolicy --> AttributeCondition{Attribute-based<br/>Condition?}
+
+    TimeCondition --> CheckTime[Check current time<br/>vs allowed hours]
+    LocationCondition --> CheckIP[Check IP address<br/>vs allowed ranges]
+    AttributeCondition --> CheckAttrs[Check user attributes<br/>vs required values]
+
+    CheckTime --> ConditionMet{All Conditions<br/>Met?}
+    CheckIP --> ConditionMet
+    CheckAttrs --> ConditionMet
+
+    ConditionMet -->|Yes| ApplyEffect{Policy<br/>Effect?}
+    ConditionMet -->|No| NextPolicy{More<br/>Policies?}
+
+    ApplyEffect -->|ALLOW| Allow[Access Granted]
+    ApplyEffect -->|DENY| Deny[Access Denied]
+
+    NextPolicy -->|Yes| EvaluatePolicy
+    NextPolicy -->|No| DefaultDeny[Default Deny]
+
+    style PolicyEngine fill:#f3e5f5
+    style ConditionMet fill:#fff3e0
+    style Allow fill:#c8e6c9
+    style Deny fill:#ffcdd2
+    style DefaultDeny fill:#ffcdd2
 ```
 
-## Layer Architecture
-
-### Middleware Chain
-
-The middleware chain processes every incoming request in order:
-
-1. **Correlation Middleware**: Generates/propagates correlation and request IDs
-2. **Authentication Middleware**: Validates JWT tokens (optional for public routes)
-3. **Validation Middleware**: Sanitizes and validates input data with Zod schemas
-4. **Error Handler**: Catches and formats errors into structured responses
-5. **Logger Middleware**: Logs request/response with correlation IDs
-6. **Metrics Middleware**: Collects Prometheus metrics (duration, status, payload size)
-
-### Controller Layer
-
-- Handles HTTP requests and responses
-- Orchestrates service layer calls
-- Formats API responses
-- Wraps async handlers for error propagation
-
-### Service Layer
-
-- Contains pure business logic
-- Independent of HTTP transport
-- Orchestrates repository calls
-- Implements caching strategies
-- Throws domain-specific errors
-
-### Repository Layer
-
-- Abstracts database operations
-- Uses Prisma ORM for type-safe queries
-- Implements repository pattern
-- Provides consistent error handling
-- Supports transactions
-
-## Request Flow
-
-1.  **Request Entry**:
-    - Client sends HTTP request to ingress/load balancer
-    - Request includes optional correlation ID header (`x-correlation-id`)
-
-2.  **Correlation Middleware**:
-    - Generates or propagates correlation ID for request tracing
-    - Adds request ID for unique request identification
-    - Sets correlation headers on response
-
-3.  **Security Middleware**:
-    - **Authentication**: Validates JWT tokens (optional for public routes)
-    - **Authorization**: Checks user roles and permissions
-    - **Rate Limiting**: Prevents abuse with Redis-backed rate limiting
-    - **Helmet**: Secures HTTP headers
-
-4.  **Validation Middleware**:
-    - Sanitizes input data (trimming, normalization)
-    - Validates request data using Zod schemas
-    - Returns structured validation errors
-
-5.  **Router & Controller**:
-    - Routes request to appropriate controller
-    - Controller orchestrates business logic execution
-    - Input validation and response formatting
-
-6.  **Service Layer**:
-    - Contains pure business logic
-    - Independent of HTTP transport layer
-    - Orchestrates data access and external service calls
-
-7.  **Repository Layer**:
-    - Implements repository pattern for data access
-    - Abstracts database operations with Prisma ORM
-    - Provides consistent error handling
-
-8.  **Response & Observability**:
-    - Formats structured JSON responses
-    - Records comprehensive metrics (duration, errors, payload sizes)
-    - Logs with correlation IDs for distributed tracing
-    - Sends traces to Jaeger if enabled
-
-## Architecture Patterns
-
-### Repository Pattern
-
-```typescript
-// Base repository with common CRUD operations
-class BaseRepository<T, CreateInput, UpdateInput> {
-  async findById(id: string): Promise<T | null>
-  async create(data: CreateInput): Promise<T>
-  async update(id: string, data: UpdateInput): Promise<T>
-  // ... more common methods
-}
-
-// Specific repository extends base
-class FeatureRepository extends BaseRepository<Feature, CreateFeatureInput, UpdateFeatureInput> {
-  async findByName(name: string): Promise<Feature | null>
-  async findByTags(tags: string[]): Promise<Feature[]>
-  // ... feature-specific methods
-}
-```
-
-### Middleware Chain
-
-```typescript
-// Request processing pipeline
-app.use(correlationMiddleware());        // Add correlation IDs
-app.use(authenticate());                 // JWT validation
-app.use(authorize('admin'));             // Role checking
-app.use(validateDto(schema));            // Input validation
-app.use(errorHandler);                   // Error handling
-```
-
-### Error Handling
-
-```typescript
-// Custom error classes
-class NotFoundError extends HttpError {
-  constructor(resource: string) {
-    super(`${resource} not found`, 404, 'NOT_FOUND');
-  }
-}
-
-// Usage in services
-if (!feature) {
-  throw new NotFoundError('Feature');
-}
-```
-
-### Dependency Injection
-
-```typescript
-// Constructor injection for testability
-export class FeatureService {
-  constructor(private repository: IRepository<Feature>) {}
-
-  async create(data: CreateFeatureInput): Promise<Feature> {
-    return this.repository.create(data);
-  }
-}
-```
-
-## Best Practices
-
-### Code Organization
-
-- **Separation of Concerns**: Clear boundaries between layers (Controller → Service → Repository)
-- **Single Responsibility**: Each class/method has one clear purpose
-- **Dependency Injection**: Constructor injection for better testability
-- **Error Boundaries**: Proper error handling at each layer
-
-### Security
-
-- **Input Validation**: All inputs validated with Zod schemas
-- **Authentication**: JWT tokens with proper expiration
-- **Authorization**: Role-based access control (RBAC)
-- **Rate Limiting**: Distributed rate limiting with Redis
-- **Security Headers**: Helmet.js for HTTP security headers
-
-### Observability
-
-- **Structured Logging**: Consistent log format with correlation IDs
-- **Metrics**: Comprehensive Prometheus metrics
-- **Tracing**: Distributed tracing with Jaeger
-- **Health Checks**: Liveness and readiness probes
-- **Correlation IDs**: Request tracing across service boundaries
-
-### Error Handling
-
-- **Custom Error Classes**: Specific error types for different scenarios
-- **HTTP Status Mapping**: Proper status codes for different error types
-- **Structured Responses**: Consistent error response format
-- **Operational Errors**: Clear distinction between programming and operational errors
-
-### Testing
-
-- **Unit Tests**: Test individual functions and classes
-- **Integration Tests**: Test component interactions
-- **E2E Tests**: Test complete request/response cycles
-- **Test Utilities**: Shared test helpers and mocks
-- **Coverage Goals**: >70% code coverage target
-
-### Docker & Deployment
-
-- **Multi-stage Builds**: Optimized for production image size
-- **Security**: Non-root users, minimal attack surface
-- **Health Checks**: Container health monitoring
-- **Compose Files**: Development, testing, and production configurations
-- **Resource Limits**: Proper CPU and memory constraints
-
-## Configuration Management
-
-### Environment Variables
-
-- **Typed Configuration**: Zod schemas for env validation
-- **Default Values**: Sensible defaults for development
-- **Override Support**: `.env.local` overrides `.env`
-- **Documentation**: Comprehensive env variable documentation
-
-### Feature Flags
-
-- **Runtime Configuration**: Database-backed feature flags
-- **Admin Control**: Admin API for feature management
-- **Gradual Rollout**: Enable/disable features without deployment
-- **Audit Trail**: Track feature flag changes
-
-## API Design
-
-### RESTful Conventions
-
-- **Resource Naming**: Plural nouns for resource endpoints
-- **HTTP Methods**: GET, POST, PUT, DELETE, PATCH appropriately
-- **Status Codes**: Proper HTTP status codes for all responses
-- **Content Negotiation**: JSON responses with proper content-type
-
-### Response Format
-
+**Policy Example (JSON Logic)**:
 ```json
 {
-  "success": true,
-  "data": { ... },
-  "message": "Operation completed successfully",
-  "timestamp": "2024-01-01T00:00:00.000Z"
-}
-```
-
-### Error Responses
-
-```json
-{
-  "success": false,
-  "error": {
-    "code": "VALIDATION_ERROR",
-    "message": "Validation failed",
-    "details": [...]
+  "name": "Business Hours Only",
+  "resource": "sensitive_data",
+  "condition": {
+    "and": [
+      {
+        ">=": [{"var": "hour"}, 9]
+      },
+      {
+        "<=": [{"var": "hour"}, 17]
+      },
+      {
+        "in": [{"var": "day"}, [1, 2, 3, 4, 5]]
+      }
+    ]
   },
-  "timestamp": "2024-01-01T00:00:00.000Z"
+  "effect": "ALLOW",
+  "priority": 100
 }
 ```
 
-## Development Workflow
+---
+
+## Caching Strategy
+
+The IAM Service implements a multi-layer caching strategy for optimal performance:
+
+```mermaid
+graph TB
+    Request[Incoming Request] --> CheckL1{L1 Cache<br/>Node.js Memory}
+
+    CheckL1 -->|Cache Hit| L1Hit[Fast Response<br/>< 1ms latency]
+    CheckL1 -->|Cache Miss| CheckL2{L2 Cache<br/>Redis}
+
+    CheckL2 -->|Cache Hit| L2Hit[Medium Response<br/>< 10ms latency]
+    CheckL2 -->|Cache Miss| Database[(PostgreSQL<br/>Source of Truth)]
+
+    Database --> UpdateL2[Update L2 Cache<br/>Write to Redis]
+    UpdateL2 --> UpdateL1[Update L1 Cache<br/>Write to Memory]
+
+    UpdateL1 --> Response[Return Response]
+    L2Hit --> UpdateL1
+    L1Hit --> Response
+
+    subgraph "Cache Layers"
+        L1Cache[L1: In-Memory Cache<br/>node-cache<br/>TTL: 60 seconds<br/>Hot data only]
+        L2Cache[L2: Redis Cache<br/>ioredis<br/>TTL: 5-15 minutes<br/>Distributed]
+        DBLayer[L3: PostgreSQL<br/>Prisma ORM<br/>Source of truth<br/>Persistent]
+    end
+
+    subgraph "Cached Data Types"
+        UserData[User Data<br/>TTL: 15min]
+        Permissions[Permissions<br/>TTL: 5min]
+        Tokens[Token Validation<br/>TTL: Token lifetime]
+        Sessions[Sessions<br/>TTL: Session lifetime]
+        Roles[User Roles<br/>TTL: 5min]
+    end
+
+    style L1Hit fill:#90EE90
+    style L2Hit fill:#87CEEB
+    style Database fill:#FFB6C1
+    style L1Cache fill:#c8e6c9
+    style L2Cache fill:#bbdefb
+    style DBLayer fill:#f8bbd0
+```
+
+### Cache Configuration
+
+| Data Type | L1 TTL | L2 TTL | Invalidation Strategy |
+|-----------|--------|--------|----------------------|
+| User Data | 60s | 15min | On update/delete |
+| Permissions | 60s | 5min | On role/permission change |
+| User Roles | 60s | 5min | On role assignment/revocation |
+| Token Validation | N/A | Token lifetime | On logout/revocation |
+| Sessions | N/A | Session lifetime | On logout |
+| Rate Limit Counters | N/A | 15min window | Time-based expiry |
+
+### Cache Invalidation
+
+```typescript
+// Example: Invalidate user caches when permissions change
+await rbacService.grantPermission(userId, permissionId);
+
+// Automatically invalidates:
+// - cacheService.keys.userPermissions(userId)
+// - cacheService.keys.userRoles(userId)
+```
+
+---
+
+## Module Dependencies
+
+The IAM Service is organized into 10 feature modules with clear dependencies:
+
+```mermaid
+graph TD
+    subgraph "Presentation Layer"
+        Routes[Routes/Controllers<br/>50+ Endpoints]
+    end
+
+    subgraph "Business Logic Layer"
+        subgraph "Core Auth"
+            AuthModule[Auth Module<br/>Login/Register/Logout]
+            TokenModule[Token Module<br/>JWT + Cookies]
+            SessionModule[Session Module<br/>Device Tracking]
+        end
+
+        subgraph "Extended Auth"
+            RBACModule[RBAC Module<br/>Roles + Permissions]
+            SocialModule[Social Auth<br/>Google/FB/GitHub]
+            OIDCModule[OIDC Module<br/>Provider + Client]
+            MFAModule[MFA Module<br/>TOTP/WebAuthn]
+        end
+
+        subgraph "Identity"
+            IdentityModule[Identity Module<br/>Users + Profiles]
+            OrgModule[Organization Module<br/>Multi-tenancy]
+            GroupModule[Group Module<br/>Group Permissions]
+        end
+
+        subgraph "Access Governance"
+            AccessModule[Access Module<br/>Requests + Reviews]
+            AnalyticsModule[Analytics Module<br/>Usage Analysis]
+        end
+
+        subgraph "Compliance"
+            GovernanceModule[Governance Module<br/>Compliance + Risk]
+        end
+    end
+
+    subgraph "Core Services Layer"
+        CacheService[Cache Service<br/>Multi-layer]
+        AuditService[Audit Service<br/>Event Sourcing]
+        SecurityService[Security Service<br/>Encryption]
+        FeatureService[Feature Flags<br/>Runtime Config]
+    end
+
+    subgraph "Data Access Layer"
+        Repositories[Repositories<br/>Data Access<br/>Prisma ORM]
+    end
+
+    subgraph "Infrastructure"
+        Database[(PostgreSQL<br/>30+ Models)]
+        Redis[(Redis<br/>Cache + Locks)]
+    end
+
+    %% Routes to Modules
+    Routes --> AuthModule
+    Routes --> IdentityModule
+    Routes --> AccessModule
+    Routes --> GovernanceModule
+
+    %% Core Auth Dependencies
+    AuthModule --> TokenModule
+    AuthModule --> SessionModule
+    AuthModule --> SocialModule
+    AuthModule --> OIDCModule
+    AuthModule --> MFAModule
+    AuthModule --> RBACModule
+
+    %% Identity Dependencies
+    IdentityModule --> OrgModule
+    IdentityModule --> GroupModule
+    IdentityModule --> RBACModule
+
+    %% Access Dependencies
+    AccessModule --> AnalyticsModule
+    AccessModule --> RBACModule
+
+    %% Governance Dependencies
+    GovernanceModule --> RBACModule
+
+    %% Core Services
+    AuthModule --> CacheService
+    IdentityModule --> CacheService
+    RBACModule --> CacheService
+
+    AuthModule --> AuditService
+    AccessModule --> AuditService
+    GovernanceModule --> AuditService
+
+    AuthModule --> SecurityService
+
+    AuthModule --> FeatureService
+
+    %% Data Access
+    AuthModule --> Repositories
+    IdentityModule --> Repositories
+    AccessModule --> Repositories
+    GovernanceModule --> Repositories
+    RBACModule --> Repositories
+
+    Repositories --> Database
+    CacheService --> Redis
+    CacheService --> Database
+
+    style AuthModule fill:#e1f5fe
+    style RBACModule fill:#f3e5f5
+    style IdentityModule fill:#fff3e0
+    style AccessModule fill:#e8f5e9
+    style GovernanceModule fill:#fce4ec
+    style CacheService fill:#bbdefb
+    style AuditService fill:#c8e6c9
+    style SecurityService fill:#ffccbc
+```
+
+### Module Descriptions
+
+| Module | Responsibility | Key Files |
+|--------|---------------|-----------|
+| **Auth** | User authentication and token management | `auth.service.ts`, `auth.controller.ts` |
+| **Token** | JWT generation, validation, and refresh | `jwt.service.ts`, `cookie.service.ts` |
+| **Session** | Session lifecycle and device management | `session.service.ts` |
+| **RBAC** | Role and permission management | `rbac.service.ts`, `rbac.middleware.ts` |
+| **Social** | OAuth integration with external providers | `social.service.ts`, `google.strategy.ts` |
+| **OIDC** | OpenID Connect provider and client | `oidc-provider.service.ts` |
+| **MFA** | Multi-factor authentication | `mfa.service.ts`, `totp.service.ts` |
+| **Identity** | User lifecycle and profile management | `user.service.ts`, `profile.service.ts` |
+| **Organization** | Multi-tenant organization support | `organization.service.ts` |
+| **Group** | Group-based access control | `group.service.ts` |
+| **Access** | Access request workflows and reviews | `request.service.ts`, `review.service.ts` |
+| **Analytics** | Access analytics and reporting | `analytics.service.ts` |
+| **Governance** | Compliance, policy, and risk management | `compliance.service.ts`, `risk.service.ts` |
+| **Cache** | Multi-layer caching (Memory + Redis) | `cache.service.ts` |
+| **Audit** | Event sourcing and audit logging | `audit.service.ts` |
+| **Security** | Encryption, hashing, zero-trust | `zero-trust.validator.ts` |
+
+---
+
+## Data Architecture
+
+The IAM Service uses PostgreSQL with 30+ Prisma models. See [DATA-MODEL.md](./concepts/DATA-MODEL.md) for complete Entity Relationship Diagram.
+
+### Model Categories
+
+1. **Core Authentication** (7 models):
+   - User, Session, RefreshToken, AuthEvent, SocialAccount, MFADevice, Policy
+
+2. **Authorization** (6 models):
+   - Role, Permission, UserRole, RolePermission, UserPermission, GroupPermission
+
+3. **Identity Management** (6 models):
+   - Organization, Group, GroupMember, UserProfile, IdentityVerification
+
+4. **Access Management** (4 models):
+   - AccessRequest, AccessRequestApprover, AccessReview, AccessReviewItem
+
+5. **Governance** (3 models):
+   - ComplianceReport, PolicyTemplate, RiskScore
+
+### Key Relationships
+
+```
+User (1) ─── (*) UserRole ─── (*) Role ─── (*) RolePermission ─── (*) Permission
+User (1) ─── (*) UserPermission ─── (*) Permission
+User (1) ─── (*) Session
+User (1) ─── (1) UserProfile
+User (1) ─── (*) AccessRequest
+Organization (1) ─── (*) User
+Organization (1) ─── (*) Group ─── (*) GroupMember ─── (*) User
+```
+
+---
+
+## Security Architecture
+
+The IAM Service implements defense-in-depth security with multiple layers:
+
+### Security Layers
+
+```mermaid
+graph TB
+    Request[Incoming Request] --> Layer1[Layer 1: Network Security<br/>Traefik Gateway + TLS]
+
+    Layer1 --> Layer2[Layer 2: Zero-Trust Validation<br/>Device + Location + Behavior]
+
+    Layer2 --> Layer3[Layer 3: Rate Limiting<br/>Dynamic by Role<br/>50-1000 req/15min]
+
+    Layer3 --> Layer4[Layer 4: Authentication<br/>JWT Validation<br/>Token Expiry: 15min]
+
+    Layer4 --> Layer5[Layer 5: Authorization<br/>RBAC + ABAC<br/>Permission Checking]
+
+    Layer5 --> Layer6[Layer 6: Input Validation<br/>Zod Schemas<br/>Sanitization]
+
+    Layer6 --> Layer7[Layer 7: Audit Logging<br/>Event Sourcing<br/>All Actions Logged]
+
+    Layer7 --> ProcessRequest[Process Request]
+
+    style Layer1 fill:#ffccbc
+    style Layer2 fill:#ff9999
+    style Layer3 fill:#ffb74d
+    style Layer4 fill:#fff176
+    style Layer5 fill:#aed581
+    style Layer6 fill:#4dd0e1
+    style Layer7 fill:#9575cd
+    style ProcessRequest fill:#c8e6c9
+```
+
+### Security Features
+
+| Feature | Implementation | Location |
+|---------|---------------|----------|
+| **Zero-Trust** | Device fingerprinting, location, behavior analysis | `zero-trust.validator.ts` |
+| **Password Hashing** | bcrypt (cost factor 12) | `auth.service.ts:43` |
+| **Token Security** | JWT with HS256, 15min expiry, token rotation | `jwt.service.ts` |
+| **CSRF Protection** | State tokens for OAuth, SameSite cookies | `cookie.service.ts` |
+| **Rate Limiting** | Redis-backed, dynamic by role | `rate-limit.middleware.ts` |
+| **Input Validation** | Zod schemas, sanitization | `validation.middleware.ts` |
+| **Audit Logging** | Event sourcing (AuthEvent model) | `audit.service.ts` |
+| **Session Security** | Device fingerprinting, IP tracking | `session.service.ts` |
+| **MFA** | TOTP with 30s window, backup codes | `mfa.service.ts` |
+
+### Threat Mitigation
+
+| Threat | Mitigation |
+|--------|-----------|
+| **Brute Force** | Login rate limiting (5 attempts/15min), account lockout |
+| **Token Theft** | Short token lifetime (15min), token rotation, device binding |
+| **CSRF** | SameSite cookies, state tokens for OAuth |
+| **XSS** | Content Security Policy, HttpOnly cookies |
+| **SQL Injection** | Prisma ORM parameterized queries |
+| **Session Hijacking** | Device fingerprinting, IP validation |
+| **Privilege Escalation** | Strict permission checks, audit logging |
+| **Replay Attacks** | Token expiry, nonce for OAuth |
+
+---
+
+## Observability
+
+The IAM Service provides comprehensive observability with metrics, logs, and traces:
+
+### Observability Stack
+
+```mermaid
+graph TB
+    subgraph "IAM Service"
+        Application[Application Code]
+
+        Application --> MetricsCollector[Metrics Collector<br/>Prometheus Format]
+        Application --> Logger[Structured Logger<br/>Winston]
+        Application --> Tracer[Distributed Tracer<br/>Jaeger Client]
+    end
+
+    subgraph "Collection Layer"
+        Prometheus[Prometheus<br/>Metrics Storage]
+        Loki[Loki<br/>Log Aggregation]
+        Jaeger[Jaeger<br/>Trace Storage]
+    end
+
+    subgraph "Visualization Layer"
+        Grafana[Grafana<br/>Dashboards + Alerts]
+    end
+
+    MetricsCollector --> Prometheus
+    Logger --> Loki
+    Tracer --> Jaeger
+
+    Prometheus --> Grafana
+    Loki --> Grafana
+    Jaeger --> Grafana
+
+    Grafana --> Alerts[Alert Manager<br/>Notifications]
+
+    style Application fill:#e1f5fe
+    style Prometheus fill:#f3e5f5
+    style Loki fill:#fff3e0
+    style Jaeger fill:#e8f5e9
+    style Grafana fill:#fce4ec
+```
+
+### Metrics (Prometheus)
+
+**Collected Metrics:**
+- HTTP request duration (histogram)
+- HTTP request count (counter)
+- HTTP response status codes (counter)
+- Active sessions (gauge)
+- Cache hit/miss ratio (counter)
+- Database query duration (histogram)
+- Authentication success/failure rate (counter)
+- Permission check duration (histogram)
+
+**Endpoints:**
+- `/metrics` - Prometheus metrics endpoint
+- `/health/live` - Liveness probe
+- `/health/ready` - Readiness probe
+
+### Logging (Winston)
+
+**Log Levels:** ERROR, WARN, INFO, DEBUG
+
+**Structured Log Format:**
+```json
+{
+  "level": "info",
+  "message": "User logged in",
+  "timestamp": "2024-01-01T00:00:00.000Z",
+  "correlationId": "req-123-456",
+  "userId": "user-789",
+  "email": "user@example.com",
+  "service": "iam-service"
+}
+```
+
+### Tracing (Jaeger)
+
+**Trace Spans:**
+- HTTP request handling
+- Database queries
+- Cache operations
+- External API calls
+- Authentication flow
+- Authorization checks
+
+**Correlation IDs:**
+- Every request gets a unique correlation ID
+- Propagated across service calls
+- Included in all logs and traces
+
+---
+
+## Deployment Architecture
+
+The IAM Service can be deployed in multiple configurations:
 
 ### Local Development
 
-1. **Setup Infrastructure**: `docker-compose up -d`
-2. **Install Dependencies**: `pnpm install`
-3. **Database Setup**: `pnpm prisma migrate dev && pnpm prisma db seed`
-4. **Start Development**: `pnpm dev`
-5. **Run Tests**: `pnpm test`
+```mermaid
+graph LR
+    Developer[Developer<br/>Localhost] --> LocalIAM[IAM Service<br/>pnpm dev<br/>Port 3001]
 
-### Testing Strategy
+    LocalIAM --> LocalDB[(PostgreSQL<br/>Docker<br/>Port 5432)]
+    LocalIAM --> LocalRedis[(Redis<br/>Docker<br/>Port 6379)]
 
-1. **Unit Tests**: Test individual functions and classes
-2. **Integration Tests**: Test middleware chains and service interactions
-3. **E2E Tests**: Test complete API workflows
-4. **Performance Tests**: Load testing and performance validation
+    style LocalIAM fill:#e1f5fe
+    style LocalDB fill:#f3e5f5
+    style LocalRedis fill:#fff3e0
+```
 
-### Deployment Pipeline
-
-1. **Linting**: Code quality checks with ESLint and Prettier
-2. **Testing**: Full test suite execution (unit, integration, E2E)
-3. **Security Scanning**: Dependency audit, SAST, and container scanning
-4. **Build**: Multi-stage Docker image creation with security scanning
-5. **Deploy**: Container orchestration deployment with health checks
-6. **Verification**: Automated post-deployment health and performance verification
-
----
-
-# Part 2: Platform Integration (External)
-
-This section describes how a service built from this template integrates with the GoodGo microservices platform.
-
-## Platform Architecture
+### Docker Compose (Multi-Service)
 
 ```mermaid
-graph TD
-    Client[Client / Browser] --> Traefik[Traefik API Gateway]
-    
-    subgraph Platform[GoodGo Microservices Platform]
-        Traefik --> IAMService[IAM Service]
-        Traefik --> YourService[Your Service from Template]
-        Traefik --> OtherServices[Other Services...]
-        
-        YourService --> SharedDB[(Shared PostgreSQL)]
-        YourService --> SharedRedis[(Shared Redis)]
-        
-        IAMService -.->|JWT Validation| YourService
-        YourService -.->|Inter-Service Calls| OtherServices
+graph TB
+    subgraph "Docker Compose Network"
+        Traefik[Traefik Gateway<br/>Port 80/443]
+
+        Traefik --> IAMService[IAM Service<br/>Port 3001]
+        Traefik --> ProductService[Product Service<br/>Port 3002]
+        Traefik --> OrderService[Order Service<br/>Port 3003]
+
+        IAMService --> SharedDB[(PostgreSQL<br/>Port 5432)]
+        IAMService --> SharedRedis[(Redis<br/>Port 6379)]
+
+        ProductService --> SharedDB
+        ProductService --> SharedRedis
+
+        OrderService --> SharedDB
+        OrderService --> SharedRedis
     end
-    
-    subgraph Observability[Observability Stack]
-        Prometheus[Prometheus]
-        Grafana[Grafana]
-        Jaeger[Jaeger]
-        Loki[Loki]
-    end
-    
-    YourService -.->|Metrics| Prometheus
-    YourService -.->|Traces| Jaeger
-    YourService -.->|Logs| Loki
-    Prometheus --> Grafana
-    
+
     style Traefik fill:#ffecb3
-    style YourService fill:#e1f5fe
+    style IAMService fill:#e1f5fe
+    style SharedDB fill:#f3e5f5
+    style SharedRedis fill:#fff3e0
 ```
 
-## Service Discovery & Registration
+### Kubernetes (Production)
 
-Services are registered with Traefik via Docker labels in `deployments/local/docker-compose.yml`:
+```mermaid
+graph TB
+    subgraph "Ingress Layer"
+        Ingress[Ingress Controller<br/>NGINX/Traefik<br/>TLS Termination]
+    end
 
-```yaml
-services:
-  your-service:
-    build:
-      context: ../..
-      dockerfile: services/your-service/Dockerfile
-    labels:
-      # Enable Traefik for this service
-      - "traefik.enable=true"
-      
-      # Define routing rule
-      - "traefik.http.routers.your-service.rule=PathPrefix(`/api/v1/your-service`)"
-      
-      # Specify service port
-      - "traefik.http.services.your-service.loadbalancer.server.port=5002"
-      
-      # Health check configuration
-      - "traefik.http.services.your-service.loadbalancer.healthcheck.path=/health/live"
-      - "traefik.http.services.your-service.loadbalancer.healthcheck.interval=10s"
+    subgraph "Application Layer"
+        IAMPod1[IAM Pod 1<br/>Replica 1]
+        IAMPod2[IAM Pod 2<br/>Replica 2]
+        IAMPod3[IAM Pod 3<br/>Replica 3]
+
+        IAMService[IAM Service<br/>ClusterIP]
+    end
+
+    subgraph "Data Layer"
+        PostgreSQL[(PostgreSQL<br/>StatefulSet<br/>Persistent Volume)]
+        Redis[(Redis<br/>StatefulSet<br/>Sentinel HA)]
+    end
+
+    subgraph "Observability"
+        Prometheus[Prometheus<br/>Metrics]
+        Jaeger[Jaeger<br/>Tracing]
+        Loki[Loki<br/>Logs]
+    end
+
+    Ingress --> IAMService
+    IAMService --> IAMPod1
+    IAMService --> IAMPod2
+    IAMService --> IAMPod3
+
+    IAMPod1 --> PostgreSQL
+    IAMPod1 --> Redis
+    IAMPod2 --> PostgreSQL
+    IAMPod2 --> Redis
+    IAMPod3 --> PostgreSQL
+    IAMPod3 --> Redis
+
+    IAMPod1 -.-> Prometheus
+    IAMPod1 -.-> Jaeger
+    IAMPod1 -.-> Loki
+
+    style Ingress fill:#ffecb3
+    style IAMPod1 fill:#e1f5fe
+    style IAMPod2 fill:#e1f5fe
+    style IAMPod3 fill:#e1f5fe
+    style PostgreSQL fill:#f3e5f5
+    style Redis fill:#fff3e0
 ```
 
-## Shared Infrastructure
+### Production Best Practices
 
-### Traefik API Gateway (infra/traefik/)
+1. **High Availability**:
+   - Multiple IAM service replicas (3+)
+   - PostgreSQL replication (primary + standby)
+   - Redis Sentinel for failover
 
-- **Location**: `infra/traefik/` - Platform-level configuration
-- **Static Config**: `traefik.yml` - Entry points, providers, API dashboard
-- **Dynamic Config**: `dynamic/middlewares.yml`, `dynamic/routes.yml`
-- **Features**: Load balancing, rate limiting, SSL/TLS, CORS, security headers
+2. **Security**:
+   - TLS/SSL for all connections
+   - Network policies for pod-to-pod communication
+   - Secrets management (HashiCorp Vault, AWS Secrets Manager)
+   - Non-root containers
 
-### PostgreSQL Database
+3. **Resource Limits**:
+   ```yaml
+   resources:
+     requests:
+       cpu: 500m
+       memory: 512Mi
+     limits:
+       cpu: 2000m
+       memory: 2Gi
+   ```
 
-- **Shared or Isolated**: Can be shared database with schema isolation or separate databases
-- **Connection**: Via `DATABASE_URL` environment variable
-- **Migrations**: Managed per-service with Prisma
+4. **Health Checks**:
+   ```yaml
+   livenessProbe:
+     httpGet:
+       path: /health/live
+       port: 3001
+     initialDelaySeconds: 30
+     periodSeconds: 10
 
-### Redis Cache
+   readinessProbe:
+     httpGet:
+       path: /health/ready
+       port: 3001
+     initialDelaySeconds: 10
+     periodSeconds: 5
+   ```
 
-- **Shared Instance**: Common Redis instance for all services
-- **Connection**: Via `REDIS_URL` or `REDIS_HOST`/`REDIS_PORT`
-- **Use Cases**: Caching, rate limiting, session storage
-
-### Observability Stack (infra/observability/)
-
-- **Prometheus**: Metrics collection from all services
-- **Grafana**: Visualization and dashboards
-- **Jaeger**: Distributed tracing
-- **Loki**: Log aggregation
-
-## Inter-Service Communication
-
-### HTTP/REST Communication
-
-Services communicate via HTTP through Traefik or direct service-to-service calls:
-
-```typescript
-// Example: Calling another service
-const response = await fetch('http://iam-service:5001/api/v1/users/validate', {
-  headers: {
-    'Authorization': `Bearer ${token}`,
-    'X-Correlation-ID': correlationId
-  }
-});
-```
-
-### Authentication Flow
-
-1. Client authenticates with Auth Service
-2. Auth Service issues JWT token
-3. Client includes JWT in requests to other services
-4. Services validate JWT using `@goodgo/auth-sdk`
-5. Services extract user info from validated token
+5. **Horizontal Pod Autoscaling**:
+   ```yaml
+   minReplicas: 3
+   maxReplicas: 10
+   targetCPUUtilizationPercentage: 70
+   ```
 
 ---
 
-# Part 3: Deployment Context
+## Next Steps
 
-This section explains how to deploy a service built from this template to the platform.
+- **User Guides**: See [GETTING-STARTED.md](./guides/01-GETTING-STARTED.md) for setup instructions
+- **API Reference**: See [API_REFERENCE.md](./API_REFERENCE.md) for complete endpoint documentation
+- **Security Model**: See [SECURITY-MODEL.md](./concepts/SECURITY-MODEL.md) for security details
+- **Data Model**: See [DATA-MODEL.md](./concepts/DATA-MODEL.md) for database schema
+- **Deployment**: See [DEPLOYMENT-GUIDE.md](./deployment/DEPLOYMENT-GUIDE.md) for deployment instructions
 
-## Adding Service to Platform
+---
 
-### Step 1: Create Service from Template
+## References
 
-```bash
-# Use the create-service script
-./scripts/utils/create-service.sh my-new-service
+- **Security Skill**: [.cursor/skills/security/SKILL.md](../../../.cursor/skills/security/SKILL.md)
+- **IAM Proposal**: [docs/en/architecture/iam-proposal.md](../../../docs/en/architecture/iam-proposal.md)
+- **Migration Guide**: [docs/en/guides/iam-migration.md](../../../docs/en/guides/iam-migration.md)
+- **Prisma Schema**: [prisma/schema.prisma](../prisma/schema.prisma)
+- **Routes Definition**: [src/routes/index.ts](../src/routes/index.ts)
 
-# Or manually copy the template
-cp -r services/_template services/my-new-service
-```
+---
 
-### Step 2: Register in deployments/local/docker-compose.yml
-
-Add your service to the platform compose file:
-
-```yaml
-services:
-  my-new-service:
-    build:
-      context: ../..
-      dockerfile: services/my-new-service/Dockerfile
-    container_name: my-new-service-local
-    environment:
-      - NODE_ENV=development
-      - PORT=5003
-      - DATABASE_URL=${DATABASE_URL}
-      - REDIS_HOST=redis
-      - REDIS_PORT=6379
-      - JWT_SECRET=${JWT_SECRET}
-      - SERVICE_NAME=my-new-service
-      - API_VERSION=v1
-    depends_on:
-      redis:
-        condition: service_healthy
-    networks:
-      - microservices-network
-    labels:
-      - "traefik.enable=true"
-      - "traefik.http.routers.my-new-service.rule=PathPrefix(`/api/v1/my-new-service`)"
-      - "traefik.http.services.my-new-service.loadbalancer.server.port=5003"
-```
-
-### Step 3: Configure Traefik Routes (Optional)
-
-For advanced routing, add to `infra/traefik/dynamic/routes.yml`:
-
-```yaml
-http:
-  routers:
-    my-new-service:
-      rule: "PathPrefix(`/api/v1/my-new-service`)"
-      service: my-new-service
-      middlewares:
-        - secure-headers
-        - cors
-        - compress
-```
-
-### Step 4: Start the Platform
-
-```bash
-cd deployments/local
-docker-compose up -d
-```
-
-### Step 5: Access Your Service
-
-- **API**: http://localhost/api/v1/my-new-service
-- **Health**: http://localhost/api/v1/my-new-service/health
-- **API Docs**: http://localhost/api/v1/my-new-service/api-docs
-- **Traefik Dashboard**: http://localhost:8080
-
-## Environment Configuration
-
-Services inherit environment variables from:
-
-1. **Platform Level**: `deployments/local/.env.local`
-2. **Service Level**: Service-specific environment in docker-compose.yml
-3. **Defaults**: Service's `.env.example` for development
-
-## Operational Excellence
-
-### Incident Response
-
-1. **Detection**: Automated monitoring alerts
-2. **Assessment**: Incident severity classification
-3. **Communication**: Stakeholder notification
-4. **Investigation**: Root cause analysis
-5. **Resolution**: Fix deployment and verification
-6. **Post-mortem**: Incident review and improvement
-
-### Capacity Planning
-
-- **Resource Monitoring**: Track CPU, memory, disk, and network usage
-- **Performance Benchmarks**: Regular performance testing
-- **Scaling Triggers**: Automated scaling based on metrics
-- **Cost Optimization**: Right-sizing resources
-
-### Compliance & Security
-
-- **Security Audits**: Regular security assessments
-- **Compliance Checks**: GDPR, HIPAA, SOC2 compliance
-- **Data Encryption**: At-rest and in-transit encryption
-- **Access Controls**: Least privilege access principles
+**Last Updated**: January 2026
+**Version**: 1.0.0
+**Status**: Production Ready
diff --git a/services/iam-service/docs/concepts/CORE-CONCEPTS.md b/services/iam-service/docs/concepts/CORE-CONCEPTS.md
new file mode 100644
index 00000000..65e7d837
--- /dev/null
+++ b/services/iam-service/docs/concepts/CORE-CONCEPTS.md
@@ -0,0 +1,798 @@
+# IAM Core Concepts
+
+> **Foundational Concepts for Identity & Access Management**
+>
+> This document explains the fundamental concepts, principles, and terminology used in the IAM Service.
+
+## Table of Contents
+
+- [What is IAM?](#what-is-iam)
+- [Key Concepts](#key-concepts)
+- [Authentication Methods](#authentication-methods)
+- [Authorization Models](#authorization-models)
+- [Security Principles](#security-principles)
+- [Common Patterns](#common-patterns)
+
+---
+
+## What is IAM?
+
+**IAM (Identity and Access Management)** is a framework of policies, processes, and technologies that ensures the right individuals access the right resources at the right times for the right reasons.
+
+### The Three Pillars of IAM
+
+```mermaid
+graph LR
+    IAM[Identity & Access<br/>Management]
+
+    IAM --> Identity[Identity<br/>Management]
+    IAM --> Access[Access<br/>Control]
+    IAM --> Governance[Governance &<br/>Compliance]
+
+    Identity --> Users[Users & Profiles]
+    Identity --> Orgs[Organizations]
+    Identity --> Groups[Groups]
+
+    Access --> Auth[Authentication]
+    Access --> Authz[Authorization]
+    Access --> Sessions[Session Management]
+
+    Governance --> Audit[Audit Logs]
+    Governance --> Compliance[Compliance Reports]
+    Governance --> Risk[Risk Management]
+
+    style IAM fill:#e1f5fe
+    style Identity fill:#f3e5f5
+    style Access fill:#fff3e0
+    style Governance fill:#e8f5e9
+```
+
+### Why IAM Matters
+
+1. **Security**: Prevent unauthorized access to sensitive resources
+2. **Compliance**: Meet regulatory requirements (GDPR, SOC2, HIPAA, ISO27001)
+3. **Productivity**: Users can access what they need, when they need it
+4. **Visibility**: Track who did what, when, and why
+5. **Efficiency**: Automate user provisioning and de-provisioning
+6. **Risk Management**: Identify and mitigate access-related risks
+
+### IAM vs Authentication vs Authorization
+
+| Aspect | Authentication | Authorization | IAM |
+|--------|---------------|---------------|-----|
+| **Question** | Who are you? | What can you do? | Complete identity lifecycle |
+| **Scope** | Identity verification | Permission checking | Identity + Access + Governance |
+| **Example** | Login with password | Check if user can delete file | User creation → access → reviews → compliance |
+| **Output** | User identity | Allow/Deny decision | Complete access management |
+| **Technologies** | JWT, OAuth, SAML | RBAC, ABAC, ACL | Authentication + Authorization + Audit + Compliance |
+
+**Simple Analogy**:
+- **Authentication** = Showing your ID at the door (proving who you are)
+- **Authorization** = Checking if you're on the guest list (proving what you can access)
+- **IAM** = Managing the entire event (invitations, guest lists, access levels, tracking, compliance)
+
+---
+
+## Key Concepts
+
+### Principals
+
+A **principal** is an entity that can request access to resources.
+
+```mermaid
+graph TD
+    Principal[Principal<br/>Who wants access?]
+
+    Principal --> User[User<br/>Human with email/password]
+    Principal --> Service[Service<br/>Application with API key]
+    Principal --> Device[Device<br/>Mobile/Desktop with cert]
+
+    User --> UserTypes[User Types]
+    UserTypes --> Employee[Employee]
+    UserTypes --> Customer[Customer]
+    UserTypes --> Partner[Partner]
+    UserTypes --> Admin[Administrator]
+
+    style Principal fill:#e1f5fe
+    style User fill:#fff3e0
+    style Service fill:#e8f5e9
+    style Device fill:#f3e5f5
+```
+
+**Examples**:
+- Human users: `user@example.com`
+- Service accounts: `payment-service`
+- API clients: `mobile-app-v1`
+- IoT devices: `sensor-123`
+
+### Resources
+
+A **resource** is an entity that can be accessed or acted upon.
+
+**Common Resources**:
+- **Data**: Users, products, orders, invoices, reports
+- **Functions**: APIs, endpoints, services, microservices
+- **Infrastructure**: Databases, queues, storage buckets
+- **Business Objects**: Projects, organizations, teams
+
+**Resource Naming Convention**: `resource-type`
+- Examples: `users`, `products`, `orders`, `payments`, `reports`
+
+### Actions
+
+An **action** is an operation that can be performed on a resource.
+
+**Standard Actions** (CRUD):
+- `create` - Create new resources
+- `read` - View/list resources
+- `update` - Modify existing resources
+- `delete` - Remove resources
+
+**Extended Actions**:
+- `list` - List multiple resources
+- `export` - Export data
+- `import` - Import data
+- `approve` - Approve workflows
+- `publish` - Publish content
+- `archive` - Archive resources
+
+**Action Naming Convention**: `verb`
+- Examples: `read`, `create`, `update`, `delete`, `approve`
+
+### Permissions
+
+A **permission** is the right to perform an action on a resource within a specific scope.
+
+**Permission Format**: `resource:action:scope`
+
+```mermaid
+graph LR
+    Permission[Permission<br/>users:read:all]
+
+    Permission --> Resource[Resource<br/>users]
+    Permission --> Action[Action<br/>read]
+    Permission --> Scope[Scope<br/>all]
+
+    Scope --> Own[own<br/>Only your resources]
+    Scope --> Team[team<br/>Your team's resources]
+    Scope --> All[all<br/>All resources]
+
+    style Permission fill:#e1f5fe
+    style Resource fill:#f3e5f5
+    style Action fill:#fff3e0
+    style Scope fill:#e8f5e9
+```
+
+**Permission Examples**:
+
+| Permission | Meaning |
+|-----------|---------|
+| `users:read:all` | Read all users |
+| `users:update:own` | Update own user profile |
+| `products:create:team` | Create products for team |
+| `orders:delete:all` | Delete any order (admin) |
+| `reports:export:team` | Export team reports |
+| `payments:approve:all` | Approve all payments |
+
+### Policies
+
+A **policy** is a set of rules that determine access based on attributes and conditions.
+
+```mermaid
+graph TD
+    Policy[Policy<br/>Business Hours Access]
+
+    Policy --> Resource[Resource<br/>sensitive_data]
+    Policy --> Conditions[Conditions]
+    Policy --> Effect[Effect<br/>ALLOW/DENY]
+
+    Conditions --> Time[Time Condition<br/>9am - 5pm]
+    Conditions --> Day[Day Condition<br/>Monday - Friday]
+    Conditions --> Location[Location Condition<br/>Office IP ranges]
+
+    Effect --> Allow[ALLOW<br/>Grant access]
+    Effect --> Deny[DENY<br/>Block access]
+
+    style Policy fill:#e1f5fe
+    style Conditions fill:#fff3e0
+    style Effect fill:#e8f5e9
+```
+
+**Policy Example** (JSON Logic):
+```json
+{
+  "name": "Business Hours Only",
+  "resource": "sensitive_data",
+  "condition": {
+    "and": [
+      {">=": [{"var": "hour"}, 9]},
+      {"<=": [{"var": "hour"}, 17]},
+      {"in": [{"var": "day"}, [1, 2, 3, 4, 5]]},
+      {"in": [{"var": "ip"}, ["192.168.1.0/24", "10.0.0.0/8"]]}
+    ]
+  },
+  "effect": "ALLOW",
+  "priority": 100
+}
+```
+
+### The Access Decision Triangle
+
+Every access decision involves three key elements:
+
+```mermaid
+graph TD
+    Decision{Access Decision<br/>Allow or Deny?}
+
+    Principal[Principal<br/>WHO wants access?<br/>user@example.com]
+    Resource[Resource<br/>WHAT is being accessed?<br/>sensitive_data]
+    Action[Action<br/>WHAT operation?<br/>read]
+
+    Principal --> Decision
+    Resource --> Decision
+    Action --> Decision
+
+    Decision --> Context[Context<br/>WHEN, WHERE, HOW?]
+
+    Context --> Time[Time<br/>During business hours?]
+    Context --> Location[Location<br/>From office IP?]
+    Context --> Device[Device<br/>Trusted device?]
+    Context --> Risk[Risk Level<br/>Low risk score?]
+
+    Decision -->|All conditions met| Allow[ALLOW<br/>Access Granted]
+    Decision -->|Any condition fails| Deny[DENY<br/>Access Denied]
+
+    style Decision fill:#fff3e0
+    style Principal fill:#e1f5fe
+    style Resource fill:#f3e5f5
+    style Action fill:#e8f5e9
+    style Allow fill:#c8e6c9
+    style Deny fill:#ffcdd2
+```
+
+---
+
+## Authentication Methods
+
+Authentication is the process of verifying the identity of a user, service, or device.
+
+### Authentication Factors
+
+```mermaid
+graph LR
+    MFA[Multi-Factor<br/>Authentication]
+
+    MFA --> Something[Something<br/>You Know]
+    MFA --> SomethingHave[Something<br/>You Have]
+    MFA --> SomethingAre[Something<br/>You Are]
+
+    Something --> Password[Password]
+    Something --> PIN[PIN]
+    Something --> SecurityQ[Security Questions]
+
+    SomethingHave --> Phone[Phone/SMS]
+    SomethingHave --> Token[Hardware Token]
+    SomethingHave --> App[Authenticator App]
+
+    SomethingAre --> Fingerprint[Fingerprint]
+    SomethingAre --> Face[Face Recognition]
+    SomethingAre --> Voice[Voice Recognition]
+
+    style MFA fill:#e1f5fe
+    style Something fill:#fff3e0
+    style SomethingHave fill:#e8f5e9
+    style SomethingAre fill:#f3e5f5
+```
+
+### 1. Password-Based Authentication
+
+**How it works**:
+1. User provides email + password
+2. System hashes password with bcrypt
+3. Compare hash with stored hash
+4. Generate JWT token if match
+
+**Security Features**:
+- Bcrypt hashing (cost factor 12)
+- Password complexity requirements
+- Rate limiting (5 attempts per 15 minutes)
+- Account lockout after failed attempts
+
+**Use Cases**:
+- Traditional web applications
+- Internal employee systems
+- Admin portals
+
+### 2. Social Authentication (OAuth 2.0)
+
+**How it works**:
+1. User clicks "Sign in with Google/Facebook/GitHub"
+2. Redirect to OAuth provider
+3. User authorizes app
+4. Receive authorization code
+5. Exchange code for access token
+6. Create or link user account
+
+**Benefits**:
+- No password management
+- Faster signup/login
+- Higher conversion rates
+- Trust in established providers
+
+**Supported Providers**:
+- Google OAuth 2.0
+- Facebook OAuth
+- GitHub OAuth
+- Apple Sign-In (future)
+- Microsoft OAuth (future)
+
+### 3. OpenID Connect (OIDC)
+
+**How it works**:
+- Extension of OAuth 2.0 for authentication
+- Provides ID tokens (JWT) with user claims
+- Supports discovery and dynamic registration
+
+**Modes**:
+- **OIDC Provider**: IAM acts as identity provider for other apps
+- **OIDC Client**: IAM consumes other identity providers
+
+**Use Cases**:
+- Single Sign-On (SSO)
+- Enterprise authentication
+- Federation across organizations
+
+### 4. Multi-Factor Authentication (MFA)
+
+**TOTP (Time-based One-Time Password)**:
+- Generate 6-digit code every 30 seconds
+- Works with Google Authenticator, Authy, 1Password
+- No internet connection required
+- Backup codes for account recovery
+
+**WebAuthn/FIDO2** (future):
+- Hardware security keys (YubiKey, Titan)
+- Platform authenticators (Touch ID, Face ID, Windows Hello)
+- Phishing-resistant
+- No shared secrets
+
+**When to Require MFA**:
+- High-risk actions (money transfer, data export)
+- Privileged accounts (admins, developers)
+- Sensitive resource access
+- First login from new device
+- Risk-based triggers (unusual location, device)
+
+### 5. API Keys & Service Authentication
+
+**For Service-to-Service Communication**:
+- Long-lived API keys
+- Short-lived JWT tokens
+- Mutual TLS (mTLS)
+- Service mesh identity
+
+**Use Cases**:
+- Microservice communication
+- CI/CD pipelines
+- Scheduled jobs
+- Third-party integrations
+
+---
+
+## Authorization Models
+
+Authorization is the process of determining what an authenticated user can do.
+
+### RBAC (Role-Based Access Control)
+
+**Concept**: Users are assigned roles, roles have permissions.
+
+```mermaid
+graph LR
+    User1[User: Alice] --> UserRole1[UserRole]
+    User2[User: Bob] --> UserRole2[UserRole]
+
+    UserRole1 --> Admin[Role: ADMIN]
+    UserRole2 --> Manager[Role: MANAGER]
+
+    Admin --> RolePerm1[RolePermission]
+    Admin --> RolePerm2[RolePermission]
+    Manager --> RolePerm3[RolePermission]
+
+    RolePerm1 --> Perm1[users:*:all<br/>All user operations]
+    RolePerm2 --> Perm2[products:*:all<br/>All product operations]
+    RolePerm3 --> Perm3[orders:read:team<br/>Read team orders]
+
+    style User1 fill:#e1f5fe
+    style User2 fill:#e1f5fe
+    style Admin fill:#ffccbc
+    style Manager fill:#fff3e0
+    style Perm1 fill:#c8e6c9
+    style Perm2 fill:#c8e6c9
+    style Perm3 fill:#c8e6c9
+```
+
+**Advantages**:
+- Simple to understand and manage
+- Easy to audit ("Who has the ADMIN role?")
+- Scalable for large organizations
+- Supports role hierarchies
+
+**Limitations**:
+- Coarse-grained (all ADMINs have same permissions)
+- Hard to handle exceptions
+- Role explosion for complex scenarios
+
+**Best Practices**:
+- Principle of least privilege
+- Regular role reviews
+- Temporary role assignments with expiration
+- Separate roles for different responsibilities
+
+### ABAC (Attribute-Based Access Control)
+
+**Concept**: Access decisions based on attributes of user, resource, action, and context.
+
+```mermaid
+graph TD
+    Request[Access Request] --> Evaluate[Evaluate Policy]
+
+    Evaluate --> UserAttrs[User Attributes<br/>department, level, location]
+    Evaluate --> ResourceAttrs[Resource Attributes<br/>classification, owner, sensitivity]
+    Evaluate --> EnvironmentAttrs[Environment Attributes<br/>time, IP, device, risk score]
+
+    UserAttrs --> Decision{Policy Decision}
+    ResourceAttrs --> Decision
+    EnvironmentAttrs --> Decision
+
+    Decision -->|All conditions met| Allow[ALLOW<br/>Access Granted]
+    Decision -->|Condition fails| Deny[DENY<br/>Access Denied]
+
+    style Evaluate fill:#e1f5fe
+    style UserAttrs fill:#fff3e0
+    style ResourceAttrs fill:#e8f5e9
+    style EnvironmentAttrs fill:#f3e5f5
+    style Allow fill:#c8e6c9
+    style Deny fill:#ffcdd2
+```
+
+**Advantages**:
+- Fine-grained control
+- Dynamic decisions based on context
+- Handles exceptions easily
+- Supports complex business rules
+
+**Limitations**:
+- More complex to configure
+- Harder to audit
+- Performance considerations
+
+**Use Cases**:
+- Time-based access (business hours only)
+- Location-based access (office IP only)
+- Resource classification (access sensitive data only if cleared)
+- Risk-based access (require MFA if risky)
+
+### Hybrid Model (RBAC + ABAC)
+
+The IAM Service uses a **hybrid approach** combining the best of both:
+
+**Authorization Hierarchy**:
+```
+1. Direct User Permissions (HIGHEST PRIORITY)
+   ↓
+2. Role Permissions (RBAC)
+   ↓
+3. Group Permissions
+   ↓
+4. ABAC Policies (context-based)
+   ↓
+5. Default Deny (LOWEST PRIORITY)
+```
+
+**Example Flow**:
+1. Check if user has direct permission (e.g., explicit grant or deny)
+2. If not, check user's roles for permission
+3. If not, check user's groups for permission
+4. If not, evaluate ABAC policies with context
+5. If no match, default to DENY
+
+**Benefits**:
+- RBAC for common cases (fast, simple)
+- ABAC for exceptions and context (flexible)
+- Best of both worlds
+
+---
+
+## Security Principles
+
+### 1. Zero Trust Architecture
+
+**Principle**: "Never trust, always verify"
+
+```mermaid
+graph LR
+    Request[Every Request] --> Verify[Verify Identity]
+    Verify --> ValidateDevice[Validate Device]
+    ValidateDevice --> CheckLocation[Check Location]
+    CheckLocation --> AnalyzeBehavior[Analyze Behavior]
+    AnalyzeBehavior --> CalculateRisk[Calculate Risk]
+    CalculateRisk --> Decision{Risk Level?}
+
+    Decision -->|Low Risk| Allow[ALLOW<br/>Normal Access]
+    Decision -->|Medium Risk| MFA[Require MFA]
+    Decision -->|High Risk| Deny[DENY<br/>Block Access]
+
+    MFA --> Allow
+
+    style Request fill:#e1f5fe
+    style Decision fill:#fff3e0
+    style Allow fill:#c8e6c9
+    style MFA fill:#ffe082
+    style Deny fill:#ffcdd2
+```
+
+**Implementation**:
+- Every request authenticated
+- Device fingerprinting
+- IP address validation
+- Behavioral analysis
+- Continuous risk assessment
+
+### 2. Least Privilege
+
+**Principle**: Users should have the minimum permissions necessary to do their job.
+
+**Practice**:
+- Start with no permissions
+- Grant permissions as needed
+- Review permissions regularly
+- Remove unused permissions
+- Use time-limited permissions for temporary access
+
+### 3. Defense in Depth
+
+**Principle**: Multiple layers of security controls.
+
+```mermaid
+graph TB
+    Attack[Attack Attempt] --> Layer1[Layer 1: Network<br/>Firewall + TLS]
+
+    Layer1 --> Layer2[Layer 2: Zero-Trust<br/>Device + Location + Behavior]
+
+    Layer2 --> Layer3[Layer 3: Rate Limiting<br/>Prevent Brute Force]
+
+    Layer3 --> Layer4[Layer 4: Authentication<br/>Verify Identity]
+
+    Layer4 --> Layer5[Layer 5: Authorization<br/>Check Permissions]
+
+    Layer5 --> Layer6[Layer 6: Input Validation<br/>Prevent Injection]
+
+    Layer6 --> Layer7[Layer 7: Audit Logging<br/>Track All Actions]
+
+    Layer7 --> Resource[Protected Resource]
+
+    style Attack fill:#ffcdd2
+    style Layer1 fill:#ffccbc
+    style Layer2 fill:#ff9999
+    style Layer3 fill:#ffb74d
+    style Layer4 fill:#fff176
+    style Layer5 fill:#aed581
+    style Layer6 fill:#4dd0e1
+    style Layer7 fill:#9575cd
+    style Resource fill:#c8e6c9
+```
+
+**Layers in IAM Service**:
+1. Network security (Traefik Gateway, TLS)
+2. Zero-trust validation (device, location, behavior)
+3. Rate limiting (prevent brute force)
+4. Authentication (verify identity)
+5. Authorization (check permissions)
+6. Input validation (prevent injection attacks)
+7. Audit logging (track all actions)
+
+### 4. Separation of Duties
+
+**Principle**: No single user should have complete control over critical processes.
+
+**Examples**:
+- Different users for approval and execution
+- Code review before deployment
+- Multi-person approval for financial transactions
+- Separate roles for read and write operations
+
+### 5. Audit Everything
+
+**Principle**: Log all authentication and authorization events for security, compliance, and troubleshooting.
+
+**What to Log**:
+- User logins (success and failure)
+- Permission checks (allow and deny)
+- Permission changes (grant, revoke)
+- Role assignments
+- Policy changes
+- Session creation and termination
+- MFA events
+- Risk calculations
+
+**Log Format**:
+```json
+{
+  "eventType": "LOGIN_SUCCESS",
+  "userId": "user-123",
+  "email": "user@example.com",
+  "ipAddress": "192.168.1.100",
+  "deviceFingerprint": "abc123",
+  "timestamp": "2024-01-01T12:00:00.000Z",
+  "correlationId": "req-456"
+}
+```
+
+---
+
+## Common Patterns
+
+### 1. Single Sign-On (SSO)
+
+**Concept**: Log in once, access multiple applications.
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant App1 as Application 1
+    participant IAM as IAM Service
+    participant App2 as Application 2
+
+    User->>App1: Access App1
+    App1->>IAM: Redirect to login
+    User->>IAM: Login (email/password)
+    IAM->>IAM: Create session
+    IAM->>App1: Redirect with token
+    App1->>User: Access granted
+
+    Note over User,App2: Later, access App2
+
+    User->>App2: Access App2
+    App2->>IAM: Check session
+    IAM->>IAM: Session exists
+    IAM->>App2: Return user info
+    App2->>User: Access granted<br/>(no login required)
+```
+
+**Benefits**:
+- Better user experience (one login)
+- Reduced password fatigue
+- Centralized access control
+- Easier offboarding
+
+**Protocols**:
+- OAuth 2.0 + OIDC (modern, JSON-based)
+- SAML 2.0 (enterprise, XML-based)
+- Kerberos (legacy, Windows)
+
+### 2. Multi-Tenancy
+
+**Concept**: Single instance serves multiple organizations (tenants).
+
+```mermaid
+graph TD
+    IAM[IAM Service<br/>Single Instance]
+
+    IAM --> Org1[Organization 1<br/>Company A]
+    IAM --> Org2[Organization 2<br/>Company B]
+    IAM --> Org3[Organization 3<br/>Company C]
+
+    Org1 --> Users1[Users]
+    Org1 --> Groups1[Groups]
+    Org1 --> Policies1[Policies]
+
+    Org2 --> Users2[Users]
+    Org2 --> Groups2[Groups]
+    Org2 --> Policies2[Policies]
+
+    style IAM fill:#e1f5fe
+    style Org1 fill:#fff3e0
+    style Org2 fill:#e8f5e9
+    style Org3 fill:#f3e5f5
+```
+
+**Data Isolation**:
+- Organization ID on every record
+- Row-level security in queries
+- Separate databases (optional, for high security)
+
+**Benefits**:
+- Cost-effective (shared infrastructure)
+- Easier maintenance (single codebase)
+- Faster onboarding (no deployment needed)
+
+### 3. Just-In-Time (JIT) Access
+
+**Concept**: Grant temporary access only when needed.
+
+**Flow**:
+1. User requests access to resource
+2. Manager/system approves
+3. Access granted for limited time (e.g., 2 hours)
+4. Access automatically revoked after expiry
+
+**Use Cases**:
+- Emergency database access
+- Temporary admin privileges
+- Contractor access
+- Incident response
+
+### 4. Privileged Access Management (PAM)
+
+**Concept**: Special controls for high-privilege accounts.
+
+**Features**:
+- Check-out/check-in of privileged credentials
+- Session recording
+- Just-in-time privilege elevation
+- Approval workflows
+- Automated password rotation
+
+**Use Cases**:
+- Database admin accounts
+- Cloud infrastructure accounts
+- Root/Administrator accounts
+- Service accounts with high privileges
+
+### 5. Access Reviews & Certification
+
+**Concept**: Periodic review of who has access to what.
+
+**Process**:
+1. Generate review campaign (quarterly, annually)
+2. Assign reviewers (managers, resource owners)
+3. Reviewers certify or revoke access
+4. Automatically revoke uncertified access
+5. Generate compliance report
+
+**Benefits**:
+- Prevent privilege creep
+- Compliance (SOC2, ISO27001)
+- Discover orphaned accounts
+- Identify over-privileged users
+
+---
+
+## Next Steps
+
+Now that you understand the core concepts, explore:
+
+- **[ARCHITECTURE.md](../ARCHITECTURE.en.md)** - System architecture and diagrams
+- **[DATA-MODEL.md](./DATA-MODEL.md)** - Database schema and relationships
+- **[SECURITY-MODEL.md](./SECURITY-MODEL.md)** - Security architecture and threat model
+- **[GETTING-STARTED.md](../guides/01-GETTING-STARTED.md)** - Hands-on tutorial
+
+---
+
+## Glossary
+
+| Term | Definition |
+|------|------------|
+| **Principal** | Entity requesting access (user, service, device) |
+| **Resource** | Entity being accessed (data, API, file) |
+| **Action** | Operation being performed (read, write, delete) |
+| **Permission** | Right to perform action on resource in scope (`resource:action:scope`) |
+| **Role** | Named collection of permissions |
+| **Policy** | Rule-based access control using attributes and conditions |
+| **RBAC** | Role-Based Access Control |
+| **ABAC** | Attribute-Based Access Control |
+| **MFA** | Multi-Factor Authentication |
+| **SSO** | Single Sign-On |
+| **OIDC** | OpenID Connect |
+| **JWT** | JSON Web Token |
+| **TOTP** | Time-based One-Time Password |
+| **Zero Trust** | Security model: never trust, always verify |
+| **Least Privilege** | Minimum permissions necessary |
+| **Defense in Depth** | Multiple layers of security |
+
+---
+
+**Last Updated**: January 2026
+**Version**: 1.0.0
+**Status**: Production Ready
diff --git a/services/iam-service/docs/concepts/DATA-MODEL.md b/services/iam-service/docs/concepts/DATA-MODEL.md
new file mode 100644
index 00000000..f5909815
--- /dev/null
+++ b/services/iam-service/docs/concepts/DATA-MODEL.md
@@ -0,0 +1,1154 @@
+# IAM Service Data Model
+
+> **Complete Database Schema & Entity Relationships**
+>
+> This document describes all database models, relationships, and data architecture patterns used in the IAM Service.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Complete Entity Relationship Diagram](#complete-entity-relationship-diagram)
+- [Model Categories](#model-categories)
+- [Core Authentication Models](#core-authentication-models)
+- [Authorization Models](#authorization-models)
+- [Social & OIDC Models](#social--oidc-models)
+- [Identity Management Models](#identity-management-models)
+- [Access Management Models](#access-management-models)
+- [Governance Models](#governance-models)
+- [Relationships & Constraints](#relationships--constraints)
+- [Data Lifecycle](#data-lifecycle)
+- [Indexing Strategy](#indexing-strategy)
+
+---
+
+## Overview
+
+The IAM Service uses **PostgreSQL 14+** with **Prisma ORM** for type-safe database access. The data model consists of **30+ interconnected models** organized into 6 logical domains.
+
+### Database Statistics
+
+| Metric | Value |
+|--------|-------|
+| Total Models | 30+ |
+| Total Relationships | 50+ |
+| Enumerations | 11 |
+| Unique Constraints | 20+ |
+| Indexes | 60+ |
+| Foreign Keys | 35+ |
+
+### Model Organization
+
+```mermaid
+graph TD
+    DataModel[IAM Data Model<br/>30+ Models]
+
+    DataModel --> CoreAuth[Core Authentication<br/>7 models]
+    DataModel --> Authorization[Authorization<br/>6 models]
+    DataModel --> SocialOIDC[Social & OIDC<br/>2 models]
+    DataModel --> Identity[Identity Management<br/>6 models]
+    DataModel --> Access[Access Management<br/>4 models]
+    DataModel --> Governance[Governance<br/>3 models]
+
+    CoreAuth --> User[User]
+    CoreAuth --> Session[Session]
+    CoreAuth --> RefreshToken[RefreshToken]
+    CoreAuth --> AuthEvent[AuthEvent]
+    CoreAuth --> SocialAccount[SocialAccount]
+    CoreAuth --> MFADevice[MFADevice]
+    CoreAuth --> Policy[Policy]
+
+    Authorization --> Role[Role]
+    Authorization --> Permission[Permission]
+    Authorization --> UserRole[UserRole]
+    Authorization --> RolePermission[RolePermission]
+    Authorization --> UserPermission[UserPermission]
+    Authorization --> GroupPermission[GroupPermission]
+
+    Identity --> Organization[Organization]
+    Identity --> Group[Group]
+    Identity --> GroupMember[GroupMember]
+    Identity --> UserProfile[UserProfile]
+    Identity --> IdentityVerification[IdentityVerification]
+
+    Access --> AccessRequest[AccessRequest]
+    Access --> AccessRequestApprover[AccessRequestApprover]
+    Access --> AccessReview[AccessReview]
+    Access --> AccessReviewItem[AccessReviewItem]
+
+    Governance --> ComplianceReport[ComplianceReport]
+    Governance --> PolicyTemplate[PolicyTemplate]
+    Governance --> RiskScore[RiskScore]
+
+    style DataModel fill:#e1f5fe
+    style CoreAuth fill:#fff3e0
+    style Authorization fill:#f3e5f5
+    style SocialOIDC fill:#e8f5e9
+    style Identity fill:#fce4ec
+    style Access fill:#ffccbc
+    style Governance fill:#c8e6c9
+```
+
+---
+
+## Complete Entity Relationship Diagram
+
+This diagram shows all 30+ models and their relationships:
+
+```mermaid
+erDiagram
+    %% ============================================================================
+    %% Core Authentication Domain
+    %% ============================================================================
+
+    User ||--o{ UserRole : "has"
+    User ||--o{ UserPermission : "has direct"
+    User ||--o{ Session : "has"
+    User ||--o{ RefreshToken : "has"
+    User ||--o{ SocialAccount : "linked to"
+    User ||--o{ MFADevice : "has"
+    User ||--o{ AuthEvent : "generates"
+
+    Role ||--o{ UserRole : "assigned to users"
+    Role ||--o{ RolePermission : "has"
+
+    Permission ||--o{ RolePermission : "granted to roles"
+    Permission ||--o{ UserPermission : "granted to users"
+    Permission ||--o{ GroupPermission : "granted to groups"
+
+    %% ============================================================================
+    %% Identity Management Domain
+    %% ============================================================================
+
+    Organization ||--o{ User : "contains"
+    Organization ||--o{ Group : "contains"
+    Organization ||--o{ Policy : "has"
+    Organization ||--o{ Organization : "parent/child"
+
+    Group ||--o{ GroupMember : "has members"
+    Group ||--o{ GroupPermission : "has permissions"
+
+    User ||--o{ GroupMember : "member of"
+    User ||--|| UserProfile : "has profile"
+    User ||--o{ IdentityVerification : "has verifications"
+
+    %% ============================================================================
+    %% Access Management Domain
+    %% ============================================================================
+
+    User ||--o{ AccessRequest : "creates"
+    AccessRequest ||--o{ AccessRequestApprover : "has approvers"
+
+    AccessReview ||--o{ AccessReviewItem : "contains items"
+
+    %% ============================================================================
+    %% Governance Domain
+    %% ============================================================================
+
+    User ||--o{ RiskScore : "has risk scores"
+
+    %% ============================================================================
+    %% Model Details
+    %% ============================================================================
+
+    User {
+        string id PK "cuid primary key"
+        string email UK "unique email address"
+        string username UK "unique username"
+        string passwordHash "bcrypt hashed password"
+        boolean isActive "account active status"
+        boolean emailVerified "email verified flag"
+        boolean mfaEnabled "MFA enabled flag"
+        string mfaSecret "TOTP secret (encrypted)"
+        datetime lastLoginAt "last login timestamp"
+        int loginCount "total login count"
+        string organizationId FK "organization reference"
+        datetime createdAt "creation timestamp"
+        datetime updatedAt "last update timestamp"
+    }
+
+    Role {
+        string id PK "cuid primary key"
+        string name UK "unique role name"
+        string displayName "human-readable name"
+        string description "role description"
+        boolean isSystem "system role flag"
+        datetime createdAt "creation timestamp"
+        datetime updatedAt "last update timestamp"
+    }
+
+    Permission {
+        string id PK "cuid primary key"
+        string resource "resource type"
+        string action "action type"
+        string scope "access scope"
+        string description "permission description"
+        datetime createdAt "creation timestamp"
+    }
+
+    UserRole {
+        string id PK "cuid primary key"
+        string userId FK "user reference"
+        string roleId FK "role reference"
+        string grantedBy "granter user ID"
+        datetime expiresAt "expiration timestamp"
+        datetime createdAt "creation timestamp"
+    }
+
+    RolePermission {
+        string id PK "cuid primary key"
+        string roleId FK "role reference"
+        string permissionId FK "permission reference"
+        datetime createdAt "creation timestamp"
+    }
+
+    UserPermission {
+        string id PK "cuid primary key"
+        string userId FK "user reference"
+        string permissionId FK "permission reference"
+        boolean granted "grant or deny"
+        string grantedBy "granter user ID"
+        datetime expiresAt "expiration timestamp"
+        datetime createdAt "creation timestamp"
+    }
+
+    Session {
+        string id PK "cuid primary key"
+        string userId FK "user reference"
+        string deviceId "device identifier"
+        string deviceName "device name"
+        string ipAddress "IP address"
+        string userAgent "user agent string"
+        string fingerprint "device fingerprint"
+        boolean isActive "session active flag"
+        datetime expiresAt "expiration timestamp"
+        datetime createdAt "creation timestamp"
+        datetime lastActivityAt "last activity timestamp"
+    }
+
+    RefreshToken {
+        string id PK "cuid primary key"
+        string userId FK "user reference"
+        string token UK "token value"
+        string family "token family ID"
+        string deviceId "device identifier"
+        string ipAddress "IP address"
+        string userAgent "user agent string"
+        datetime expiresAt "expiration timestamp"
+        datetime revokedAt "revocation timestamp"
+        datetime createdAt "creation timestamp"
+    }
+
+    SocialAccount {
+        string id PK "cuid primary key"
+        string userId FK "user reference"
+        enum provider "OAuth provider"
+        string providerId "provider user ID"
+        string email "provider email"
+        string name "provider name"
+        string avatar "avatar URL"
+        text accessToken "OAuth access token"
+        text refreshToken "OAuth refresh token"
+        datetime expiresAt "token expiration"
+        datetime createdAt "creation timestamp"
+        datetime updatedAt "last update timestamp"
+    }
+
+    MFADevice {
+        string id PK "cuid primary key"
+        string userId FK "user reference"
+        enum type "MFA type (TOTP/WEBAUTHN)"
+        string name "device name"
+        string secret "TOTP secret"
+        string credentialId "WebAuthn credential ID"
+        text publicKey "WebAuthn public key"
+        int counter "WebAuthn counter"
+        boolean isActive "device active flag"
+        datetime lastUsedAt "last use timestamp"
+        datetime createdAt "creation timestamp"
+    }
+
+    AuthEvent {
+        string id PK "cuid primary key"
+        string userId FK "user reference"
+        string eventType "event type"
+        json eventData "event details"
+        string ipAddress "IP address"
+        string userAgent "user agent string"
+        boolean success "success flag"
+        text errorMessage "error message"
+        datetime timestamp "event timestamp"
+    }
+
+    Policy {
+        string id PK "cuid primary key"
+        string name UK "unique policy name"
+        string description "policy description"
+        string resource "target resource"
+        json condition "policy conditions"
+        string effect "ALLOW or DENY"
+        int priority "evaluation priority"
+        boolean isActive "policy active flag"
+        string organizationId FK "organization reference"
+        datetime createdAt "creation timestamp"
+        datetime updatedAt "last update timestamp"
+    }
+
+    Organization {
+        string id PK "cuid primary key"
+        string name "organization name"
+        string domain UK "organization domain"
+        string parentId FK "parent organization ID"
+        json settings "organization settings"
+        boolean isActive "active flag"
+        datetime createdAt "creation timestamp"
+        datetime updatedAt "last update timestamp"
+    }
+
+    Group {
+        string id PK "cuid primary key"
+        string name "group name"
+        string organizationId FK "organization reference"
+        string description "group description"
+        boolean isActive "active flag"
+        datetime createdAt "creation timestamp"
+        datetime updatedAt "last update timestamp"
+    }
+
+    GroupMember {
+        string id PK "cuid primary key"
+        string userId FK "user reference"
+        string groupId FK "group reference"
+        string role "member role"
+        datetime joinedAt "join timestamp"
+        datetime expiresAt "expiration timestamp"
+    }
+
+    GroupPermission {
+        string id PK "cuid primary key"
+        string groupId FK "group reference"
+        string permissionId FK "permission reference"
+        datetime createdAt "creation timestamp"
+    }
+
+    UserProfile {
+        string id PK "cuid primary key"
+        string userId UK "user reference"
+        string firstName "first name"
+        string lastName "last name"
+        string phone "phone number"
+        boolean phoneVerified "phone verified flag"
+        string avatarUrl "avatar URL"
+        json customFields "custom attributes"
+        json preferences "user preferences"
+        json metadata "additional metadata"
+        datetime createdAt "creation timestamp"
+        datetime updatedAt "last update timestamp"
+    }
+
+    IdentityVerification {
+        string id PK "cuid primary key"
+        string userId FK "user reference"
+        enum type "verification type"
+        enum status "verification status"
+        string method "verification method"
+        string token UK "verification token"
+        datetime verifiedAt "verification timestamp"
+        datetime expiresAt "expiration timestamp"
+        json metadata "verification details"
+        datetime createdAt "creation timestamp"
+    }
+
+    AccessRequest {
+        string id PK "cuid primary key"
+        string userId FK "user reference"
+        string resource "target resource"
+        string action "requested action"
+        string reason "request reason"
+        enum status "request status"
+        datetime requestedAt "request timestamp"
+        datetime reviewedAt "review timestamp"
+        string reviewedBy "reviewer user ID"
+        datetime expiresAt "expiration timestamp"
+        json metadata "request metadata"
+    }
+
+    AccessRequestApprover {
+        string id PK "cuid primary key"
+        string requestId FK "request reference"
+        string approverId "approver user ID"
+        enum status "approval status"
+        string comments "approval comments"
+        datetime reviewedAt "review timestamp"
+    }
+
+    AccessReview {
+        string id PK "cuid primary key"
+        string name "review name"
+        string description "review description"
+        enum type "review type"
+        enum status "review status"
+        datetime startDate "start date"
+        datetime endDate "end date"
+        string createdBy "creator user ID"
+        datetime createdAt "creation timestamp"
+        datetime completedAt "completion timestamp"
+    }
+
+    AccessReviewItem {
+        string id PK "cuid primary key"
+        string reviewId FK "review reference"
+        string userId "target user ID"
+        string resource "target resource"
+        json access "current access details"
+        enum status "review item status"
+        string reviewedBy "reviewer user ID"
+        datetime reviewedAt "review timestamp"
+        string comments "review comments"
+    }
+
+    ComplianceReport {
+        string id PK "cuid primary key"
+        enum type "compliance type"
+        string name "report name"
+        datetime periodStart "period start"
+        datetime periodEnd "period end"
+        enum status "report status"
+        json data "report data"
+        datetime generatedAt "generation timestamp"
+        string generatedBy "generator user ID"
+        datetime createdAt "creation timestamp"
+        datetime updatedAt "last update timestamp"
+    }
+
+    PolicyTemplate {
+        string id PK "cuid primary key"
+        string name "template name"
+        enum category "policy category"
+        string description "template description"
+        json content "template structure"
+        string version "template version"
+        boolean isActive "active flag"
+        datetime createdAt "creation timestamp"
+        datetime updatedAt "last update timestamp"
+    }
+
+    RiskScore {
+        string id PK "cuid primary key"
+        string userId FK "user reference"
+        int score "risk score (0-100)"
+        enum level "risk level"
+        json factors "risk factors"
+        datetime calculatedAt "calculation timestamp"
+    }
+```
+
+---
+
+## Model Categories
+
+### 1. Core Authentication (7 models)
+
+**Purpose**: Handle user authentication, sessions, and security events.
+
+| Model | Purpose | Key Features |
+|-------|---------|--------------|
+| **User** | Core user entity | Email/username, password hash, MFA, active status |
+| **Session** | Active user sessions | Device tracking, fingerprinting, expiration |
+| **RefreshToken** | Long-lived tokens | Token rotation, family tracking, revocation |
+| **AuthEvent** | Audit log events | Event sourcing, compliance, troubleshooting |
+| **SocialAccount** | OAuth accounts | Google, Facebook, GitHub integration |
+| **MFADevice** | MFA devices | TOTP, WebAuthn support |
+| **Policy** | ABAC policies | JSON logic, conditions, priority |
+
+### 2. Authorization (6 models)
+
+**Purpose**: Manage roles, permissions, and access control.
+
+| Model | Purpose | Key Features |
+|-------|---------|--------------|
+| **Role** | Named collections of permissions | ADMIN, MANAGER, USER, custom roles |
+| **Permission** | Granular access rights | resource:action:scope format |
+| **UserRole** | User-role assignments | Expiration, temporary grants |
+| **RolePermission** | Role-permission mappings | Many-to-many relationship |
+| **UserPermission** | Direct user permissions | Override roles, grant/deny |
+| **GroupPermission** | Group permissions | Inherited by group members |
+
+### 3. Social & OIDC (2 models)
+
+**Purpose**: External authentication integration.
+
+| Model | Purpose | Key Features |
+|-------|---------|--------------|
+| **SocialAccount** | OAuth provider accounts | Access tokens, refresh tokens, profile |
+| **MFADevice** | Multi-factor auth devices | TOTP secrets, WebAuthn credentials |
+
+### 4. Identity Management (6 models)
+
+**Purpose**: User profiles, organizations, groups, verification.
+
+| Model | Purpose | Key Features |
+|-------|---------|--------------|
+| **Organization** | Multi-tenant organizations | Hierarchy, settings, isolation |
+| **Group** | User groups | Organization-scoped, permissions |
+| **GroupMember** | Group membership | Roles, expiration |
+| **UserProfile** | Extended user info | Name, phone, avatar, custom fields |
+| **IdentityVerification** | Email/phone/document verification | OTP tokens, status tracking |
+
+### 5. Access Management (4 models)
+
+**Purpose**: Access requests, reviews, analytics.
+
+| Model | Purpose | Key Features |
+|-------|---------|--------------|
+| **AccessRequest** | Access request workflows | Approval chains, expiration |
+| **AccessRequestApprover** | Multi-person approval | Approval status, comments |
+| **AccessReview** | Access certification campaigns | Periodic, adhoc, certification |
+| **AccessReviewItem** | Individual review items | Approve, revoke, no change |
+
+### 6. Governance (3 models)
+
+**Purpose**: Compliance, policies, risk management.
+
+| Model | Purpose | Key Features |
+|-------|---------|--------------|
+| **ComplianceReport** | GDPR, SOC2, ISO27001 reports | Period-based, generation |
+| **PolicyTemplate** | Reusable policy templates | Versioning, categories |
+| **RiskScore** | User risk scoring | Factors, levels, tracking |
+
+---
+
+## Core Authentication Models
+
+### User Model
+
+```typescript
+model User {
+  id            String    @id @default(cuid())
+  email         String    @unique
+  username      String?   @unique
+  passwordHash  String?   // Nullable for social-only users
+  isActive      Boolean   @default(true)
+  emailVerified Boolean   @default(false)
+  mfaEnabled    Boolean   @default(false)
+  mfaSecret     String?
+  lastLoginAt   DateTime?
+  loginCount    Int       @default(0)
+  organizationId String?
+  createdAt     DateTime  @default(now())
+  updatedAt     DateTime  @updatedAt
+}
+```
+
+**Key Features**:
+- Primary identifier: `id` (CUID for distributed generation)
+- Unique constraints: `email`, `username`
+- Password hashing: bcrypt (cost factor 12)
+- MFA support: TOTP secret stored
+- Audit fields: `lastLoginAt`, `loginCount`
+- Soft delete: `isActive` flag
+
+### Session Model
+
+```typescript
+model Session {
+  id             String   @id @default(cuid())
+  userId         String
+  deviceId       String
+  deviceName     String?
+  ipAddress      String
+  userAgent      String?
+  fingerprint    String?  // Device fingerprint
+  isActive       Boolean  @default(true)
+  expiresAt      DateTime
+  createdAt      DateTime @default(now())
+  lastActivityAt DateTime @default(now())
+}
+```
+
+**Key Features**:
+- Device tracking: `deviceId`, `deviceName`, `fingerprint`
+- Security: IP address, user agent tracking
+- Activity monitoring: `lastActivityAt`
+- Expiration: Auto-expire based on `expiresAt`
+
+### RefreshToken Model
+
+```typescript
+model RefreshToken {
+  id         String    @id @default(cuid())
+  userId     String
+  token      String    @unique
+  family     String?   // Token family for rotation
+  deviceId   String?
+  ipAddress  String?
+  userAgent  String?
+  expiresAt  DateTime
+  revokedAt  DateTime?
+  createdAt  DateTime  @default(now())
+}
+```
+
+**Key Features**:
+- Token rotation: `family` for tracking token generations
+- Security: Revocation support with `revokedAt`
+- Device binding: Optional `deviceId` tracking
+- Long-lived: 7-day expiration
+
+### AuthEvent Model (Audit Log)
+
+```typescript
+model AuthEvent {
+  id           String   @id @default(cuid())
+  userId       String?
+  eventType    String   // LOGIN, LOGOUT, MFA_ENABLED, etc.
+  eventData    Json
+  ipAddress    String?
+  userAgent    String?
+  success      Boolean  @default(true)
+  errorMessage String?  @db.Text
+  timestamp    DateTime @default(now())
+}
+```
+
+**Key Features**:
+- Event sourcing: All auth events logged
+- Compliance: GDPR, SOC2 audit trail
+- Troubleshooting: Success/failure tracking
+- Flexible: JSON `eventData` for any event type
+
+---
+
+## Authorization Models
+
+### RBAC Relationship
+
+```mermaid
+graph LR
+    User[User<br/>alice@example.com] --> UserRole[UserRole<br/>Assignment]
+
+    UserRole --> Role[Role<br/>ADMIN]
+
+    Role --> RolePerm1[RolePermission]
+    Role --> RolePerm2[RolePermission]
+
+    RolePerm1 --> Perm1[Permission<br/>users:*:all]
+    RolePerm2 --> Perm2[Permission<br/>products:*:all]
+
+    User --> DirectPerm[UserPermission<br/>Direct Override]
+    DirectPerm --> Perm3[Permission<br/>analytics:read:all]
+
+    style User fill:#e1f5fe
+    style Role fill:#f3e5f5
+    style Perm1 fill:#fff3e0
+    style Perm2 fill:#fff3e0
+    style Perm3 fill:#ffccbc
+```
+
+### Permission Model
+
+**Format**: `resource:action:scope`
+
+```typescript
+model Permission {
+  id          String   @id @default(cuid())
+  resource    String   // users, products, orders
+  action      String   // create, read, update, delete
+  scope       String?  // own, team, all
+  description String?
+  createdAt   DateTime @default(now())
+
+  @@unique([resource, action, scope])
+}
+```
+
+**Examples**:
+- `users:read:all` - Read all users
+- `users:update:own` - Update own profile
+- `orders:delete:all` - Delete any order (admin)
+
+### UserRole Model (with Expiration)
+
+```typescript
+model UserRole {
+  id        String   @id @default(cuid())
+  userId    String
+  roleId    String
+  grantedBy String?  // Who granted this role
+  expiresAt DateTime? // Temporary assignment
+  createdAt DateTime @default(now())
+
+  @@unique([userId, roleId])
+}
+```
+
+**Key Features**:
+- Temporary roles: `expiresAt` for time-limited access
+- Audit trail: `grantedBy` tracks who assigned role
+- Unique constraint: One assignment per user-role pair
+
+---
+
+## Social & OIDC Models
+
+### SocialAccount Model
+
+```typescript
+model SocialAccount {
+  id           String   @id @default(cuid())
+  userId       String
+  provider     Provider // GOOGLE, FACEBOOK, GITHUB
+  providerId   String   // ID from provider
+  email        String?
+  name         String?
+  avatar       String?
+  accessToken  String?  @db.Text
+  refreshToken String?  @db.Text
+  expiresAt    DateTime?
+  createdAt    DateTime @default(now())
+  updatedAt    DateTime @updatedAt
+
+  @@unique([provider, providerId])
+}
+
+enum Provider {
+  GOOGLE
+  FACEBOOK
+  GITHUB
+  APPLE
+  MICROSOFT
+}
+```
+
+**Key Features**:
+- Multiple providers per user
+- Token storage for API calls
+- Profile information caching
+- Unique per provider-providerId
+
+---
+
+## Identity Management Models
+
+### Organization Hierarchy
+
+```mermaid
+graph TD
+    RootOrg[Organization<br/>Acme Corp]
+
+    RootOrg --> Div1[Organization<br/>Engineering]
+    RootOrg --> Div2[Organization<br/>Sales]
+
+    Div1 --> Team1[Organization<br/>Frontend Team]
+    Div1 --> Team2[Organization<br/>Backend Team]
+
+    Div2 --> Team3[Organization<br/>North America]
+    Div2 --> Team4[Organization<br/>Europe]
+
+    Team1 --> User1[User: Alice]
+    Team1 --> User2[User: Bob]
+    Team2 --> User3[User: Charlie]
+
+    style RootOrg fill:#e1f5fe
+    style Div1 fill:#fff3e0
+    style Div2 fill:#fff3e0
+    style Team1 fill:#e8f5e9
+    style Team2 fill:#e8f5e9
+```
+
+### Organization Model
+
+```typescript
+model Organization {
+  id       String   @id @default(cuid())
+  name     String
+  domain   String?  @unique
+  parentId String?  // Self-referencing hierarchy
+  settings Json?
+  isActive Boolean  @default(true)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  // Self-referencing relationship
+  parent   Organization?  @relation("OrganizationHierarchy", fields: [parentId], references: [id])
+  children Organization[] @relation("OrganizationHierarchy")
+}
+```
+
+**Key Features**:
+- Hierarchical structure (parent-child)
+- Domain-based organization
+- Custom settings (JSON)
+- Multi-tenancy support
+
+### Group Model
+
+```typescript
+model Group {
+  id             String   @id @default(cuid())
+  name           String
+  organizationId String?
+  description    String?
+  isActive       Boolean  @default(true)
+  createdAt      DateTime @default(now())
+  updatedAt      DateTime @updatedAt
+
+  members     GroupMember[]
+  permissions GroupPermission[]
+
+  @@unique([organizationId, name])
+}
+```
+
+**Key Features**:
+- Organization-scoped groups
+- Members and permissions
+- Unique names within organization
+
+### UserProfile Model
+
+```typescript
+model UserProfile {
+  id            String   @id @default(cuid())
+  userId        String   @unique
+  firstName     String?
+  lastName      String?
+  phone         String?
+  phoneVerified Boolean  @default(false)
+  avatarUrl     String?
+  customFields  Json?    // Extended attributes
+  preferences   Json?    // User preferences
+  metadata      Json?    // Additional data
+  createdAt     DateTime @default(now())
+  updatedAt     DateTime @updatedAt
+}
+```
+
+**Key Features**:
+- Extended user information
+- Custom fields (JSON) for flexibility
+- Phone verification support
+- Avatar management
+
+---
+
+## Access Management Models
+
+### Access Request Workflow
+
+```mermaid
+stateDiagram-v2
+    [*] --> PENDING: User creates request
+
+    PENDING --> APPROVED: All approvers approve
+    PENDING --> REJECTED: Any approver rejects
+    PENDING --> CANCELLED: User cancels
+    PENDING --> EXPIRED: Timeout
+
+    APPROVED --> [*]: Access granted
+    REJECTED --> [*]: Access denied
+    CANCELLED --> [*]: Request cancelled
+    EXPIRED --> [*]: Request expired
+```
+
+### AccessRequest Model
+
+```typescript
+model AccessRequest {
+  id         String   @id @default(cuid())
+  userId     String
+  resource   String
+  action     String
+  reason     String?
+  status     RequestStatus @default(PENDING)
+  requestedAt DateTime @default(now())
+  reviewedAt  DateTime?
+  reviewedBy  String?
+  expiresAt   DateTime?
+  metadata    Json?
+
+  approvers AccessRequestApprover[]
+}
+
+enum RequestStatus {
+  PENDING
+  APPROVED
+  REJECTED
+  EXPIRED
+  CANCELLED
+}
+```
+
+**Key Features**:
+- Multi-person approval support
+- Expiration for temporary access
+- Metadata for custom workflows
+- Audit trail (reviewedBy, reviewedAt)
+
+---
+
+## Governance Models
+
+### ComplianceReport Model
+
+```typescript
+model ComplianceReport {
+  id          String   @id @default(cuid())
+  type        ComplianceType
+  name        String
+  periodStart DateTime
+  periodEnd   DateTime
+  status      ReportStatus @default(DRAFT)
+  data        Json?
+  generatedAt DateTime?
+  generatedBy String?
+  createdAt   DateTime @default(now())
+  updatedAt   DateTime @updatedAt
+}
+
+enum ComplianceType {
+  GDPR      // General Data Protection Regulation
+  SOC2      // Service Organization Control 2
+  ISO27001  // Information Security Management
+  HIPAA     // Health Insurance Portability and Accountability Act
+  CUSTOM    // Custom compliance framework
+}
+
+enum ReportStatus {
+  DRAFT
+  GENERATED
+  PUBLISHED
+  ARCHIVED
+}
+```
+
+**Key Features**:
+- Multiple compliance frameworks
+- Period-based reporting
+- Status tracking
+- Flexible data structure (JSON)
+
+### RiskScore Model
+
+```typescript
+model RiskScore {
+  id          String   @id @default(cuid())
+  userId      String
+  score       Int      // 0-100
+  level       RiskLevel
+  factors     Json     // Risk factors
+  calculatedAt DateTime @default(now())
+}
+
+enum RiskLevel {
+  LOW
+  MEDIUM
+  HIGH
+  CRITICAL
+}
+```
+
+**Risk Factors** (in JSON):
+```json
+{
+  "failedLogins": 3,
+  "unusualLocation": true,
+  "newDevice": true,
+  "highPrivilegeAccess": false,
+  "inactivityDays": 45,
+  "openAccessRequests": 2
+}
+```
+
+---
+
+## Relationships & Constraints
+
+### Primary Relationships
+
+```
+User (1) ───< UserRole (many) >─── Role (1)
+User (1) ───< UserPermission (many) >─── Permission (1)
+Role (1) ───< RolePermission (many) >─── Permission (1)
+Group (1) ───< GroupPermission (many) >─── Permission (1)
+Group (1) ───< GroupMember (many) >─── User (1)
+Organization (1) ───< User (many)
+Organization (1) ───< Group (many)
+Organization (1) ───< Organization (many) [self-referencing]
+User (1) ──── UserProfile (1) [one-to-one]
+User (1) ───< Session (many)
+User (1) ───< RefreshToken (many)
+User (1) ───< SocialAccount (many)
+User (1) ───< MFADevice (many)
+User (1) ───< AccessRequest (many)
+AccessRequest (1) ───< AccessRequestApprover (many)
+AccessReview (1) ───< AccessReviewItem (many)
+```
+
+### Unique Constraints
+
+| Model | Unique Constraint | Purpose |
+|-------|------------------|---------|
+| User | email | One email per user |
+| User | username | One username per user |
+| Role | name | One role name |
+| Permission | [resource, action, scope] | One permission per resource-action-scope |
+| UserRole | [userId, roleId] | One assignment per user-role |
+| Organization | domain | One organization per domain |
+| Group | [organizationId, name] | Unique names within organization |
+| SocialAccount | [provider, providerId] | One account per provider-providerId |
+
+### Cascade Deletes
+
+**ON DELETE CASCADE**:
+- User deleted → Delete all UserRoles, Sessions, RefreshTokens, etc.
+- Role deleted → Delete all RolePermissions
+- Organization deleted → Set users' organizationId to null
+- Group deleted → Delete all GroupMembers
+
+**ON DELETE SET NULL**:
+- Organization deleted → Users remain, organizationId set to null
+- AuthEvent user deleted → Event remains, userId set to null (for audit)
+
+---
+
+## Data Lifecycle
+
+### User Lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> Created: register()
+
+    Created --> Active: Email verified
+    Created --> Inactive: Never verified
+
+    Active --> Deactivated: Deactivate account
+    Active --> Locked: Too many failed logins
+    Active --> MFAEnabled: Enable MFA
+
+    Deactivated --> Active: Reactivate
+    Locked --> Active: Unlock after timeout
+    MFAEnabled --> Active: Disable MFA
+
+    Active --> Deleted: Delete account (soft)
+    Deactivated --> Deleted: Delete account
+
+    Deleted --> [*]: Hard delete after retention period
+```
+
+### Session Lifecycle
+
+1. **Created**: User logs in → Session created
+2. **Active**: Session valid, user making requests
+3. **Inactive**: No activity for extended period
+4. **Expired**: Past `expiresAt` timestamp
+5. **Revoked**: User logs out or admin revokes
+6. **Deleted**: Cleanup job removes expired sessions
+
+### Permission Lifecycle
+
+1. **Created**: Admin creates new permission
+2. **Assigned**: Permission granted to roles/users/groups
+3. **Cached**: Permission cached in Redis (5min TTL)
+4. **Checked**: Permission verified on resource access
+5. **Revoked**: Permission removed from role/user/group
+6. **Invalidated**: Cache cleared on permission change
+
+---
+
+## Indexing Strategy
+
+### Performance Indexes
+
+| Model | Index Columns | Purpose |
+|-------|--------------|---------|
+| User | email | Fast login lookup |
+| User | username | Username lookup |
+| User | organizationId | Tenant filtering |
+| Session | userId | User's sessions |
+| Session | deviceId | Device tracking |
+| Session | expiresAt | Cleanup job |
+| RefreshToken | userId | User's tokens |
+| RefreshToken | token | Token lookup |
+| RefreshToken | family | Token rotation |
+| AuthEvent | [userId, timestamp] | User audit trail |
+| AuthEvent | [eventType, timestamp] | Event type queries |
+| UserRole | userId | User's roles |
+| UserRole | roleId | Role members |
+| UserRole | expiresAt | Expiration cleanup |
+| Permission | resource | Resource permissions |
+| AccessRequest | userId | User's requests |
+| AccessRequest | status | Pending requests |
+
+### Composite Indexes
+
+For efficient querying:
+- `AuthEvent(userId, timestamp)` - User audit logs ordered by time
+- `UserRole(userId, expiresAt)` - Active roles for user
+- `Session(userId, isActive, expiresAt)` - Active sessions for user
+
+---
+
+## Database Migrations
+
+### Migration Strategy
+
+1. **Forward-only migrations**: Never rollback, always migrate forward
+2. **Non-destructive changes**: Add columns as nullable, then backfill
+3. **Zero-downtime**: Multi-phase migrations for production
+4. **Versioning**: Prisma migration history in `_prisma_migrations` table
+
+### Example Migration Phases
+
+**Phase 1 - Add column**:
+```sql
+ALTER TABLE users ADD COLUMN new_field VARCHAR(255);
+```
+
+**Phase 2 - Backfill data**:
+```sql
+UPDATE users SET new_field = 'default_value' WHERE new_field IS NULL;
+```
+
+**Phase 3 - Make required**:
+```sql
+ALTER TABLE users ALTER COLUMN new_field SET NOT NULL;
+```
+
+---
+
+## Data Retention
+
+| Data Type | Retention Period | Cleanup Strategy |
+|-----------|-----------------|------------------|
+| Active Users | Indefinite | Soft delete |
+| Inactive Users | 2 years | Hard delete |
+| Sessions | 30 days after expiry | Automatic cleanup |
+| Refresh Tokens | 7 days after expiry | Automatic cleanup |
+| AuthEvents | 7 years | Compliance requirement |
+| Access Requests | 3 years | Compliance requirement |
+| Compliance Reports | 7 years | Legal requirement |
+| Risk Scores | 1 year | Rolling window |
+
+---
+
+## Next Steps
+
+- **[ARCHITECTURE.md](../ARCHITECTURE.en.md)** - System architecture and flows
+- **[CORE-CONCEPTS.md](./CORE-CONCEPTS.md)** - IAM fundamentals
+- **[SECURITY-MODEL.md](./SECURITY-MODEL.md)** - Security architecture
+- **[API Reference](../API_REFERENCE.md)** - API endpoints
+
+---
+
+## Reference Files
+
+- **Prisma Schema**: [prisma/schema.prisma](../../prisma/schema.prisma)
+- **Repositories**: [src/repositories/](../../src/repositories/)
+- **Migrations**: [prisma/migrations/](../../prisma/migrations/)
+
+---
+
+**Last Updated**: January 2026
+**Version**: 1.0.0
+**Status**: Production Ready