CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Naming Conventions and Code Style

Naming Rules

• NO marketing adjectives: Never use "advanced", "enhanced", "improved", "better", "superior", "features", "optimized", "premium", or similar terms in code names
• Be descriptive and direct: Use specific, functional names that describe what the code does
• Avoid redundancy: Don't use "features" suffix (e.g., useE2EE not useE2EEFeatures)
• Keep it simple: Prefer shorter, clearer names over verbose ones
• Examples:
  • ✅ useE2EE, MessageScheduler, DisappearingMessages
  • ❌ useAdvancedE2EE, EnhancedMessageScheduler, ImprovedFeatures

Integration over Creation

• Always integrate new functionality into existing hooks/components when possible
• Only create separate files when functionality is truly distinct
• Prefer extending existing interfaces over creating new ones
• Merge related functionality rather than creating parallel systems

Architecture Overview

This is a Laravel 12 + React fullstack application using:

• Backend: Laravel 12 with Inertia.js for SPA functionality
• Frontend: React 19 with TypeScript, Vite for bundling
• UI Library: shadcn/ui components with Radix UI primitives and Tailwind CSS v4
• Testing: Pest (PHP) for backend, Playwright for E2E tests
• Database: PostgreSQL (default), migrations in database/migrations/
• SSR: Enabled via Inertia.js server-side rendering (port 13714)
• Authentication: Laravel Passport for OAuth 2.0/OIDC, Laravel Breeze-style UI flows, WebAuthn/Passkeys support
• Extensions: Multiple Spatie packages (permissions, activity logs, event sourcing)
• Organization Management: Hierarchical organization structure with units, positions, and memberships
• Chat System: End-to-end encrypted chat with multi-device and quantum-resistant cryptography support
• File Storage: MinIO S3-compatible storage with encrypted file handling
• Containerization: Docker Compose setup for local, dev, staging, and production environments

Development Commands

Start Development Server

# Runs Laravel server, queue worker, logs, and Vite in parallel
composer dev

# Development with SSR (builds SSR first, then runs with SSR server)
composer dev:ssr

Frontend Only

npm run dev          # Start Vite dev server
npm run build        # Build for production
npm run build:ssr    # Build with SSR

Backend

php artisan serve    # Start Laravel server
php artisan test     # Run Pest tests
composer test        # Same as artisan test

Code Quality

npm run lint         # ESLint with auto-fix
npm run types        # TypeScript type checking
npm run format       # Prettier formatting
npm run format:check # Check formatting

./vendor/bin/pint    # Laravel Pint (PHP formatting)

E2E and Testing

npm run test:e2e        # Run all Playwright E2E tests
npm run test:e2e:ui     # Run E2E tests with UI mode
npm run test:e2e:headed # Run E2E tests in headed mode
npm run test:e2e:debug  # Debug E2E tests

./scripts/test-e2ee.sh     # Comprehensive E2EE chat testing
./scripts/test-e2ee.sh unit        # Run only unit tests
./scripts/test-e2ee.sh multidevice # Run only multi-device tests
./scripts/test-e2ee.sh quantum     # Run quantum cryptography tests

php artisan test --filter=Chat      # Run specific chat test group

Docker Development

make help           # Show all available commands
make install        # Install and setup the project
make local          # Start local development environment
make local-fresh    # Start with fresh database
make test           # Run complete test suite
make logs service=app # Show logs for specific service
make shell          # Open shell in app container
make clean          # Clean up Docker resources

Project Structure

Backend (Laravel)

• Routes:
  • routes/web.php - Main web routes
  • routes/webs/auth.php - Authentication routes
  • routes/webs/oauth.php - OAuth/OIDC routes
  • routes/webs/settings.php - Settings routes
  • routes/api.php - API endpoints
  • routes/channels.php - Broadcasting channels
• Controllers: app/Http/Controllers/ organized by feature:
  • Api/Chat/ - Chat system controllers (Conversation, Message, Encryption, etc.)
  • Api/QuantumController.php - Quantum cryptography API endpoints
  • Api/ - Organization, User, Permission, Role controllers
  • Auth/ - Authentication controllers
  • OAuth/ - OAuth 2.0 server controllers
  • Settings/ - Profile and password management
• Models: app/Models/ including:
  • Organization hierarchy: Organization, OrganizationUnit, OrganizationPosition, OrganizationMembership
  • Chat system: Chat/Conversation, Chat/Message, Chat/EncryptionKey, Chat/Participant
  • Authentication: User, UserDevice, UserMfaSetting
  • OAuth: Client, OAuthAuditLog, OAuthScope
• Services: app/Services/ - Business logic:
  • ChatEncryptionService.php - Chat encryption with quantum algorithm support
  • QuantumCryptoService.php - NIST-approved post-quantum cryptography (ML-KEM)
  • Crypto/MLKEMProviderInterface.php - ML-KEM provider abstraction
  • Crypto/LibOQSMLKEMProvider.php - Production LibOQS implementation
  • Crypto/FallbackMLKEMProvider.php - Development/testing fallback
  • MultiDeviceEncryptionService.php - Multi-device quantum support
  • ChatFileService.php - File handling and other services
• Middleware: app/Http/Middleware/ - Rate limiting, permissions, chat security, tenant context

Frontend (React)

• Entry Points:
  • resources/js/app.tsx - client-side entry
  • resources/js/ssr.tsx - server-side rendering entry
• Pages: resources/js/pages/ - Inertia.js pages:
  • chat.tsx - Main chat interface
  • dashboard.tsx - Dashboard
  • welcome.tsx - Landing page
• Components: resources/js/components/ - reusable components and shadcn/ui components
• Layouts: resources/js/layouts/ - app layouts (app-layout, auth-layout)
• Hooks: resources/js/hooks/ - custom React hooks:
  • useChat.ts - Chat functionality
  • useE2EE.ts - End-to-end encryption with quantum algorithm support
  • useQuantumE2EE.ts - Quantum-resistant cryptography management
  • useChatPagination.ts - Chat message pagination
  • usePermissions.tsx - Permission checking
• Services: resources/js/services/ - Frontend services:
  • ApiService.ts - Centralized HTTP client with authentication and token management
  • MultiDeviceE2EEService.ts - Multi-device encryption
  • OptimizedE2EEService.ts - Performance optimized encryption with quantum support
  • QuantumE2EEService.ts - Client-side quantum cryptography
  • SecurityMonitoringService.ts - Security monitoring
• Types: resources/js/types/ - TypeScript definitions (chat.ts, index.d.ts)
• Utils: resources/js/utils/ - Utility functions and encryption helpers:
  • QuantumMigrationUtils.ts - Migration utilities for quantum transition
  • Standard encryption and chat utilities

Configuration

• TypeScript: Path aliases configured (@/* maps to resources/js/*), strict mode enabled
• shadcn/ui: Configured in components.json with Tailwind CSS integration, Lucide icons
• Vite: Configured for Laravel with React, Tailwind CSS v4, and SSR support
• Docker: Multi-environment setup (local, dev, staging, prod) with Docker Compose
• Storage: MinIO S3-compatible storage configuration for encrypted file handling

Key Integrations

Inertia.js

• Server-side rendering enabled
• Pages are React components in resources/js/pages/
• Laravel routes return Inertia::render() calls
• Ziggy package provides named route helpers in frontend

Authentication

• Laravel Breeze-style authentication with Inertia.js
• Complete auth flow: register, login, password reset, email verification
• Auth pages in resources/js/pages/auth/

UI Components

• shadcn/ui components in resources/js/components/ui/:
  • quantum-status-badge.tsx - Algorithm status indicators with tooltips
  • quantum-health-indicator.tsx - System health and device readiness display
  • quantum-device-manager.tsx - Device management interface with migration
  • quantum-admin-panel.tsx - Complete admin dashboard for quantum systems
  • Standard UI components (button, card, alert, etc.)
• Appearance/theme system with light/dark mode support
• Sidebar navigation with user management

Testing

Backend Tests (Pest)

php artisan test                    # Run all Pest tests
php artisan test --filter=Auth      # Run specific test group
php artisan test tests/Feature/     # Run feature tests only
php artisan test --stop-on-failure  # Stop on first failure
composer test                       # Run tests via composer (includes setup)

Tests are located in:

• tests/Feature/ - Feature tests including auth flows, chat, E2EE, organization management
• tests/Unit/ - Unit tests for services and utilities
• tests/e2e/ - End-to-end tests using Playwright

E2E Tests (Playwright)

npm run test:e2e        # Run all E2E tests
npm run test:e2e:ui     # Run with Playwright UI
npm run test:e2e:headed # Run in headed browser mode
npm run test:e2e:debug  # Debug mode

E2E test categories:

• Chat functionality and messaging
• End-to-end encryption workflows
• Multi-device encryption scenarios
• Authentication and authorization flows
• Organization management features

Specialized Testing Scripts

./scripts/test-e2ee.sh          # Comprehensive E2EE testing suite
./scripts/test-e2ee.sh unit     # Unit tests only
./scripts/test-e2ee.sh security # Security validation tests
./scripts/test-minio.sh         # MinIO integration testing

Database

• Uses PostgreSQL by default (configurable via Docker Compose)
• Extensive migration set including:
  • OAuth 2.0/OIDC tables (Passport) with organization-scoped clients
  • Organization hierarchy tables (organizations, units, positions, memberships)
  • Chat system tables (conversations, messages, encryption keys, participants)
  • Permission tables (Spatie), activity logs, event sourcing, multitenancy
  • Passkeys/WebAuthn support tables
  • User device management and trusted device tracking
• Comprehensive seeders in database/seeders/:
  • Organizational structure and position hierarchies
  • OAuth clients and scopes
  • Permission system setup
  • Industry-specific permissions

Key Features

Organization Management

• Hierarchical Structure: Organizations can have parent-child relationships with automatic path/level management
• Organization Types: holding_company, subsidiary, division, branch, department, unit
• Organization Units: Various unit types (boards, committees, divisions, departments, etc.)
• Position Management: Hierarchical position levels with salary ranges and qualifications
• Membership System: Users can have memberships across multiple organizations with different roles

OAuth 2.0 & OIDC Provider

• Full OAuth 2.0 Server: Authorization code, client credentials, refresh token flows
• OpenID Connect: Complete OIDC implementation with discovery endpoints
• Organization-Scoped Clients: All OAuth clients must be associated with an organization
• Google-Style Scopes: Modern URL-based OAuth scopes (https://api.yourcompany.com/auth/organization.readonly, etc.)
• Rate Limiting: Separate rate limits for different OAuth endpoints
• Audit Logging: Complete audit trail for OAuth operations with tenant context

End-to-End Encrypted Chat System

• Multi-Device Support: Seamless encryption across multiple user devices
• Quantum-Resistant Cryptography: NIST-approved post-quantum algorithms (ML-KEM-512/768/1024)
• Hybrid Encryption: Smooth transition from RSA to quantum-resistant algorithms
• Key Management: Sophisticated encryption key generation, rotation, and recovery
• File Encryption: Encrypted file uploads and downloads with thumbnail support
• Performance Optimized: Bulk encryption/decryption operations for better performance
• Security Monitoring: Real-time security anomaly detection and forensic audit trails
• Cross-Platform Compatibility: Support for different device types and encryption implementations
• Algorithm Negotiation: Automatic selection of best compatible encryption algorithms
• Migration Tools: Comprehensive utilities for upgrading to quantum-resistant encryption

Quantum Cryptography Features

• NIST-Approved Algorithms: ML-KEM (CRYSTALS-KYBER) key encapsulation mechanism
• Security Levels: Support for ML-KEM-512, ML-KEM-768, and ML-KEM-1024
• Hybrid Cryptography: RSA+ML-KEM combinations for transition periods
• Provider Architecture: Pluggable ML-KEM implementations (LibOQS production, fallback testing)
• Device Readiness Assessment: Automatic evaluation of quantum migration readiness
• Migration Strategies: Immediate, gradual, and hybrid migration approaches
• Real-time Health Monitoring: Quantum system status and device capability tracking
• Admin Dashboard: Comprehensive quantum security management interface
• Backward Compatibility: Seamless interoperability with existing RSA-encrypted conversations
• Performance Optimization: Caching, batching, and background processing for quantum operations

Security Features

• WebAuthn/Passkeys: Modern passwordless authentication
• Two-Factor Authentication: TOTP/Google Authenticator support
• Rate Limiting: Comprehensive rate limiting across OAuth, auth, and chat endpoints
• Activity Logging: Full activity logging with Spatie activity log package
• Trusted Device Management: Device registration and trust verification
• Session Management: Advanced session tracking and termination capabilities
• Security Audit Trails: Comprehensive logging for OAuth operations and chat encryption events

Development Notes

Key Development Patterns

• Service Layer: Business logic separated into dedicated service classes (app/Services/)
• Repository Pattern: Models use factories for testing with comprehensive relationship support
• Event-Driven Architecture: Laravel events for chat notifications, presence updates, and security alerts
• Multi-Tenant Architecture: Organization-scoped permissions and OAuth clients with tenant context
• API Rate Limiting: Different rate limits for various endpoint categories (auth, chat, OAuth)
• Centralized HTTP Client: All API calls use ApiService with automatic authentication, token refresh, and error handling

Environment Setup

• Concurrency Scripts: composer dev and composer dev:ssr run multiple services in parallel
• Docker Integration: Full containerization with separate configs for local/dev/staging/prod
• SSR Configuration: Inertia.js server-side rendering on port 13714
• File Storage: MinIO S3-compatible storage with encryption support
• Database Testing: Separate test database with comprehensive seeding

Code Quality Tools

• Backend: Laravel Pint for PHP formatting, Pest for testing
• Frontend: ESLint + Prettier with TypeScript strict mode
• E2E Testing: Playwright with comprehensive chat and encryption test suites
• Specialized Testing: Custom scripts for E2EE validation and performance benchmarking

Data Manipulation Rules

• NEVER use php artisan tinker: Tinker should never be used for data manipulation, seeding, or any database operations
• Use proper seeders: For database seeding, always use php artisan db:seed with proper seeder classes in database/seeders/
• Use migrations: For schema changes, create and run migrations with php artisan make:migration and php artisan migrate
• Use factories: For test data generation, use model factories with php artisan make:factory
• Use Artisan commands: Create custom Artisan commands for one-time data operations with php artisan make:command
• Production safety: Tinker poses significant risks in production environments and should be avoided entirely

Key Configuration Files

• composer.json - Development scripts and dependency management
• docker-compose.yml - Local development environment
• vite.config.ts - Frontend build configuration with SSR support
• components.json - shadcn/ui configuration
• tsconfig.json - TypeScript configuration with path aliases

HTTP Client Usage

All frontend API requests must use the centralized ApiService instead of direct fetch calls:

import apiService from '@/services/ApiService';

// GET request
const data = await apiService.get<ResponseType>('/api/endpoint');

// POST request
const result = await apiService.post<ResponseType>('/api/endpoint', payload);

// File upload
const formData = new FormData();
formData.append('file', file);
const response = await apiService.postFormData<ResponseType>('/api/upload', formData);

// Public endpoints (no authentication)
const publicData = await apiService.getPublic<ResponseType>('/api/public/endpoint');

Benefits of using ApiService:

• Automatic authentication token management
• Token refresh on expiration
• Consistent error handling across all API calls
• CSRF protection for web requests
• User session management across browser tabs

Quantum Cryptography API

Backend API Endpoints

All quantum endpoints are available under /api/v1/quantum/ with authentication required:

// Key generation
POST /api/v1/quantum/generate-keypair
{
  "algorithm": "ML-KEM-768",  // ML-KEM-512, ML-KEM-768, ML-KEM-1024
  "security_level": 768
}

// Key encapsulation  
POST /api/v1/quantum/encapsulate
{
  "public_key": "base64_encoded_key",
  "algorithm": "ML-KEM-768"
}

// Key decapsulation
POST /api/v1/quantum/decapsulate  
{
  "ciphertext": "base64_encoded_ciphertext", 
  "private_key": "base64_encoded_key",
  "algorithm": "ML-KEM-768"
}

// Device registration
POST /api/v1/quantum/register-device
{
  "device_name": "My Phone",
  "device_type": "mobile",
  "capabilities": ["ml-kem-768", "ml-kem-1024"]
}

// Algorithm negotiation
GET /api/v1/quantum/conversations/{id}/negotiate-algorithm

// Health check
GET /api/v1/quantum/health

Frontend Usage Examples

Basic Quantum Encryption

import { useQuantumE2EE } from '@/hooks/useQuantumE2EE';
import apiService from '@/services/ApiService';

const { encryptMessage, quantumStatus } = useQuantumE2EE();

// Generate quantum keypair using ApiService
const keypair = await apiService.post('/api/v1/quantum/generate-keypair', {
  algorithm: 'ML-KEM-768',
  security_level: 768
});

// Encrypt with quantum algorithm
const encrypted = await encryptMessage(
  "Hello, quantum world!", 
  conversationId,
  "ML-KEM-768"
);

Device Management

import { QuantumDeviceManager } from '@/components/ui/quantum-device-manager';

<QuantumDeviceManager 
  showAddDevice={true}
  className="max-w-4xl"
/>

Health Monitoring

import { QuantumHealthIndicator } from '@/components/ui/quantum-health-indicator';

<QuantumHealthIndicator 
  showDetails={true}
  autoRefresh={true}
  refreshInterval={30000}
/>

Migration Management

import { quantumMigrationUtils } from '@/utils/QuantumMigrationUtils';
import apiService from '@/services/ApiService';

// Register device with quantum capabilities using ApiService
const deviceRegistration = await apiService.post('/api/v1/quantum/register-device', {
  device_name: 'My Device',
  device_type: 'desktop',
  capabilities: ['ml-kem-768', 'ml-kem-1024']
});

// Assess migration readiness
const assessment = await quantumMigrationUtils.assessMigrationReadiness();

// Start migration
const migrationId = await quantumMigrationUtils.startMigration('gradual');

// Monitor progress
const status = quantumMigrationUtils.getMigrationStatus();

Admin Dashboard

import { QuantumAdminPanel } from '@/components/ui/quantum-admin-panel';

<QuantumAdminPanel className="container mx-auto" />

Quantum Algorithm Support

Supported Algorithms

• ML-KEM-512: 128-bit security level, smaller keys (fastest)
• ML-KEM-768: 192-bit security level, balanced performance (recommended)
• ML-KEM-1024: 256-bit security level, largest keys (highest security)
• HYBRID-RSA4096-MLKEM768: Transition mode combining RSA and ML-KEM

Algorithm Selection Priority

1. ML-KEM-768: Default for new conversations
2. HYBRID-RSA4096-MLKEM768: For mixed classical/quantum device compatibility
3. RSA-4096-OAEP: Fallback for legacy devices

Encryption Version History

• v1: Legacy (deprecated)
• v2: RSA-based encryption (current classical)
• v3: Quantum-resistant encryption (ML-KEM based)

Testing Quantum Features

Backend Testing

# Run quantum-specific tests
php artisan test --filter=Quantum

# Test ML-KEM provider implementations
php artisan test tests/Feature/QuantumCryptoServiceTest.php

# Test API endpoints
php artisan test tests/Feature/Api/QuantumControllerTest.php

Frontend Testing

# Run quantum E2EE tests
./scripts/test-e2ee.sh quantum

# Test device migration
npm run test:e2e -- --grep "quantum.*migration"

# Test algorithm negotiation
npm run test:e2e -- --grep "quantum.*negotiation"

Development Setup

# Install LibOQS (production ML-KEM provider)
# Ubuntu/Debian:
sudo apt-get install liboqs-dev

# macOS:
brew install liboqs

# For development/testing, fallback provider is used automatically
# when LibOQS is not available