# SerpentRace Backend API Documentation for Frontend Developers

## Table of Contents
1. [Test User Credentials](#test-user-credentials)
2. [Data Structures & Entities](#data-structures--entities)
3. [Authentication Endpoints](#authentication-endpoints)
4. [User Management](#user-management)
5. [Deck Management](#deck-management)
6. [Organization Management](#organization-management)
7. [Chat System](#chat-system)
8. [Contact Management](#contact-management)
9. [Admin Endpoints](#admin-endpoints)
10. [Import/Export Functionality](#importexport-functionality)
11. [Error Handling](#error-handling)
12. [WebSocket Events](#websocket-events)

---

## Test User Credentials

For development and testing, use these pre-configured user accounts:

### Regular User (Verified)
- **Username:** `john_doe`
- **Password:** `password123`
- **Email:** `john.doe@email.com`
- **Type:** Regular user (state: 1 - VERIFIED_REGULAR)
- **Organization:** None

### Premium User (Organization Member)
- **Username:** `jane_premium`
- **Password:** `password123`
- **Email:** `jane.smith@email.com`
- **Type:** Premium user (state: 2 - VERIFIED_PREMIUM)
- **Organization:** Tech Solutions Inc

### Teacher (Premium Organization Member)
- **Username:** `teacher_bob`
- **Password:** `password123`
- **Email:** `bob.teacher@eduinst.edu`
- **Type:** Premium user (state: 2 - VERIFIED_PREMIUM)
- **Organization:** Educational Institute

### Admin User
- **Username:** `admin_user`
- **Password:** `password123`
- **Email:** `admin@serpentrace.com`
- **Type:** Admin (state: 5 - ADMIN)
- **Organization:** None

### Unverified User
- **Username:** `new_user`
- **Password:** `password123`
- **Email:** `newuser@email.com`
- **Type:** Unverified (state: 0 - REGISTERED_NOT_VERIFIED)
- **Organization:** None

---

## Data Structures & Entities

### User Entity
```typescript
interface User {
  id: string;                    // UUID
  orgid: string | null;          // Organization ID (if member)
  username: string;              // Unique username
  email: string;                 // Unique email
  fname: string;                 // First name
  lname: string;                 // Last name
  type: string;                  // 'personal' | 'premium' | 'admin'
  phone: string | null;          // Phone number
  state: UserState;              // User status (see enum below)
  regdate: Date;                 // Registration date
  updatedate: Date;              // Last update
  Orglogindate: Date | null;     // Last organization login
}

enum UserState {
  REGISTERED_NOT_VERIFIED = 0,  // Email not verified
  VERIFIED_REGULAR = 1,          // Regular verified user
  VERIFIED_PREMIUM = 2,          // Premium verified user  
  SOFT_DELETE = 3,               // Soft deleted
  DEACTIVATED = 4,               // Account deactivated
  ADMIN = 5                      // Admin user
}
```

### Deck Entity
```typescript
interface Deck {
  id: string;                    // UUID
  name: string;                  // Deck name
  type: DeckType;                // Deck type (see enum)
  userid: string;                // Owner's user ID
  creationdate: Date;            // Creation timestamp
  cards: Card[];                 // Array of cards
  playedNumber: number;          // Times played
  ctype: DeckVisibility;         // Visibility type
  updatedate: Date;              // Last update
  state: DeckState;              // Deck status
  organization: Organization | null; // Organization reference
}

enum DeckType {
  LUCK = 0,                      // Luck-based cards
  JOKER = 1,                     // Joker/wild cards
  QUESTION = 2                   // Question-based cards
}

enum DeckVisibility {
  PUBLIC = 0,                    // Public to all
  PRIVATE = 1,                   // Private to owner
  ORGANIZATION = 2               // Shared within organization
}

enum DeckState {
  ACTIVE = 0,                    // Active deck
  SOFT_DELETE = 1                // Soft deleted
}

interface Card {
  id: string;                    // Card ID
  type: CardType;                // Type of card
  text: string;                  // Question/prompt text
  answer?: string | boolean | null; // Answer (varies by type)
  options?: string[];            // Multiple choice options
}

enum CardType {
  QUIZ = 0,                      // Multiple choice question
  SENTENCE_PAIRING = 1,          // Sentence completion
  OWN_ANSWER = 2,                // Open-ended question
  TRUE_FALSE = 3,                // True/false question
  CLOSER = 4                     // closer to answer
}
```

### Organization Entity
```typescript
interface Organization {
  id: string;                    // UUID
  name: string;                  // Organization name
  contactfname: string;          // Contact first name
  contactlname: string;          // Contact last name
  contactphone: string;          // Contact phone
  contactemail: string;          // Contact email
  state: OrganizationState;      // Organization status
  regdate: Date;                 // Registration date
  updatedate: Date;              // Last update
  url: string | null;            // Organization website
  userinorg: number;             // User count in org
  maxOrganizationalDecks: number | null; // Max org decks allowed
}

enum OrganizationState {
  REGISTERED = 0,                // Just registered
  ACTIVE = 1,                    // Active organization
  SOFT_DELETE = 2                // Soft deleted
}
```

### Chat Entity
```typescript
interface Chat {
  id: string;                    // UUID
  type: ChatType;                // Chat type
  name: string | null;           // Group/game name
  gameId: string | null;         // Associated game ID
  createdBy: string | null;      // Creator's user ID
  users: string[];               // Participant user IDs
  messages: Message[];           // Chat messages
  lastActivity: Date | null;     // Last message time
  createDate: Date;              // Chat creation date
  updateDate: Date;              // Last update
  state: ChatState;              // Chat status
  archiveDate: Date | null;      // Archive date
}

interface Message {
  id: string;                    // Message ID
  date: Date;                    // Message timestamp
  userid: string;                // Sender's user ID
  text: string;                  // Message content
}

enum ChatType {
  DIRECT = 'direct',             // Direct message
  GROUP = 'group',               // Group chat
  GAME = 'game'                  // Game-specific chat
}

enum ChatState {
  ACTIVE = 0,                    // Active chat
  ARCHIVE = 1,                   // Archived chat
  SOFT_DELETE = 2                // Soft deleted
}
```

### Contact Entity
```typescript
interface Contact {
  id: string;                    // UUID
  name: string;                  // Contact name
  email: string;                 // Contact email
  userid: string | null;         // Associated user ID
  type: ContactType;             // Contact type
  txt: string;                   // Message text
  state: ContactState;           // Contact status
  createDate: Date;              // Creation date
  updateDate: Date;              // Last update
  adminResponse: string | null;  // Admin response
  responseDate: Date | null;     // Response date
  respondedBy: string | null;    // Responding admin ID
}

enum ContactType {
  BUG = 0,                       // Bug report
  PROBLEM = 1,                   // Problem report
  QUESTION = 2,                  // General question
  SALES = 3,                     // Sales inquiry
  OTHER = 4                      // Other type
}

enum ContactState {
  ACTIVE = 0,                    // Active/unresolved
  RESOLVED = 1,                  // Resolved
  SOFT_DELETE = 2                // Soft deleted
}
```

---

## Authentication Endpoints

### User Login
**Endpoint:** `POST /api/users/login`

**Description:** Authenticate user with username or Email and password

**Request Data:**
```typescript
{
  username: string;    // 3-50 characters
  password: string;    // 6-100 characters
}
```

**Response Data (Success):**
```typescript
{
  token: string;                 // JWT authentication token its safed in cookie its just a copy
  user: {
    id: string;
    username: string;
    email: string;
    fname: string;
    lname: string;
    type: string;
    state: number;
    orgid: string | null;
  };
  requiresOrgReauth?: boolean;   // If org re-auth needed
  orgLoginUrl?: string;          // Organization auth URL
  organizationName?: string;     // Organization name
}
```

**Error Responses:**
- `401`: Invalid credentials, unverified email, or account restrictions
- `400`: Validation error (missing fields, invalid length)
- `500`: Internal server error

**Account State Restrictions:**
Users cannot login if their account state is:
- `0` (REGISTERED_NOT_VERIFIED): Email verification required
- `3` (SOFT_DELETE): Account has been deleted
- `4` (DEACTIVATED): Account has been deactivated

**Successful Login States:**
- `1` (VERIFIED_REGULAR): Regular user can login
- `2` (VERIFIED_PREMIUM): Premium user can login  
- `5` (ADMIN): Admin user can login

**Example Usage:**
```typescript
const loginUser = async (username: string, password: string) => {
  const response = await fetch('/api/users/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ username, password })
  });
  
  if (response.ok) {
    const data = await response.json();
    localStorage.setItem('auth_token', data.token);
    return data;
  }
  throw new Error('Login failed');
};
```

### User Registration
**Endpoint:** `POST /api/users/create`

**Description:** Create new user account

**Request Data:**
```typescript
{
  username: string;    // 3-50 characters, unique
  email: string;       // Valid email format, unique
  password: string;    // 6-100 characters
  fname: string;       // First name
  lname: string;       // Last name
  type?: string;       // 'personal' | 'premium' (default: 'personal')
  phone?: string;      // Optional phone number
}
```

**Response Data (Success):**
```typescript
{
  id: string;
  username: string;
  email: string;
  fname: string;
  lname: string;
  type: string;
  state: 0;           // REGISTERED_NOT_VERIFIED
  regdate: Date;
}
```

**Error Responses:**
- `409`: Username or email already exists
- `400`: Validation error
- `500`: Internal server error

---

## User Management

### Get User Profile
**Endpoint:** `GET /api/users/profile`

**Authentication:** Required (Bearer token)

**Description:** Get current user's profile information

**Request Data:** None (user ID from JWT token)

**Response Data:**
```typescript
{
  id: string;
  orgid: string | null;
  username: string;
  email: string;
  fname: string;
  lname: string;
  code: string | null;      // Verification token
  type: string;
  phone: string | null;
  state: number;
}
```

### Update User Profile
**Endpoint:** `PATCH /api/users/profile`

**Authentication:** Required (Bearer token)

**Description:** Update current user's profile

**Request Data:**
```typescript
{
  fname?: string;
  lname?: string;
  email?: string;
  phone?: string;
  // Other updatable fields
}
```

**Response Data:** Updated user object (same as GET profile)

**Error Responses:**
- `409`: Email already exists
- `400`: Validation error
- `404`: User not found

---

## Deck Management

### Get Decks (Paginated) - RECOMMENDED
**Endpoint:** `GET /api/decks/page/{from}/{to}`

**Authentication:** Required (Bearer token)

**Description:** Get user's accessible decks with pagination

**URL Parameters:**
- `from`: Start index (0-based)
- `to`: End index (inclusive)

**Response Data:**
```typescript
{
  decks: ShortDeckDto[];
  totalCount: number;
}

interface ShortDeckDto {
  id: string;
  name: string;
  type: number;              // DeckType enum
  playedNumber: number;
  ctype: number;             // DeckVisibility enum
}
```

**Deck Access Rules:**
- Regular users: Own private decks + all public decks
- Premium users: Above + organization decks from their org
- Admins: All decks

### Get All Decks - DEPRECATED
**Endpoint:** `GET /api/decks`

**Authentication:** Required (Bearer token)

**Description:** Get all accessible decks (deprecated, use paginated version)

**Response:** Array of `ShortDeckDto`

### Create Deck
**Endpoint:** `POST /api/decks`

**Authentication:** Required (Bearer token)

**Description:** Create a new deck

**Request Data:**
```typescript
{
  name: string;                 // Deck name
  type: DeckType;               // 0=LUCK, 1=JOKER, 2=QUESTION
  cards: Card[];                // Array of cards
  ctype?: DeckVisibility;       // Default: PUBLIC (0)
  userid: string;               // Auto-filled from token
}
```

**Response Data:** `ShortDeckDto`

**Deck Limits:**
- Regular users: 8 decks max
- Premium users: 12 decks max
- Only premium users can create organizational decks
- Organization deck limits set by admin

### Get Deck by ID
**Endpoint:** `GET /api/decks/{id}`

**Authentication:** Required (Bearer token)

**Description:** Get detailed deck information

**Response Data:**
```typescript
{
  id: string;
  name: string;
  type: number;
  userid: string;
  creationdate: Date;
  cards: Card[];
  playedNumber: number;
  ctype: number;
}
```

### Update Deck
**Endpoint:** `PUT /api/decks/{id}`

**Authentication:** Required (Bearer token)

**Description:** Update existing deck (owner only)

**Request Data:** Partial deck data to update

**Response Data:** Updated `ShortDeckDto`

### Delete Deck
**Endpoint:** `DELETE /api/decks/{id}`

**Authentication:** Required (Bearer token)

**Description:** Delete deck (owner only)

**Response:** `204 No Content`

### Search Decks
**Endpoint:** `GET /api/decks/search`

**Authentication:** Required (Bearer token)

**Description:** Search decks by name or content

**Query Parameters:**
- `q`: Search query (required)
- `limit`: Results limit (1-100, default: 20)
- `offset`: Results offset (default: 0)

**Response Data:** Array of matching decks

---

## Organization Management

### Get Organizations (Paginated)
**Endpoint:** `GET /api/organizations/page/{from}/{to}`

**Authentication:** Required (Bearer token)

**Description:** Get organizations with pagination

**Response Data:**
```typescript
{
  organizations: ShortOrganizationDto[];
  totalCount: number;
}

interface ShortOrganizationDto {
  id: string;
  name: string;
  state: number;
  userinorg: number;
  maxOrganizationalDecks?: number | null;
}
```

### Get All Organizations - DEPRECATED
**Endpoint:** `GET /api/organizations`

**Authentication:** Required (Bearer token)

### Create Organization
**Endpoint:** `POST /api/organizations`

**Authentication:** Required (Bearer token)

**Request Data:**
```typescript
{
  name: string;
  contactfname: string;
  contactlname: string;
  contactphone: string;
  contactemail: string;
  description?: string;
  maxOrganizationalDecks?: number;
}
```

### Get Organization by ID
**Endpoint:** `GET /api/organizations/{id}`

**Authentication:** Required (Bearer token)

**Response Data:**
```typescript
{
  id: string;
  name: string;
  contactfname: string;
  contactlname: string;
  contactphone: string;
  contactemail: string;
  state: number;
  regdate: Date;
  updatedate: Date;
  url: string | null;
  userinorg: number;
  maxOrganizationalDecks: number | null;
  users: string[];               // User IDs
}
```

### Update Organization
**Endpoint:** `PUT /api/organizations/{id}`

**Authentication:** Required (Bearer token)

### Delete Organization
**Endpoint:** `DELETE /api/organizations/{id}`

**Authentication:** Required (Bearer token)

---

## Chat System

### Get User Chats
**Endpoint:** `GET /api/chats/user-chats`

**Authentication:** Required (Bearer token)

**Description:** Get all chats for current user

**Query Parameters:**
- `includeArchived`: boolean (default: false)

**Response Data:**
```typescript
ShortChatDto[]

interface ShortChatDto {
  id: string;
  userCount: number;
  state: number;
}
```

### Get Chat History
**Endpoint:** `GET /api/chats/history/{chatId}`

**Authentication:** Required (Bearer token)

**Description:** Get detailed chat with message history

**Response Data:**
```typescript
{
  id: string;
  users: string[];              // Participant user IDs
  messages: Message[];
  updateDate: Date;
  state: number;
}
```

### Create Chat
**Endpoint:** `POST /api/chats`

**Authentication:** Required (Bearer token)

**Request Data:**
```typescript
{
  users: string[];              // Participant user IDs
  type?: string;                // 'direct' | 'group' | 'game'
  name?: string;                // Group/game name
  gameId?: string;              // Associated game ID
}
```

### Send Message
**Endpoint:** `POST /api/chats/{chatId}/message`

**Authentication:** Required (Bearer token)

**Request Data:**
```typescript
{
  text: string;                 // Message content
}
```

**Response Data:** Message object with generated ID and timestamp

---

## Contact Management

### Create Contact
**Endpoint:** `POST /api/contact`

**Authentication:** Optional (can be anonymous)

**Description:** Submit contact/support request

**Request Data:**
```typescript
{
  name: string;                 // Contact name
  email: string;                // Contact email
  type: ContactType;            // 0=BUG, 1=PROBLEM, 2=QUESTION, 3=SALES, 4=OTHER
  txt: string;                  // Message content
}
```

**Response Data:**
```typescript
{
  id: string;
  name: string;
  email: string;
  userid: string | null;        // If authenticated
  type: number;
  txt: string;
  state: 0;                     // ACTIVE
  createDate: Date;
  updateDate: Date;
}
```

**Contact Types:**
- `0` - Bug Report
- `1` - Problem Report  
- `2` - General Question
- `3` - Sales Inquiry
- `4` - Other

---

## Admin Endpoints

All admin endpoints require authentication with admin role (UserState.ADMIN = 5).

### Get Users (Paginated)
**Endpoint:** `GET /api/admin/users/page/{from}/{to}`

**Authentication:** Required (Admin only)

**Query Parameters:**
- `includeDeleted`: boolean (default: false)

**Response Data:**
```typescript
{
  users: DetailUserDto[];
  pagination: {
    from: number;
    to: number;
    returned: number;
    totalCount: number;
    includeDeleted: boolean;
  };
}
```

### Update User State
**Endpoint:** `PATCH /api/admin/users/{userId}/state`

**Authentication:** Required (Admin only)

**Request Data:**
```typescript
{
  state: UserState;             // New user state
}
```

### Get All Contacts
**Endpoint:** `GET /api/admin/contacts`

**Authentication:** Required (Admin only)

**Response Data:** Array of all contact submissions

### Respond to Contact
**Endpoint:** `POST /api/admin/contacts/{contactId}/response`

**Authentication:** Required (Admin only)

**Request Data:**
```typescript
{
  response: string;             // Admin response text
}
```

---

## Import/Export Functionality

### Export Deck
**Endpoint:** `GET /api/deck-import-export/export/{deckId}`

**Authentication:** Required (Bearer token)

**Description:** Export user's own deck as encrypted .spr file

**Response:** Binary file download

### Import Deck
**Endpoint:** `POST /api/deck-import-export/import`

**Authentication:** Required (Bearer token)

**Description:** Import deck from .spr file

**Request:** Multipart form data with file

**Response Data:** Created deck object

---

## Error Handling

### Standard Error Response Format
```typescript
{
  error: string;                // Error message
  details?: string;             // Additional details (validation errors)
  code?: string;                // Error code
}
```

### HTTP Status Codes
- `200` - Success
- `201` - Created
- `204` - No Content
- `400` - Bad Request (validation error)
- `401` - Unauthorized (authentication required)
- `403` - Forbidden (insufficient permissions)
- `404` - Not Found
- `409` - Conflict (duplicate data)
- `500` - Internal Server Error

### Common Error Scenarios

**Authentication Errors:**
```typescript
// Missing token
{ error: "Authentication required" }

// Invalid token
{ error: "Invalid or expired token" }

// Insufficient permissions
{ error: "Admin access required" }
```

**Validation Errors:**
```typescript
// Missing required fields
{ error: "Missing required fields: username, password" }

// Invalid field length
{ error: "Username must be between 3 and 50 characters" }

// Invalid email format
{ error: "Invalid email format" }
```

**Business Logic Errors:**
```typescript
// Deck limit exceeded
{ error: "Deck limit exceeded. Maximum 8 decks allowed for your account type." }

// Organization deck restrictions
{ error: "Only premium users can create organizational decks." }

// Ownership restrictions
{ error: "You can only modify your own decks." }
```

---

## WebSocket Real-Time Communication

### Connection & Authentication
Connect to WebSocket server with JWT authentication:

```typescript
import io from 'socket.io-client';

// Connect with JWT token
const socket = io('/', {
  auth: { 
    token: localStorage.getItem('auth_token') || 'your-jwt-token' 
  }
});

// Alternative: Pass token via cookie header
const socket = io('/', {
  extraHeaders: {
    cookie: `auth_token=${localStorage.getItem('auth_token')}`
  }
});
```

**Connection Events:**
```typescript
// Connection successful
socket.on('connect', () => {
  console.log('Connected to WebSocket server');
});

// Authentication failed
socket.on('connect_error', (error) => {
  console.error('WebSocket connection failed:', error.message);
  // Redirect to login or refresh token
});

// Disconnected
socket.on('disconnect', (reason) => {
  console.log('Disconnected:', reason);
});
```

### Chat Management Events

**Initial Chat List:**
```typescript
// Receive user's active chats on connection
socket.on('chats:list', (chats: Array<{
  id: string;
  type: 'direct' | 'group' | 'game';
  name?: string;
  gameId?: string;
  users: string[];
  lastActivity?: Date;
  unreadCount: number;
  isArchived: boolean;
}>) => {
  // Update chat list in UI
  setChatList(chats);
});
```

**Join/Leave Chat:**
```typescript
// Join a chat room
socket.emit('chat:join', { chatId: 'chat-uuid' });

// Confirmation of joining
socket.on('chat:joined', (data: {
  chatId: string;
  messages: Message[]; // Last 10 messages
}) => {
  // Load chat messages into UI
});

// Leave a chat room
socket.emit('chat:leave', { chatId: 'chat-uuid' });

// Confirmation of leaving
socket.on('chat:left', (data: { chatId: string }) => {
  // Update UI to show chat as inactive
});
```

**Send/Receive Messages:**
```typescript
// Send message to chat
socket.emit('message:send', {
  chatId: 'chat-uuid',
  message: 'Hello everyone!'
});

// Receive new message in chat
socket.on('message:received', (data: {
  chatId: string;
  message: {
    id: string;
    date: Date;
    userid: string;
    text: string;
  };
}) => {
  // Add message to chat UI
  addMessageToChat(data.chatId, data.message);
});
```

**Rate Limiting:**
- Maximum 100 messages per user per minute
- Exceeded limit returns error: `{ message: "Rate limit exceeded. Maximum 100 messages per minute allowed." }`

### Chat Creation Events

**Create Group Chat:**
```typescript
// Create group (premium users only)
socket.emit('group:create', {
  name: 'Study Group',
  userIds: ['user-1', 'user-2', 'user-3']
});

// Group created successfully
socket.on('group:created', (data: {
  chat: {
    id: string;
    type: 'group';
    name: string;
    createdBy: string;
    users: string[];
    messages: Message[];
  };
}) => {
  // Add new group to chat list
  addChatToList(data.chat);
});
```

**Create Direct Chat:**
```typescript
// Create direct message
socket.emit('chat:direct', {
  targetUserId: 'user-uuid'
});

// Direct chat created
socket.on('chat:direct:created', (data: {
  chat: {
    id: string;
    type: 'direct';
    users: string[];
    messages: Message[];
  };
}) => {
  // Add direct chat to list
});

// Direct chat already exists
socket.on('chat:direct:exists', (data: {
  chatId: string;
}) => {
  // Navigate to existing chat
});
```

**Create Game Chat:**
```typescript
// Create game-specific chat
socket.emit('game:chat:create', {
  gameId: 'game-uuid',
  gameName: 'Quiz Battle',
  playerIds: ['player-1', 'player-2']
});

// Game chat created
socket.on('game:chat:created', (data: {
  chat: {
    id: string;
    type: 'game';
    name: string;
    gameId: string;
    users: string[];
    messages: Message[];
  };
}) => {
  // Show game chat in UI
});

// Game chat already exists
socket.on('game:chat:exists', (data: {
  chatId: string;
}) => {
  // Use existing game chat
});
```

### Chat History & Archive

**Get Chat History:**
```typescript
// Request full chat history
socket.emit('chat:history', { chatId: 'chat-uuid' });

// Receive chat history (active chat)
socket.on('chat:history', (data: {
  chatId: string;
  messages: Message[];
  chatInfo: {
    type: 'direct' | 'group' | 'game';
    name?: string;
    gameId?: string;
    users: string[];
  };
}) => {
  // Display full chat history
});

// Receive archived chat history
socket.on('chat:history:archived', (data: {
  chatId: string;
  messages: Message[];
  chatType: 'direct' | 'group' | 'game';
  isGameChat: boolean;
}) => {
  // Display archived chat with read-only UI
});
```

### Message Management & Pruning

**Message Retention Rules:**
- **All chats**: Messages older than 2 weeks are automatically deleted
- **Direct & Game chats**: Maximum 10 messages per user kept
- **Group chats**: No per-user message limit (time limit only)
- **Archive**: Inactive chats (no activity for 30 minutes) are archived
- **Cleanup**: Archived messages are cleaned up after 4 weeks

### Error Handling

**WebSocket Error Events:**
```typescript
// General errors
socket.on('error', (error: { message: string }) => {
  console.error('WebSocket error:', error.message);
  
  // Common error messages:
  // - "Chat not found"
  // - "Unauthorized to join this chat"
  // - "Unauthorized to send message to this chat"
  // - "Message must be a non-empty string"
  // - "Premium subscription required to create groups"
  // - "Group name is required"
  // - "At least one member is required"
  // - "One or more users not found"
  // - "Target user not found"
  // - "Failed to join chat"
  // - "Failed to send message"
  // - "Failed to create group"
  // - "Failed to create direct chat"
  // - "Failed to create game chat"
  // - "Failed to get chat history"
  
  // Handle error in UI
  showErrorMessage(error.message);
});
```

### Complete WebSocket Implementation Example

```typescript
// hooks/useWebSocket.ts
import { useEffect, useRef, useState } from 'react';
import io, { Socket } from 'socket.io-client';

export const useWebSocket = () => {
  const socketRef = useRef<Socket | null>(null);
  const [isConnected, setIsConnected] = useState(false);
  const [chats, setChats] = useState<Chat[]>([]);

  useEffect(() => {
    const token = localStorage.getItem('auth_token');
    if (!token) return;

    // Connect to WebSocket
    socketRef.current = io('/', {
      auth: { token }
    });

    const socket = socketRef.current;

    // Connection events
    socket.on('connect', () => {
      console.log('Connected to WebSocket');
      setIsConnected(true);
    });

    socket.on('connect_error', (error) => {
      console.error('Connection failed:', error.message);
      setIsConnected(false);
    });

    socket.on('disconnect', () => {
      console.log('Disconnected from WebSocket');
      setIsConnected(false);
    });

    // Chat events
    socket.on('chats:list', (chatList) => {
      setChats(chatList);
    });

    socket.on('message:received', (data) => {
      setChats(prev => prev.map(chat => 
        chat.id === data.chatId 
          ? { ...chat, messages: [...chat.messages, data.message] }
          : chat
      ));
    });

    socket.on('chat:joined', (data) => {
      console.log('Joined chat:', data.chatId);
    });

    socket.on('error', (error) => {
      console.error('WebSocket error:', error.message);
    });

    return () => {
      socket.disconnect();
    };
  }, []);

  // Helper functions
  const joinChat = (chatId: string) => {
    socketRef.current?.emit('chat:join', { chatId });
  };

  const sendMessage = (chatId: string, message: string) => {
    socketRef.current?.emit('message:send', { chatId, message });
  };

  const createDirectChat = (targetUserId: string) => {
    socketRef.current?.emit('chat:direct', { targetUserId });
  };

  const createGroup = (name: string, userIds: string[]) => {
    socketRef.current?.emit('group:create', { name, userIds });
  };

  return {
    isConnected,
    chats,
    joinChat,
    sendMessage,
    createDirectChat,
    createGroup
  };
};
```

### Rate Limiting & Performance

**Message Rate Limits:**
- Maximum 100 messages per user per minute
- Rate limit counters reset every minute
- Counters cleaned up after 5 minutes of inactivity

**Connection Management:**
- Automatic reconnection on disconnection
- User status tracking (online/offline)
- Chat room management with Redis caching
- Inactive chat archiving after 30 minutes

**Performance Considerations:**
- Messages pruned automatically (2 weeks retention)
- Redis used for active session management
- Database archiving for inactive chats
- Efficient room-based message broadcasting

---

This documentation provides the complete API reference based on the actual backend implementation. All endpoints, data structures, and business rules are derived directly from the TypeScript source code and database schema.

---

## Authentication & Security

### JWT Token Management
```typescript
// lib/auth/tokenManager.ts
export class TokenManager {
  private static readonly TOKEN_KEY = 'serpentrace_auth_token';
  private static readonly REFRESH_KEY = 'serpentrace_refresh_token';

  static setTokens(accessToken: string, refreshToken?: string) {
    localStorage.setItem(this.TOKEN_KEY, accessToken);
    if (refreshToken) {
      localStorage.setItem(this.REFRESH_KEY, refreshToken);
    }
  }

  static getAccessToken(): string | null {
    return localStorage.getItem(this.TOKEN_KEY);
  }

  static getRefreshToken(): string | null {
    return localStorage.getItem(this.REFRESH_KEY);
  }

  static clearTokens() {
    localStorage.removeItem(this.TOKEN_KEY);
    localStorage.removeItem(this.REFRESH_KEY);
  }

  static isTokenExpired(token: string): boolean {
    try {
      const payload = JSON.parse(atob(token.split('.')[1]));
      return payload.exp * 1000 < Date.now();
    } catch {
      return true;
    }
  }
}
```

### Protected Routes
```typescript
// components/layout/ProtectedRoute.tsx
import { useEffect } from 'react';
import { useRouter } from 'next/navigation';
import { useAuthStore } from '@/store/auth';

interface ProtectedRouteProps {
  children: React.ReactNode;
  requiredRole?: 'admin' | 'premium' | 'verified';
}

export function ProtectedRoute({ children, requiredRole }: ProtectedRouteProps) {
  const { user, isAuthenticated, checkAuth } = useAuthStore();
  const router = useRouter();

  useEffect(() => {
    if (!isAuthenticated) {
      checkAuth().then((authenticated) => {
        if (!authenticated) {
          router.push('/login');
        }
      });
    }
  }, [isAuthenticated, checkAuth, router]);

  useEffect(() => {
    if (isAuthenticated && user && requiredRole) {
      const hasAccess = checkUserRole(user, requiredRole);
      if (!hasAccess) {
        router.push('/unauthorized');
      }
    }
  }, [isAuthenticated, user, requiredRole, router]);

  if (!isAuthenticated || !user) {
    return <LoadingSpinner />;
  }

  if (requiredRole && !checkUserRole(user, requiredRole)) {
    return null; // Will redirect in useEffect
  }

  return <>{children}</>;
}

function checkUserRole(user: User, requiredRole: string): boolean {
  switch (requiredRole) {
    case 'admin':
      return user.state === UserState.ADMIN;
    case 'premium':
      return user.state === UserState.VERIFIED_PREMIUM || user.state === UserState.ADMIN;
    case 'verified':
      return user.state >= UserState.VERIFIED_REGULAR;
    default:
      return true;
  }
}
```

### Authentication Context
```typescript
// store/auth.ts
import { create } from 'zustand';
import { persist } from 'zustand/middleware';
import { authAPI } from '@/lib/api/auth';
import { TokenManager } from '@/lib/auth/tokenManager';

interface AuthState {
  user: User | null;
  isAuthenticated: boolean;
  isLoading: boolean;
  login: (credentials: LoginRequest) => Promise<LoginResponse>;
  register: (userData: RegisterRequest) => Promise<User>;
  logout: () => void;
  checkAuth: () => Promise<boolean>;
  updateUser: (userData: Partial<User>) => void;
}

export const useAuthStore = create<AuthState>()(
  persist(
    (set, get) => ({
      user: null,
      isAuthenticated: false,
      isLoading: false,

      login: async (credentials) => {
        set({ isLoading: true });
        try {
          const response = await authAPI.login(credentials);
          TokenManager.setTokens(response.data.token);
          set({
            user: response.data.user,
            isAuthenticated: true,
            isLoading: false,
          });
          return response.data;
        } catch (error) {
          set({ isLoading: false });
          throw error;
        }
      },

      register: async (userData) => {
        set({ isLoading: true });
        try {
          const response = await authAPI.register(userData);
          set({ isLoading: false });
          return response.data;
        } catch (error) {
          set({ isLoading: false });
          throw error;
        }
      },

      logout: () => {
        TokenManager.clearTokens();
        set({
          user: null,
          isAuthenticated: false,
        });
      },

      checkAuth: async () => {
        const token = TokenManager.getAccessToken();
        if (!token || TokenManager.isTokenExpired(token)) {
          set({ isAuthenticated: false, user: null });
          return false;
        }

        try {
          const response = await authAPI.getProfile();
          set({
            user: response.data,
            isAuthenticated: true,
          });
          return true;
        } catch {
          TokenManager.clearTokens();
          set({ isAuthenticated: false, user: null });
          return false;
        }
      },

      updateUser: (userData) => {
        const { user } = get();
        if (user) {
          set({ user: { ...user, ...userData } });
        }
      },
    }),
    {
      name: 'auth-storage',
      partialize: (state) => ({ user: state.user, isAuthenticated: state.isAuthenticated }),
    }
  )
);
```

---

## Core Features Implementation

### 1. User Registration & Login Forms
```typescript
// components/forms/LoginForm.tsx
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import { useAuthStore } from '@/store/auth';
import { Button } from '@/components/ui/Button';
import { Input } from '@/components/ui/Input';
import { toast } from '@/lib/toast';

const loginSchema = z.object({
  username: z.string().min(3, 'Username must be at least 3 characters'),
  password: z.string().min(6, 'Password must be at least 6 characters'),
});

type LoginForm = z.infer<typeof loginSchema>;

export function LoginForm() {
  const { login } = useAuthStore();
  const {
    register,
    handleSubmit,
    formState: { errors, isSubmitting },
  } = useForm<LoginForm>({
    resolver: zodResolver(loginSchema),
  });

  const onSubmit = async (data: LoginForm) => {
    try {
      const response = await login(data);
      
      if (response.requiresOrgReauth) {
        toast.info(`Please complete authentication with ${response.organizationName}`);
        window.location.href = response.orgLoginUrl!;
        return;
      }
      
      toast.success('Login successful!');
      window.location.href = '/dashboard';
    } catch (error: any) {
      toast.error(error.response?.data?.message || 'Login failed');
    }
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)} className="space-y-4">
      <div>
        <Input
          {...register('username')}
          placeholder="Username"
          error={errors.username?.message}
        />
      </div>
      <div>
        <Input
          {...register('password')}
          type="password"
          placeholder="Password"
          error={errors.password?.message}
        />
      </div>
      <Button
        type="submit"
        disabled={isSubmitting}
        className="w-full"
      >
        {isSubmitting ? 'Signing in...' : 'Sign In'}
      </Button>
    </form>
  );
}
```

### 2. Deck Creation & Management
```typescript
// components/features/decks/DeckEditor.tsx
import { useForm, useFieldArray } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import { DeckType, DeckVisibility, CardType } from '@/types/deck';

const cardSchema = z.object({
  id: z.string(),
  type: z.nativeEnum(CardType),
  text: z.string().min(1, 'Question text is required'),
  answer: z.union([z.string(), z.boolean(), z.null()]).optional(),
  options: z.array(z.string()).optional(),
});

const deckSchema = z.object({
  name: z.string().min(1, 'Deck name is required').max(255, 'Name too long'),
  type: z.nativeEnum(DeckType),
  ctype: z.nativeEnum(DeckVisibility),
  cards: z.array(cardSchema).min(1, 'At least one card is required').max(50, 'Maximum 50 cards allowed'),
});

type DeckForm = z.infer<typeof deckSchema>;

interface DeckEditorProps {
  initialData?: Deck;
  onSave: (data: CreateDeckRequest) => Promise<void>;
  onCancel: () => void;
}

export function DeckEditor({ initialData, onSave, onCancel }: DeckEditorProps) {
  const {
    register,
    control,
    handleSubmit,
    watch,
    formState: { errors, isSubmitting },
  } = useForm<DeckForm>({
    resolver: zodResolver(deckSchema),
    defaultValues: initialData || {
      name: '',
      type: DeckType.QUESTION,
      ctype: DeckVisibility.PUBLIC,
      cards: [{ id: crypto.randomUUID(), type: CardType.QUIZ, text: '', answer: '', options: ['', '', '', ''] }],
    },
  });

  const { fields, append, remove } = useFieldArray({
    control,
    name: 'cards',
  });

  const deckType = watch('type');

  const addCard = () => {
    append({
      id: crypto.randomUUID(),
      type: CardType.QUIZ,
      text: '',
      answer: '',
      options: ['', '', '', ''],
    });
  };

  const onSubmit = async (data: DeckForm) => {
    try {
      await onSave(data);
      toast.success('Deck saved successfully!');
    } catch (error: any) {
      toast.error(error.response?.data?.message || 'Failed to save deck');
    }
  };

  return (
    <div className="max-w-4xl mx-auto p-6">
      <form onSubmit={handleSubmit(onSubmit)} className="space-y-6">
        {/* Deck Basic Information */}
        <div className="bg-white rounded-lg shadow p-6">
          <h2 className="text-xl font-semibold mb-4">Deck Information</h2>
          <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
            <div>
              <label className="block text-sm font-medium mb-2">Deck Name</label>
              <Input
                {...register('name')}
                placeholder="Enter deck name"
                error={errors.name?.message}
              />
            </div>
            <div>
              <label className="block text-sm font-medium mb-2">Deck Type</label>
              <Select {...register('type')}>
                <option value={DeckType.QUESTION}>Question Deck</option>
                <option value={DeckType.JOKER}>Joker Cards</option>
                <option value={DeckType.LUCK}>Luck Challenges</option>
              </Select>
            </div>
            <div>
              <label className="block text-sm font-medium mb-2">Visibility</label>
              <Select {...register('ctype')}>
                <option value={DeckVisibility.PUBLIC}>Public</option>
                <option value={DeckVisibility.PRIVATE}>Private</option>
                <option value={DeckVisibility.ORGANIZATION}>Organization</option>
              </Select>
            </div>
          </div>
        </div>

        {/* Cards Section */}
        <div className="bg-white rounded-lg shadow p-6">
          <div className="flex justify-between items-center mb-4">
            <h2 className="text-xl font-semibold">Cards ({fields.length})</h2>
            <Button
              type="button"
              onClick={addCard}
              disabled={fields.length >= 50}
              variant="outline"
            >
              Add Card
            </Button>
          </div>

          <div className="space-y-4">
            {fields.map((field, index) => (
              <CardEditor
                key={field.id}
                control={control}
                index={index}
                onRemove={() => remove(index)}
                canRemove={fields.length > 1}
                register={register}
                errors={errors.cards?.[index]}
              />
            ))}
          </div>
        </div>

        {/* Actions */}
        <div className="flex justify-end space-x-4">
          <Button type="button" variant="outline" onClick={onCancel}>
            Cancel
          </Button>
          <Button type="submit" disabled={isSubmitting}>
            {isSubmitting ? 'Saving...' : 'Save Deck'}
          </Button>
        </div>
      </form>
    </div>
  );
}
```

### 3. Real-time Chat Implementation
```typescript
// hooks/useSocket.ts
import { useEffect, useRef } from 'react';
import { io, Socket } from 'socket.io-client';
import { useAuthStore } from '@/store/auth';
import { TokenManager } from '@/lib/auth/tokenManager';

export function useSocket() {
  const socket = useRef<Socket | null>(null);
  const { user, isAuthenticated } = useAuthStore();

  useEffect(() => {
    if (isAuthenticated && user) {
      socket.current = io(process.env.NEXT_PUBLIC_WS_URL || 'http://localhost:3000', {
        auth: {
          token: TokenManager.getAccessToken(),
        },
      });

      socket.current.on('connect', () => {
        console.log('Connected to WebSocket server');
      });

      socket.current.on('disconnect', () => {
        console.log('Disconnected from WebSocket server');
      });

      return () => {
        socket.current?.disconnect();
      };
    }
  }, [isAuthenticated, user]);

  return socket.current;
}
```

```typescript
// components/features/chat/ChatWindow.tsx
import { useState, useEffect, useRef } from 'react';
import { useSocket } from '@/hooks/useSocket';
import { useChatStore } from '@/store/chat';
import { useAuthStore } from '@/store/auth';
import { Message, Chat } from '@/types/chat';

interface ChatWindowProps {
  chatId: string;
  onClose: () => void;
}

export function ChatWindow({ chatId, onClose }: ChatWindowProps) {
  const socket = useSocket();
  const { user } = useAuthStore();
  const { currentChat, messages, sendMessage, loadChat } = useChatStore();
  const [newMessage, setNewMessage] = useState('');
  const messagesEndRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    loadChat(chatId);
  }, [chatId, loadChat]);

  useEffect(() => {
    if (!socket) return;

    socket.emit('join-chat', chatId);

    socket.on('new-message', (message: Message) => {
      // Handle incoming messages
      useChatStore.getState().addMessage(chatId, message);
    });

    socket.on('user-typing', (data: { userId: string; isTyping: boolean }) => {
      // Handle typing indicators
    });

    return () => {
      socket.off('new-message');
      socket.off('user-typing');
      socket.emit('leave-chat', chatId);
    };
  }, [socket, chatId]);

  useEffect(() => {
    scrollToBottom();
  }, [messages]);

  const scrollToBottom = () => {
    messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' });
  };

  const handleSendMessage = async (e: React.FormEvent) => {
    e.preventDefault();
    if (!newMessage.trim() || !user) return;

    const message: Omit<Message, 'id' | 'date'> = {
      userid: user.id,
      text: newMessage.trim(),
    };

    try {
      await sendMessage(chatId, message);
      setNewMessage('');
    } catch (error) {
      toast.error('Failed to send message');
    }
  };

  if (!currentChat) {
    return <div className="p-4">Loading chat...</div>;
  }

  return (
    <div className="flex flex-col h-96 bg-white rounded-lg shadow-lg">
      {/* Chat Header */}
      <div className="flex items-center justify-between p-4 border-b">
        <div>
          <h3 className="font-semibold">
            {currentChat.name || `Chat with ${currentChat.users.length} users`}
          </h3>
          <p className="text-sm text-gray-500">{currentChat.type} chat</p>
        </div>
        <Button variant="ghost" size="sm" onClick={onClose}>
          ✕
        </Button>
      </div>

      {/* Messages */}
      <div className="flex-1 overflow-y-auto p-4 space-y-3">
        {messages.map((message) => (
          <div
            key={message.id}
            className={`flex ${
              message.userid === user?.id ? 'justify-end' : 'justify-start'
            }`}
          >
            <div
              className={`max-w-xs lg:max-w-md px-4 py-2 rounded-lg ${
                message.userid === user?.id
                  ? 'bg-blue-500 text-white'
                  : 'bg-gray-200 text-gray-800'
              }`}
            >
              <p className="text-sm">{message.text}</p>
              <p className="text-xs opacity-75 mt-1">
                {new Date(message.date).toLocaleTimeString()}
              </p>
            </div>
          </div>
        ))}
        <div ref={messagesEndRef} />
      </div>

      {/* Message Input */}
      <form onSubmit={handleSendMessage} className="p-4 border-t">
        <div className="flex space-x-2">
          <Input
            value={newMessage}
            onChange={(e) => setNewMessage(e.target.value)}
            placeholder="Type a message..."
            className="flex-1"
          />
          <Button type="submit" disabled={!newMessage.trim()}>
            Send
          </Button>
        </div>
      </form>
    </div>
  );
}
```

---

## UI/UX Guidelines

### Design System
```typescript
// components/ui/Button.tsx
import { cn } from '@/lib/utils';
import { ButtonHTMLAttributes, forwardRef } from 'react';

interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'default' | 'outline' | 'ghost' | 'destructive';
  size?: 'sm' | 'md' | 'lg';
}

export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, variant = 'default', size = 'md', ...props }, ref) => {
    return (
      <button
        ref={ref}
        className={cn(
          // Base styles
          'inline-flex items-center justify-center rounded-md font-medium transition-colors',
          'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
          'disabled:opacity-50 disabled:pointer-events-none',
          
          // Variants
          {
            'bg-primary text-primary-foreground hover:bg-primary/90': variant === 'default',
            'border border-input hover:bg-accent hover:text-accent-foreground': variant === 'outline',
            'hover:bg-accent hover:text-accent-foreground': variant === 'ghost',
            'bg-destructive text-destructive-foreground hover:bg-destructive/90': variant === 'destructive',
          },
          
          // Sizes
          {
            'h-9 px-3 text-sm': size === 'sm',
            'h-10 px-4 py-2': size === 'md',
            'h-11 px-6 text-lg': size === 'lg',
          },
          
          className
        )}
        {...props}
      />
    );
  }
);

Button.displayName = 'Button';
```

### Theme Configuration
```typescript
// tailwind.config.js
module.exports = {
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {
      colors: {
        // Brand colors
        primary: {
          50: '#f0f9ff',
          500: '#3b82f6',
          900: '#1e3a8a',
        },
        // Semantic colors
        success: '#10b981',
        warning: '#f59e0b',
        error: '#ef4444',
        // UI colors
        background: '#ffffff',
        foreground: '#0f172a',
        muted: '#f8fafc',
        border: '#e2e8f0',
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
      },
      animation: {
        'fade-in': 'fadeIn 0.3s ease-in-out',
        'slide-up': 'slideUp 0.3s ease-in-out',
      },
    },
  },
  plugins: [require('@tailwindcss/forms')],
};
```

### Responsive Layout Components
```typescript
// components/layout/DashboardLayout.tsx
interface DashboardLayoutProps {
  children: React.ReactNode;
  sidebar?: React.ReactNode;
}

export function DashboardLayout({ children, sidebar }: DashboardLayoutProps) {
  return (
    <div className="min-h-screen bg-gray-50">
      <Navigation />
      
      <div className="flex">
        {sidebar && (
          <aside className="hidden lg:block w-64 bg-white shadow-sm">
            <div className="p-6">
              {sidebar}
            </div>
          </aside>
        )}
        
        <main className="flex-1 p-6">
          <div className="max-w-7xl mx-auto">
            {children}
          </div>
        </main>
      </div>
    </div>
  );
}
```

---

## State Management

### Redux Store Configuration
```typescript
// store/index.ts
import { configureStore } from '@reduxjs/toolkit';
import { setupListeners } from '@reduxjs/toolkit/query';
import { apiSlice } from './api/apiSlice';
import deckReducer from './slices/deckSlice';
import uiReducer from './slices/uiSlice';

export const store = configureStore({
  reducer: {
    api: apiSlice.reducer,
    decks: deckReducer,
    ui: uiReducer,
  },
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware().concat(apiSlice.middleware),
});

setupListeners(store.dispatch);

export type RootState = ReturnType<typeof store.getState>;
export type AppDispatch = typeof store.dispatch;
```

### RTK Query API Slice
```typescript
// store/api/apiSlice.ts
import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react';
import { TokenManager } from '@/lib/auth/tokenManager';

export const apiSlice = createApi({
  reducerPath: 'api',
  baseQuery: fetchBaseQuery({
    baseUrl: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:3000/api',
    prepareHeaders: (headers) => {
      const token = TokenManager.getAccessToken();
      if (token) {
        headers.set('Authorization', `Bearer ${token}`);
      }
      return headers;
    },
  }),
  tagTypes: ['User', 'Deck', 'Organization', 'Chat', 'Contact'],
  endpoints: () => ({}),
});
```

```typescript
// store/api/deckApi.ts
import { apiSlice } from './apiSlice';
import { Deck, CreateDeckRequest } from '@/types/deck';

export const deckApi = apiSlice.injectEndpoints({
  endpoints: (builder) => ({
    getDecks: builder.query<{decks: Deck[], totalCount: number}, {
      from?: number;
      to?: number;
      userId?: string;
    }>({
      query: (params) => ({
        url: '/decks',
        params,
      }),
      providesTags: ['Deck'],
    }),

    getDeck: builder.query<Deck, string>({
      query: (id) => `/decks/${id}`,
      providesTags: (result, error, id) => [{ type: 'Deck', id }],
    }),

    createDeck: builder.mutation<Deck, CreateDeckRequest>({
      query: (deckData) => ({
        url: '/decks',
        method: 'POST',
        body: deckData,
      }),
      invalidatesTags: ['Deck'],
    }),

    updateDeck: builder.mutation<Deck, { id: string; data: Partial<CreateDeckRequest> }>({
      query: ({ id, data }) => ({
        url: `/decks/${id}`,
        method: 'PUT',
        body: data,
      }),
      invalidatesTags: (result, error, { id }) => [{ type: 'Deck', id }],
    }),

    deleteDeck: builder.mutation<void, string>({
      query: (id) => ({
        url: `/decks/${id}`,
        method: 'DELETE',
      }),
      invalidatesTags: ['Deck'],
    }),
  }),
});

export const {
  useGetDecksQuery,
  useGetDeckQuery,
  useCreateDeckMutation,
  useUpdateDeckMutation,
  useDeleteDeckMutation,
} = deckApi;
```

---

## Real-time Features

### WebSocket Integration
```typescript
// lib/socket/socketManager.ts
import { io, Socket } from 'socket.io-client';
import { TokenManager } from '@/lib/auth/tokenManager';

class SocketManager {
  private socket: Socket | null = null;
  private listeners: Map<string, Function[]> = new Map();

  connect() {
    if (this.socket?.connected) return;

    this.socket = io(process.env.NEXT_PUBLIC_WS_URL || 'ws://localhost:3000', {
      auth: {
        token: TokenManager.getAccessToken(),
      },
    });

    this.socket.on('connect', () => {
      console.log('Socket connected');
      this.emit('connection', true);
    });

    this.socket.on('disconnect', () => {
      console.log('Socket disconnected');
      this.emit('connection', false);
    });

    // Set up event forwarding
    this.setupEventForwarding();
  }

  disconnect() {
    this.socket?.disconnect();
    this.socket = null;
  }

  on(event: string, callback: Function) {
    if (!this.listeners.has(event)) {
      this.listeners.set(event, []);
    }
    this.listeners.get(event)!.push(callback);
  }

  off(event: string, callback: Function) {
    const eventListeners = this.listeners.get(event);
    if (eventListeners) {
      const index = eventListeners.indexOf(callback);
      if (index > -1) {
        eventListeners.splice(index, 1);
      }
    }
  }

  emit(event: string, data?: any) {
    this.socket?.emit(event, data);
    
    // Also emit to local listeners
    const eventListeners = this.listeners.get(event);
    if (eventListeners) {
      eventListeners.forEach(callback => callback(data));
    }
  }

  private setupEventForwarding() {
    if (!this.socket) return;

    const events = [
      'new-message',
      'user-typing',
      'user-online',
      'user-offline',
      'game-update',
      'deck-shared',
    ];

    events.forEach(event => {
      this.socket!.on(event, (data) => {
        this.emit(event, data);
      });
    });
  }
}

export const socketManager = new SocketManager();
```

### Real-time Notifications
```typescript
// components/features/notifications/NotificationCenter.tsx
import { useEffect, useState } from 'react';
import { socketManager } from '@/lib/socket/socketManager';
import { toast } from '@/lib/toast';

interface Notification {
  id: string;
  type: 'message' | 'deck-shared' | 'game-invite' | 'system';
  title: string;
  message: string;
  timestamp: Date;
  read: boolean;
}

export function NotificationCenter() {
  const [notifications, setNotifications] = useState<Notification[]>([]);
  const [isOpen, setIsOpen] = useState(false);

  useEffect(() => {
    const handleNewMessage = (data: any) => {
      const notification: Notification = {
        id: crypto.randomUUID(),
        type: 'message',
        title: 'New Message',
        message: `New message from ${data.senderName}`,
        timestamp: new Date(),
        read: false,
      };
      
      setNotifications(prev => [notification, ...prev]);
      toast.info(notification.message);
    };

    const handleDeckShared = (data: any) => {
      const notification: Notification = {
        id: crypto.randomUUID(),
        type: 'deck-shared',
        title: 'Deck Shared',
        message: `${data.sharedBy} shared a deck with you: ${data.deckName}`,
        timestamp: new Date(),
        read: false,
      };
      
      setNotifications(prev => [notification, ...prev]);
      toast.success(notification.message);
    };

    socketManager.on('new-message', handleNewMessage);
    socketManager.on('deck-shared', handleDeckShared);

    return () => {
      socketManager.off('new-message', handleNewMessage);
      socketManager.off('deck-shared', handleDeckShared);
    };
  }, []);

  const unreadCount = notifications.filter(n => !n.read).length;

  const markAsRead = (id: string) => {
    setNotifications(prev =>
      prev.map(n => n.id === id ? { ...n, read: true } : n)
    );
  };

  return (
    <div className="relative">
      <Button
        variant="ghost"
        onClick={() => setIsOpen(!isOpen)}
        className="relative"
      >
        🔔
        {unreadCount > 0 && (
          <span className="absolute -top-1 -right-1 bg-red-500 text-white text-xs rounded-full h-5 w-5 flex items-center justify-center">
            {unreadCount}
          </span>
        )}
      </Button>

      {isOpen && (
        <div className="absolute right-0 mt-2 w-80 bg-white rounded-lg shadow-lg border z-50">
          <div className="p-4 border-b">
            <h3 className="font-semibold">Notifications</h3>
          </div>
          
          <div className="max-h-96 overflow-y-auto">
            {notifications.length === 0 ? (
              <div className="p-4 text-center text-gray-500">
                No notifications
              </div>
            ) : (
              notifications.map(notification => (
                <div
                  key={notification.id}
                  className={`p-4 border-b cursor-pointer hover:bg-gray-50 ${
                    !notification.read ? 'bg-blue-50' : ''
                  }`}
                  onClick={() => markAsRead(notification.id)}
                >
                  <div className="flex justify-between items-start">
                    <div>
                      <h4 className="font-medium">{notification.title}</h4>
                      <p className="text-sm text-gray-600">{notification.message}</p>
                    </div>
                    {!notification.read && (
                      <div className="w-2 h-2 bg-blue-500 rounded-full"></div>
                    )}
                  </div>
                  <p className="text-xs text-gray-400 mt-2">
                    {notification.timestamp.toLocaleString()}
                  </p>
                </div>
              ))
            )}
          </div>
        </div>
      )}
    </div>
  );
}
```

---

## Performance Optimization

### Code Splitting & Lazy Loading
```typescript
// app/dashboard/decks/page.tsx
import dynamic from 'next/dynamic';
import { Suspense } from 'react';

const DeckManagement = dynamic(() => import('@/components/features/decks/DeckManagement'), {
  loading: () => <DeckManagementSkeleton />,
});

export default function DecksPage() {
  return (
    <Suspense fallback={<DeckManagementSkeleton />}>
      <DeckManagement />
    </Suspense>
  );
}
```

### Virtual Scrolling for Large Lists
```typescript
// components/ui/VirtualizedList.tsx
import { FixedSizeList as List } from 'react-window';

interface VirtualizedListProps<T> {
  items: T[];
  height: number;
  itemHeight: number;
  renderItem: ({ index, style }: { index: number; style: React.CSSProperties }) => JSX.Element;
}

export function VirtualizedList<T>({ items, height, itemHeight, renderItem }: VirtualizedListProps<T>) {
  return (
    <List
      height={height}
      itemCount={items.length}
      itemSize={itemHeight}
      itemData={items}
    >
      {renderItem}
    </List>
  );
}
```

### Memoization & Optimization
```typescript
// hooks/useOptimizedDecks.ts
import { useMemo } from 'react';
import { useGetDecksQuery } from '@/store/api/deckApi';
import { Deck, DeckType, DeckVisibility } from '@/types/deck';

interface DeckFilters {
  search?: string;
  type?: DeckType;
  visibility?: DeckVisibility;
  sortBy?: 'name' | 'date' | 'plays';
  sortOrder?: 'asc' | 'desc';
}

export function useOptimizedDecks(filters: DeckFilters = {}) {
  const { data, isLoading, error } = useGetDecksQuery({
    from: 0,
    to: 100, // Adjust based on pagination needs
  });

  const filteredAndSortedDecks = useMemo(() => {
    if (!data?.decks) return [];

    let filtered = data.decks;

    // Apply search filter
    if (filters.search) {
      const searchLower = filters.search.toLowerCase();
      filtered = filtered.filter(deck =>
        deck.name.toLowerCase().includes(searchLower) ||
        deck.cards.some(card => card.text.toLowerCase().includes(searchLower))
      );
    }

    // Apply type filter
    if (filters.type !== undefined) {
      filtered = filtered.filter(deck => deck.type === filters.type);
    }

    // Apply visibility filter
    if (filters.visibility !== undefined) {
      filtered = filtered.filter(deck => deck.ctype === filters.visibility);
    }

    // Apply sorting
    if (filters.sortBy) {
      filtered.sort((a, b) => {
        let aValue, bValue;
        
        switch (filters.sortBy) {
          case 'name':
            aValue = a.name.toLowerCase();
            bValue = b.name.toLowerCase();
            break;
          case 'date':
            aValue = new Date(a.creationdate).getTime();
            bValue = new Date(b.creationdate).getTime();
            break;
          case 'plays':
            aValue = a.playedNumber;
            bValue = b.playedNumber;
            break;
          default:
            return 0;
        }

        if (filters.sortOrder === 'desc') {
          return aValue < bValue ? 1 : -1;
        }
        return aValue > bValue ? 1 : -1;
      });
    }

    return filtered;
  }, [data?.decks, filters]);

  return {
    decks: filteredAndSortedDecks,
    totalCount: data?.totalCount || 0,
    isLoading,
    error,
  };
}
```

---

## Testing Strategy

### Component Testing
```typescript
// components/forms/__tests__/LoginForm.test.tsx
import { render, screen, fireEvent, waitFor } from '@testing-library/react';
import { LoginForm } from '../LoginForm';
import { useAuthStore } from '@/store/auth';

// Mock the auth store
jest.mock('@/store/auth');
const mockUseAuthStore = useAuthStore as jest.MockedFunction<typeof useAuthStore>;

describe('LoginForm', () => {
  const mockLogin = jest.fn();

  beforeEach(() => {
    mockUseAuthStore.mockReturnValue({
      login: mockLogin,
      user: null,
      isAuthenticated: false,
      isLoading: false,
      register: jest.fn(),
      logout: jest.fn(),
      checkAuth: jest.fn(),
      updateUser: jest.fn(),
    });
  });

  afterEach(() => {
    jest.clearAllMocks();
  });

  it('renders login form fields', () => {
    render(<LoginForm />);

    expect(screen.getByPlaceholderText('Username')).toBeInTheDocument();
    expect(screen.getByPlaceholderText('Password')).toBeInTheDocument();
    expect(screen.getByRole('button', { name: /sign in/i })).toBeInTheDocument();
  });

  it('validates required fields', async () => {
    render(<LoginForm />);

    fireEvent.click(screen.getByRole('button', { name: /sign in/i }));

    await waitFor(() => {
      expect(screen.getByText('Username must be at least 3 characters')).toBeInTheDocument();
      expect(screen.getByText('Password must be at least 6 characters')).toBeInTheDocument();
    });
  });

  it('submits form with valid credentials', async () => {
    mockLogin.mockResolvedValue({
      token: 'mock-token',
      user: { id: '1', username: 'testuser' },
      requiresOrgReauth: false,
    });

    render(<LoginForm />);

    fireEvent.change(screen.getByPlaceholderText('Username'), {
      target: { value: 'testuser' },
    });
    fireEvent.change(screen.getByPlaceholderText('Password'), {
      target: { value: 'password123' },
    });

    fireEvent.click(screen.getByRole('button', { name: /sign in/i }));

    await waitFor(() => {
      expect(mockLogin).toHaveBeenCalledWith({
        username: 'testuser',
        password: 'password123',
      });
    });
  });
});
```

### API Testing
```typescript
// lib/api/__tests__/deckApi.test.ts
import { deckApi } from '@/store/api/deckApi';
import { store } from '@/store';
import { setupApiMocking } from '@/test-utils/apiMocking';

const { server } = setupApiMocking();

describe('deckApi', () => {
  beforeAll(() => server.listen());
  afterEach(() => server.resetHandlers());
  afterAll(() => server.close());

  it('fetches decks successfully', async () => {
    const mockDecks = [
      { id: '1', name: 'Test Deck 1', type: 0 },
      { id: '2', name: 'Test Deck 2', type: 1 },
    ];

    const result = await store.dispatch(
      deckApi.endpoints.getDecks.initiate({ from: 0, to: 10 })
    );

    expect(result.data).toEqual({
      decks: mockDecks,
      totalCount: 2,
    });
  });

  it('creates deck successfully', async () => {
    const newDeck = {
      name: 'New Deck',
      type: 2,
      cards: [{ id: '1', type: 0, text: 'Test question' }],
    };

    const result = await store.dispatch(
      deckApi.endpoints.createDeck.initiate(newDeck)
    );

    expect(result.data).toMatchObject(newDeck);
  });
});
```

---

## Deployment Guide

### Environment Configuration
```bash
# .env.local
NEXT_PUBLIC_API_URL=https://api.serpentrace.com
NEXT_PUBLIC_WS_URL=wss://api.serpentrace.com
NEXTAUTH_URL=https://serpentrace.com
NEXTAUTH_SECRET=your-secret-key-here
```

### Docker Configuration
```dockerfile
# Dockerfile
FROM node:18-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --only=production

FROM node:18-alpine AS builder
WORKDIR /app
COPY . .
COPY --from=deps /app/node_modules ./node_modules
RUN npm run build

FROM node:18-alpine AS runner
WORKDIR /app
ENV NODE_ENV production

RUN addgroup -g 1001 -S nodejs
RUN adduser -S nextjs -u 1001

COPY --from=builder /app/public ./public
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static

USER nextjs

EXPOSE 3000
ENV PORT 3000

CMD ["node", "server.js"]
```

### CI/CD Pipeline
```yaml
# .github/workflows/deploy.yml
name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'
      - run: npm ci
      - run: npm run test
      - run: npm run build

  deploy:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Deploy to production
        run: |
          # Add your deployment commands here
          echo "Deploying to production..."
```

---

## Security Considerations

### Content Security Policy
```typescript
// next.config.js
const securityHeaders = [
  {
    key: 'Content-Security-Policy',
    value: `
      default-src 'self';
      script-src 'self' 'unsafe-eval' 'unsafe-inline';
      style-src 'self' 'unsafe-inline';
      img-src 'self' data: https:;
      connect-src 'self' wss: ws:;
    `.replace(/\s{2,}/g, ' ').trim()
  },
];

module.exports = {
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: securityHeaders,
      },
    ];
  },
};
```

### Input Sanitization
```typescript
// lib/security/sanitize.ts
import DOMPurify from 'dompurify';

export function sanitizeHtml(dirty: string): string {
  return DOMPurify.sanitize(dirty, {
    ALLOWED_TAGS: ['p', 'br', 'strong', 'em', 'u'],
    ALLOWED_ATTR: [],
  });
}

export function sanitizeText(text: string): string {
  return text
    .replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '')
    .replace(/[<>]/g, '')
    .trim();
}
```

---

This comprehensive frontend documentation provides a complete guide for implementing a modern, scalable, and secure frontend for the SerpentRace platform. The documentation covers all major aspects from setup to deployment, following best practices and industry standards.