Phase 3: Web UI Foundation (Rewritten for SvelteKit)#

This phase finalizes the web-based UI for CipherSwarm using a modern JSON API architecture and a SvelteKit frontend. During Phase 2, many backend endpoints were completed. Phase 3 ensures the SvelteKit frontend is integrated cleanly, consumes JSON from /api/v1/web/*, and is styled with Shadcn-Svelte (not Flowbite). All user-visible routes must include proper Playwright E2E tests.

Table of Contents#

• Phase 3: Web UI Foundation (Rewritten for SvelteKit)
  • Table of Contents
  • Summary
  • Key Architectural Changes & Lessons Learned
    • SPA to SSR Migration Accomplishments
    • Technology Stack Changes
    • Testing Architecture Improvements
    • Component Architecture Established
    • Docker & DevOps Infrastructure
  • Implementation Tasks
    • General Frontend Setup
    • Dashboard Implementation
    • Agent UI Implementation
    • Attack Editor Implementation
    • Campaign View Implementation
    • Resource UI Implementation
    • User & Project Management
    • Toasts and Notifications
    • Development & Deployment Infrastructure
  • Design Goals & User Experience Intent
    • Authentication & User Management UX
    • Campaign Management UX
    • Attack Editor UX
    • Agent Management UX
    • Resource Management UX
    • Crackable Uploads UX
    • Real-Time Updates & Notifications
    • Visual Design System
    • Form Handling Philosophy
  • Visual Theme
  • DevOps & Build Tasks
  • Testing Coverage
  • Template Migration Accomplishments
    • Major UI Sections Completed
    • Component Architecture Established
    • Testing Foundation Complete
  • SPA to SSR Migration Accomplishments
    • Fundamental Architecture Changes
    • SSR Route Implementation Complete
    • Form Migration to SvelteKit Actions
    • "Stock Shadcn-Svelte" Philosophy Success
    • Backend State Management Evolution
    • Testing Architecture Transformation
  • Three-Tier Testing Architecture Accomplishments
    • Testing Layer Implementation
    • Docker E2E Infrastructure Implementation
    • E2E Data Seeding Architecture
    • Playwright E2E Configuration
    • Testing Command Integration
    • Testing Patterns & Lessons Learned
    • Current Implementation Status
  • SSR Authentication Implementation
    • Problem Statement
    • Authentication Architecture Strategy
    • Test Environment Integration
    • Implementation Phases
    • FastAPI Backend Requirements
    • Success Criteria
    • Current Blockers
    • Documentation Update
  • Visual Theme Configuration

🎯 Major Accomplishment: The complete migration from HTMX/Jinja templates to SvelteKit has been successfully completed via the Template Salvage side quest. All legacy templates have been converted to modern Svelte components with comprehensive test coverage.

🎯 Major Architectural Evolution: Successfully migrated from SvelteKit SPA (static) to fully decoupled SSR architecture via the SPA to SSR Migration side quest. This fundamental change provides proper SEO, deep linking, progressive enhancement, and server-side data loading while maintaining modern SvelteKit patterns.

🎯 Major Testing Infrastructure Evolution: Successfully implemented a comprehensive three-tier testing architecture via the Full Testing Architecture side quest. This system provides fast backend tests, mocked frontend tests for rapid iteration, and full Docker-based E2E tests for complete integration validation.

Skirmish is responsible for implementing all views from scratch in SvelteKit using only JSON APIs. No templates from Phase 2 will be reused. This phase includes full component layout, state management, validation, and test coverage.

✅ Template Migration Complete: All Jinja templates have been successfully converted to Svelte components with full Playwright e2e test coverage and comprehensive unit test coverage where appropriate. The template salvage effort resulted in complete UI modernization.

✅ SPA to SSR Migration Complete: Complete architectural migration from SvelteKit SPA to decoupled SSR architecture with proper server-side data loading, form actions, and progressive enhancement. All routes now use SSR load functions with proper error handling and test environment detection.

✅ Three-Tier Testing Architecture Complete: Comprehensive testing infrastructure implemented with Docker-based E2E testing, service layer data seeding, and Playwright global lifecycle management. Testing patterns established for SSR applications with extensive lessons learned captured.

🔄 SSR Authentication Analysis Complete: Comprehensive analysis of SSR authentication requirements completed with detailed implementation strategy developed. Architecture patterns defined for session management, server-side API clients, and test environment integration. Implementation remains the critical blocker for full E2E testing capability.

A new test-seeding endpoint needs to be created in the backend to seed the database with the necessary data for the e2e tests. The existing e2e tests that rely on mock data need to be reclassified as integration tests, and new e2e tests need to be written that fully validate the functionality of the frontend and the backend together.

Summary#

• Backend endpoints are complete
• ✅ COMPLETED: All UI has been implemented using SvelteKit with Shadcn-Svelte components
• ✅ COMPLETED: All HTML templates from Phase 2 have been converted to SvelteKit components
• ✅ COMPLETED: Comprehensive Playwright e2e test coverage implemented for all UI components
• ✅ COMPLETED: All legacy HTMX, Alpine.js, and Flowbite JS removed
• ✅ COMPLETED: Complete migration from SvelteKit SPA to decoupled SSR architecture
• ✅ COMPLETED: All routes migrated to SSR with proper load functions and error handling
• ✅ COMPLETED: All forms migrated from modal-based to SvelteKit actions with Superforms
• ✅ COMPLETED: Docker infrastructure for decoupled frontend/backend services
• ✅ COMPLETED: Three-tier testing architecture (backend, frontend mocked, full E2E)
• ✅ COMPLETED: Complete Docker E2E infrastructure with data seeding and health checks
• ✅ COMPLETED: Service layer-based E2E data seeding with Pydantic validation
• ✅ COMPLETED: Playwright global setup/teardown for Docker lifecycle management
• ✅ COMPLETED: Testing patterns established for SSR applications with comprehensive lessons learned
• 🔄 PARTIALLY COMPLETED: SSR authentication analysis and implementation strategy
• ❌ PENDING: SSR authentication implementation (critical blocker for full E2E testing)
• New e2e tests need to be written that fully validate the functionality of the frontend and the backend together that replicate all of the existing e2e tests, but relying on the new test-seeding endpoint to seed the database with the necessary data and then validate the functionality of the frontend and the backend together.
• ✅ COMPLETED: All frontend views have corresponding Playwright-based E2E tests

Key Architectural Changes & Lessons Learned#

SPA to SSR Migration Accomplishments#

Fundamental Architecture Changes#

• ✅ COMPLETED: Migrated from adapter-static to adapter-node for full SSR capability
• ✅ COMPLETED: Decoupled frontend and backend services (SvelteKit server + FastAPI API)
• ✅ COMPLETED: Implemented proper environment-based API configuration
• ✅ COMPLETED: Server-side data loading with +page.server.ts load functions
• ✅ COMPLETED: Progressive enhancement with JavaScript-optional functionality
• ✅ COMPLETED: Deep linking and URL sharing functionality restored

"Stock Shadcn-Svelte" Philosophy Implementation#

• ✅ COMPLETED: Leveraged Superforms' built-in SvelteKit integration instead of custom API clients
• ✅ COMPLETED: Standard SvelteKit form actions (POST to same route) for all forms
• ✅ COMPLETED: Superforms handles validation & progressive enhancement out-of-the-box
• ✅ COMPLETED: Server-side conversion of validated data to CipherSwarm API format
• ✅ COMPLETED: Components stay close to stock Shadcn-Svelte patterns for maintainability

SSR Route Migration Complete#

• ✅ COMPLETED: All major routes converted from client-side API calls to SSR data loading:
  • Dashboard (/) with live stats widgets and SSR initial data
  • Campaigns (/campaigns, /campaigns/[id]) with pagination and search via URL state
  • Attacks (/attacks) with filtering and sorting through URL parameters
  • Agents (/agents) with real-time status monitoring
  • Resources (/resources, /resources/[id]) with metadata and preview
  • Users (/users) with role-based access control and admin functionality
  • Projects (/projects) with project switching and permission management
  • Settings (/settings) with configuration management

SSR Authentication Challenge Identified#

• 🔄 ANALYSIS COMPLETED: Comprehensive authentication strategy developed for SSR architecture
• ❌ CRITICAL BLOCKER: SSR load functions require authenticated API calls but no session handling exists
• Technical Gap: Need to implement session-based authentication for server-side data loading
• Impact: E2E tests fail due to 401 responses from authentication-required endpoints
• Solution Strategy: Session cookie management with SvelteKit hooks and server-side API client
• Backend Requirements: Session-based auth endpoints and CORS configuration for cookie handling

Comprehensive Form Migration#

• ✅ COMPLETED: All modal-based forms converted to dedicated routes with SvelteKit actions:
  • Campaign editor: /campaigns/new, /campaigns/[id]/edit (Superforms + Zod validation)
  • Attack editor: /attacks/new, /attacks/[id]/edit (Multi-step wizard with sliding cards)
  • User management: /users/new, /users/[id] (Role management with form actions)
  • Resource upload: /resources/upload (FileDropZone with progressive upload)
  • Delete confirmations: Proper form actions with impact assessment
• ✅ COMPLETED: Environment detection for test scenarios with mock data fallbacks
• ✅ COMPLETED: Proper error handling and success feedback for all form workflows

Technology Stack Changes#

• ✅ COMPLETED: Migrated from Flowbite to Shadcn-Svelte as primary UI component library
• ✅ COMPLETED: Implemented SvelteKit v5 with runes for reactive state management
• ✅ COMPLETED: Adopted Tailwind v4 for styling
• ✅ COMPLETED: Integrated formsnap for all form handling (no regular HTML forms)
• ✅ COMPLETED: Implemented svelte-sonner for toast notifications
• ✅ COMPLETED: Superforms v2 integration with SvelteKit form actions
• ✅ COMPLETED: Zod schemas for comprehensive form validation

Testing Architecture Improvements#

• ✅ COMPLETED: Comprehensive Playwright e2e test coverage for all UI components
• ✅ COMPLETED: Vitest unit tests for utility functions and simple components
• ✅ COMPLETED: All tests pass just frontend-check validation
• ✅ COMPLETED: Three-tier testing architecture implemented:
  • Layer 1: Backend tests with testcontainers (Python)
  • Layer 2: Frontend tests with mocked APIs (Vitest + Playwright)
  • Layer 3: Full E2E tests against real Docker backend
• ✅ COMPLETED: Docker E2E infrastructure with health checks and data seeding
• ✅ COMPLETED: Environment detection in tests with proper mock data fallbacks
• Testing Pattern: Mock API responses in Playwright tests since backend isn't running during e2e tests

Component Architecture Established#

• ✅ COMPLETED: Modular component structure in frontend/src/lib/components/
• ✅ COMPLETED: Proper separation of concerns (pages, components, utilities)
• ✅ COMPLETED: Consistent use of TypeScript interfaces for type safety
• ✅ COMPLETED: Role-based access control implemented in UI components
• ✅ COMPLETED: SvelteKit 5 runes-based stores for backend state management
• ✅ COMPLETED: SSR-compatible store hydration from server-side data
• ✅ COMPLETED: Progressive enhancement patterns throughout application

Docker & DevOps Infrastructure#

• ✅ COMPLETED: Complete Docker infrastructure for decoupled SvelteKit SSR + FastAPI:
  • Production and development Dockerfiles for both services
  • docker-compose.yml for production deployment
  • docker-compose.dev.yml for development with hot reload
  • docker-compose.e2e.yml for full-stack E2E testing
• ✅ COMPLETED: Health check configuration using /api-info endpoint (unauthenticated)
• ✅ COMPLETED: Proper service networking and dependency management
• ✅ COMPLETED: Environment variable handling across all deployment scenarios
• ✅ COMPLETED: Development command integration with three-tier testing architecture

Implementation Tasks#

General Frontend Setup#

• Create frontend/ using SvelteKit + TypeScript + Tailwind + adapter-static + eslint + prettier + vitest + playwright
• COMPLETED: Migrated to adapter-node for full SSR capability (was adapter-static)
• Install shadcn-svelte@next to support SvelteKit 5 and Tailwind 4 using pnpm in frontend/
• COMPLETED: Environment configuration setup with type-safe config loading
• COMPLETED: Server-side API client for +page.server.ts integration
• COMPLETED: Implemented shared layout with sidebar, topbar, modal container, and toast container (+layout.svelte, Sidebar, Header, Toast components)
• COMPLETED: Implemented comprehensive toast notification system using svelte-sonner
• COMPLETED: Configure frontend/app.css with Catppuccin Macchiato + DarkViolet accent (implemented via _catppuccin.scss with Bootstrap variable overrides)
• Add dark mode toggle using Shadcn-Svelte utilities

Note: The Rails backend has implemented a comprehensive Catppuccin Macchiato theme. The frontend implementation should align with these patterns when applicable.

• COMPLETED: Implemented login page (with email + password)
• COMPLETED: Implemented account/profile pages with user management
• COMPLETED: Implemented settings page
• COMPLETED: Created navigation with role-aware links and proper access control
• Wire SSE listeners for:
  • /api/v1/web/live/agents
  • /api/v1/web/live/campaigns
  • /api/v1/web/live/toasts
• COMPLETED: Defined global types and interfaces for all shared model shapes using TypeScript
• COMPLETED: Created typed load() functions for each route with proper error handling
• COMPLETED: SvelteKit 5 stores implementation for backend state management with SSR hydration

Dashboard Implementation#

• COMPLETED: Dashboard page with live data cards (Active Agents, Running Tasks, Cracked Hashes, Resource Usage)
• COMPLETED: Recent Activity and Active Tasks sections with Svelte tables
• COMPLETED: Campaign Overview Section with progress tracking
• COMPLETED: Agent Status Overview with real-time updates
• COMPLETED: Live Toast Notifications for system events
• COMPLETED: SSR data loading with +page.server.ts for dashboard statistics

Agent UI Implementation#

• COMPLETED: Agent list view with columns: name + OS, status, temp, utilization, guess rate, current job
• COMPLETED: Gear menu per row (admin-only) with options: disable agent, view details
• COMPLETED: Agent registration modal with label + project toggles (AgentRegisterModal.svelte)
• COMPLETED: Agent detail modal with comprehensive tabs:
  • Settings (label, enabled, interval, native hashcat, benchmark toggle, project assignment, sysinfo)
  • Hardware (device toggles, restart strategy, hardware flags)
  • Performance (line charts per device, utilization donuts, temp readouts)
  • Logs (realtime error log timeline with severity icons)
  • Capabilities (benchmark table with toggle, search, category filters)
• COMPLETED: All agent components (AgentDetailsModal.svelte, AgentBenchmarks.svelte, AgentHardware.svelte, AgentPerformance.svelte, AgentErrorLog.svelte)
• COMPLETED: SSR route migration (/agents) with server-side data loading and error handling
• Hook up real-time updates for performance and task status via SSE
• COMPLETED: E2E coverage for agent CRUD and detail views with comprehensive Playwright tests

Attack Editor Implementation#

• COMPLETED: Attack editor modal (AttackEditorModal.svelte) with comprehensive attack type support
• COMPLETED: Attack view modal (AttackViewModal.svelte) for read-only attack details
• COMPLETED: Form migration to dedicated routes (/attacks/new, /attacks/[id]/edit):
  • Multi-step wizard with sliding card animations
  • Attack type-specific field display (dictionary, mask, brute-force)
  • SSR resource integration with proper data loading
  • Superforms with comprehensive Zod validation
• COMPLETED: Dictionary editor with:
  • Min/max length validation
  • Searchable wordlist dropdown
  • Modifier buttons (+Change Case, etc.)
  • Preview of ephemeral list
  • "Previous Passwords" option
• COMPLETED: Mask editor with:
  • Add/Remove masks functionality
  • Inline validation
  • Real-time feedback
• COMPLETED: Brute force editor with:
  • Checkbox character classes
  • Min/max length
  • Mask generation
• COMPLETED: All attack editor fragments:
  • BruteForcePreview.svelte
  • LiveUpdatesToggle.svelte
  • PerformanceSummary.svelte
  • Estimate.svelte
  • ValidateSummary.svelte
  • AttackTableBody.svelte
• COMPLETED: Rule explanation modal (RuleExplanationModal.svelte)
• COMPLETED: SSR route migration (/attacks) with filtering and sorting through URL parameters
• Live update estimated keyspace and complexity via /api/v1/web/attacks/estimate
• Show warning + reset if editing running or exhausted attacks
• Allow JSON export/import of attack or campaign
• Validate imported schema (versioned), rehydrate ephemeral lists, re-associate by GUID
• COMPLETED: E2E coverage for all attack types with comprehensive Playwright tests

Campaign View Implementation#

• COMPLETED: Campaign list view (CampaignsList page) with:
  • Shadcn-Svelte Card, Accordion, Progress, Badge, Tooltip components
  • Table with pagination, filtering, live updates
  • Empty/error state handling
• COMPLETED: Campaign detail view (CampaignsDetail page) with attack table
• COMPLETED: Form migration to dedicated routes:
  • Campaign editor: /campaigns/new, /campaigns/[id]/edit with Superforms + Zod validation
  • Campaign delete: /campaigns/[id]/delete with impact assessment and confirmation
  • Proper navigation-based workflow instead of modal state management
• COMPLETED: Campaign progress and metrics components:
  • CampaignProgress.svelte with live data fetching
  • CampaignMetrics.svelte with auto-refresh every 5 seconds
• COMPLETED: SSR route migration (/campaigns, /campaigns/[id]) with:
  • Server-side data loading for campaigns and campaign details
  • URL state management for search and pagination
  • Proper 404 handling for non-existent campaigns
• Build CampaignAttackRow.svelte with summary: type, config, keyspace, complexity, comment
• Campaign toolbar with buttons: add attack, sort, bulk-select/delete, start/stop toggle
• Campaign view with drag-and-drop ordering and keyboard support
• Context menu per attack row: edit, duplicate, delete, move up/down/top/bottom
• Refresh campaign/attack progress live via SSE
• Show cracked hash toasts (batched if >5/sec)
• COMPLETED: E2E test coverage for campaign list, dashboard, and campaign actions

Resource UI Implementation#

• COMPLETED: Resource list page with:
  • Search/filter functionality
  • Pagination with loading states
  • Error handling and empty states
  • Comprehensive Playwright e2e test coverage
• COMPLETED: Resource detail components:
  • ResourceDetail.svelte - Main detail view
  • ResourcePreview.svelte - File content preview
  • ResourceContent.svelte - Content display
  • ResourceLines.svelte - Line-by-line view
  • ResourceLineRow.svelte - Individual line display
  • RulelistDropdown.svelte - Rule list selection
  • WordlistDropdown.svelte - Word list selection
• COMPLETED: Resource detail page (/resources/[id]) with comprehensive test coverage
• COMPLETED: Complex file upload migration (/resources/upload):
  • Converted from 32KB modal to dedicated SSR route
  • FileDropZone integration from Shadcn-Svelte-Extra for drag-and-drop
  • Hash type detection and validation
  • Multi-mode support (text paste vs file upload)
  • Formsnap integration with proper Field, Control, Label, FieldErrors components
• COMPLETED: SSR route migration (/resources, /resources/[id]) with proper metadata and preview
• COMPLETED: Resources store implementation with SvelteKit 5 runes:
  • Resource type-specific derived stores (wordlists, rulelists, masklists, charsets, dynamicWordlists)
  • SSR data hydration using $effect for reactive updates
  • Proper filtering/pagination support with URL state management
• Upload files via presigned URLs
• Resource line editor for masks/rules with:
  • Inline validation
  • Add/remove rows
  • Realtime feedback from 422 error response model

User & Project Management#

• COMPLETED: User list page with management table, filters, and actions
• COMPLETED: Form migration to dedicated routes:
  • User creation: /users/new with Superforms + Zod validation
  • User detail/edit: /users/[id] with role management and form actions
  • User deletion: Form actions with confirmation workflow and cascade deletion handling
  • Test environment detection for proper form handling
• COMPLETED: Project list page with:
  • Shadcn-Svelte table components
  • Search functionality and pagination
  • Loading/error/empty states
  • Action menus with comprehensive functionality
• COMPLETED: Project info component (ProjectInfo.svelte) with:
  • Project details display (name, description, visibility, status, user count, notes, timestamps)
  • Shadcn-Svelte Card, Badge, and Separator components
• COMPLETED: SSR route migration (/users, /projects) with role-based access control
• COMPLETED: Users & Projects store implementation with SvelteKit 5 runes and SSR hydration
• COMPLETED: Comprehensive test coverage for all user and project management features

Toasts and Notifications#

• COMPLETED: Global toast system using svelte-sonner (not Flowbite)
• COMPLETED: Specialized toast functions for CipherSwarm events:
  • Hash cracking notifications
  • Agent status updates
  • Campaign status changes
• COMPLETED: Toast utility functions with proper event handling
• Hook up cracked hash events via SSE
• Batch multiple events into summary toast
• COMPLETED: Toast appearance and functionality test coverage

Development & Deployment Infrastructure#

• COMPLETED: Complete Docker infrastructure setup:
  • Backend Dockerfile (Python 3.13 + uv package manager)
  • Frontend Dockerfile (Node.js + pnpm)
  • Production docker-compose.yml for deployment
  • Development docker-compose.dev.yml with hot reload
  • E2E docker-compose.e2e.yml for testing
• COMPLETED: Health check configuration using /api-info endpoint
• COMPLETED: Service networking and dependency management
• COMPLETED: Development command integration:
  • just test-backend (Python backend tests)
  • just test-frontend (frontend tests with mocked APIs)
  • just test-e2e (full-stack E2E with Docker backend)
  • just ci-check orchestrates all three test layers
• COMPLETED: E2E testing infrastructure:
  • Data seeding script (scripts/seed_e2e_data.py) with service layer delegation
  • Playwright global setup/teardown for Docker lifecycle management
  • Separate E2E Playwright configuration

Design Goals & User Experience Intent#

This section captures the comprehensive UX design goals and interface patterns derived from the API implementation planning. These goals guide the frontend implementation to ensure a cohesive, user-friendly experience across all CipherSwarm features.

Design Reference: See DESIGN.md in the Rails backend for comprehensive design context including user personas, brand personality ("Technical, Accessible, Performant, Minimal"), and design principles. The SvelteKit frontend should align with these design goals where applicable.

Frontend Gotchas: See GOTCHAS.md (Frontend & Accessibility section) for important implementation considerations:

• Navbar dropdown accessibility patterns
• Z-index layering with Bootstrap utilities
• Sidebar ARIA attributes for proper navigation semantics
• Turbo morph constraints (Rails-specific but relevant for understanding real-time update patterns)
• Asset caching issues to watch for during development

Authentication & User Management UX#

Design Philosophy#

• Self-service profile management: Users can update their own name and email without admin intervention
• Admin-controlled access: Role assignment and project membership changes restricted to administrators
• Clear permission boundaries: UI clearly distinguishes between self-service and admin-only functions

User Interface Patterns#

• User list table: Flowbite-inspired table component with filtering and pagination
• Role-based UI elements: Admin-only functions visually separated from user functions
• Project context awareness: All UI elements respect currently selected project context
• Immediate feedback: Profile changes and password updates provide instant confirmation

Campaign Management UX#

Core Design Goals#

• Intuitive attack ordering: Visual drag-and-drop interface with keyboard support for accessibility
• Rich attack summaries: Each attack displays type, configuration summary, keyspace, and complexity at a glance
• Lifecycle state clarity: Clear visual indicators for draft, active, and archived campaigns
• Performance transparency: Real-time progress updates and agent participation visibility

Attack Management Patterns#

• Context-aware actions: Attack actions (edit, duplicate, delete) adapt based on current state
• Bulk operations: Multi-select capabilities for efficient attack management
• Visual hierarchy: Attack positioning clearly communicated through UI ordering
• Smart defaults: New attacks inherit sensible defaults from campaign context

User Workflow Support#

• Progressive disclosure: Complex attack configurations revealed progressively
• Validation feedback: Real-time keyspace and complexity estimation during editing
• Confirmation patterns: Destructive actions require explicit confirmation with impact assessment
• Template reuse: Export/import functionality for attack and campaign templates

Attack Editor UX#

Universal Design Principles#

• Real-time feedback: Dynamic keyspace and complexity updates for unsaved changes
• Lifecycle awareness: Warnings and confirmations when editing running/exhausted attacks
• Template support: JSON export/import for attack configuration reuse
• Progressive enhancement: Complex options hidden behind expert modes

Dictionary Attack Interface#

• Smart defaults: Min/max length fields default to hash type-appropriate ranges
• Intelligent search: Wordlist dropdown with search, sorted by last modified, shows entry counts
• User-friendly modifiers: Button group for common transformations (Change Case, Substitute Characters)
• Expert options: Optional rule list dropdown for advanced users
• Dynamic wordlists: "Previous Passwords" option automatically generates from project history
• Ephemeral lists: "Add Word" interface for small, attack-specific wordlists

Mask Attack Interface#

• Inline editing: Add/remove mask lines directly in the interface
• Real-time validation: Immediate feedback on mask syntax correctness
• Ephemeral storage: Mask lists stored with attack, cleaned up on deletion
• Syntax assistance: Visual indicators and error messages for invalid masks

Brute Force Interface#

• Visual charset selection: Checkboxes for Lowercase, Uppercase, Numbers, Symbols, Space
• Range controls: Intuitive slider for min/max length selection
• Automatic generation: System generates appropriate ?1?1?... masks based on selections
• Charset derivation: Selected character types automatically populate custom charset 1

Agent Management UX#

Agent List Design#

• Information density: Compact view showing name+OS, status, temperature, utilization, performance, current job
• Role-based actions: Admin-only gear menu with disable/details options
• Real-time updates: Live status updates without page refresh
• Quick registration: Modal interface for new agent setup with immediate token display

Agent Detail Interface Structure#

Settings Tab#

• Display name logic: agent.custom_label or agent.host_name fallback pattern
• Essential controls: Enable/disable toggle, update interval, native hashcat option
• Benchmark control: Toggle for additional hash types (--benchmark-all)
• Project assignment: Multi-toggle interface for project membership
• System information: Read-only OS, IP, signature, and token display

Hardware Tab#

• Device management: Individual toggles for each backend device from --backend-info
• State-aware prompting: Apply now/next task/cancel options when tasks are running
• Graceful degradation: Gray placeholders when device info not yet available
• Hardware limits: Temperature abort thresholds and OpenCL device type selection
• Backend toggles: CUDA, HIP, Metal, OpenCL backend management

Performance Tab#

• Time series visualization: Line charts of guess rates over 8-hour windows
• Device-specific metrics: Individual donut charts showing utilization percentages
• Live updates: Real-time data via Server-Sent Events
• Historical context: Performance trends and comparative analysis

Log Tab#

• Timeline interface: Chronological AgentError entries with color-coded severity
• Rich context: Message, code, task links, and expandable details
• Filtering capabilities: Search and filter by severity, time range, task association

Capabilities Tab#

• Comprehensive benchmarks: Table view with toggle/hash ID/name/speed/category
• Expandable details: Per-device breakdowns for multi-GPU systems
• Search and filter: Quick access to specific hash types and performance data
• Benchmark management: Header button to trigger new benchmark runs

Resource Management UX#

Resource Browser Design#

• Type-aware interface: Different editing modes based on resource type (mask, rule, wordlist, charset)
• Size-based editing: Inline editing for small files, download/reupload for large files
• Metadata visibility: Line counts, file sizes, and usage information prominently displayed
• Project scoping: Resources filtered by project context with admin override

Line-Oriented Editing#

• Individual line control: Add, edit, delete operations on specific lines
• Real-time validation: Immediate syntax checking with detailed error messages
• Batch operations: Validate entire files with structured error reporting
• Preview modes: Content preview without full editing commitment

Upload Workflow#

• Type detection: Automatic resource type identification from content
• Validation pipeline: Multi-stage validation with clear error reporting
• Metadata capture: Comprehensive metadata collection during upload
• Orphan prevention: Atomic operations preventing database/storage inconsistencies

Crackable Uploads UX#

Streamlined Workflow Design#

• Dual input modes: Support both file uploads and direct hash pasting
• Intelligent parsing: Automatic hash isolation from surrounding metadata (shadow files, NTLM pairs)
• Type detection: Automated hash type identification with confidence scoring
• Validation pipeline: Multi-stage validation preventing malformed campaign creation

User Workflow Support#

• Preview interface: Confirmation screen showing detected types and parsed samples
• Override capabilities: Manual hash type selection when auto-detection fails
• Dynamic wordlist generation: Automatic wordlist creation from usernames/prior passwords
• Progress visibility: Clear status updates during upload and processing phases

Real-Time Updates & Notifications#

Server-Sent Events Design#

• Lightweight notifications: Trigger-based updates rather than full data streaming
• Targeted refreshes: Specific component updates rather than page-wide refreshes
• Reliable connections: Browser-handled reconnection with graceful degradation
• Project scoping: Events filtered by user's current project context

Toast Notification System#

• Event categorization: Different notification types for cracks, errors, status changes
• Batching logic: Multiple rapid events condensed into summary notifications
• User control: Dismissible notifications with appropriate persistence
• Visual hierarchy: Color coding and iconography for quick recognition

Visual Design System#

Theme Foundation#

• Catppuccin Macchiato: Base color palette for consistent visual identity
• DarkViolet accent (#9400D3): Primary accent color for interactive elements
• Surface hierarchy: Proper use of base, surface0, crust for layout depth
• Shadcn-Svelte integration: Theme-compatible component styling throughout

Component Patterns#

• Consistent interaction models: Similar patterns for similar operations across features
• Progressive disclosure: Complex features revealed progressively to avoid overwhelming users
• Accessibility compliance: Keyboard navigation, screen reader support, color contrast
• Responsive design: Mobile-friendly layouts with appropriate touch targets

Form Handling Philosophy#

SvelteKit Actions Integration#

• Server-side validation: Comprehensive validation with structured error reporting
• Progressive enhancement: Forms work without JavaScript enabled
• Superforms integration: Consistent form handling patterns across all features
• State management: Clean separation between form state and application state

User Feedback Patterns#

• Immediate validation: Real-time feedback on form inputs where appropriate
• Clear error messaging: Specific, actionable error messages with context
• Success confirmation: Positive feedback for completed operations
• Loading states: Clear indication of processing during form submission

Visual Theme#

• Catppuccin Macchiato base
• DarkViolet accent (#9400D3, implemented as #a855f7 in the Rails backend's _catppuccin.scss)
• Layout surfaces use base, surface0, crust with proper hierarchy:
  • Crust: Navbar background (darkest layer)
  • Mantle: Sidebar background
  • Base: Main body background
  • Surface0: Cards, inputs, and elevated surfaces
• ✅ COMPLETED: Shadcn-Svelte components provide theme-compatible styling
• ✅ COMPLETED: Fully implemented with Catppuccin Macchiato palette integrated into Bootstrap variables (Rails backend)
• Font Stack: Self-hosted fonts for air-gap safety:
  • Space Grotesk (300-700): Geometric headings
  • IBM Plex Sans (400-700): Technical body text
  • JetBrains Mono (100-800): Monospace for code/technical data
• Note: Dark mode toggle still pending implementation but theme foundation established. The Rails implementation provides a reference for proper Catppuccin Macchiato integration.

DevOps & Build Tasks#

• Set up FastAPI to serve the compiled SvelteKit frontend using StaticFiles REPLACED: Decoupled architecture with separate SvelteKit SSR server
• COMPLETED: Multi-service Docker architecture with proper service separation
• COMPLETED: SvelteKit build integration with Docker multi-stage builds
• Ensure just build-frontend builds the frontend and just dev includes frontend+backend integration
• COMPLETED: Decoupled service architecture - frontend runs on port 5173, backend on port 8000
• COMPLETED: Docker health checks and dependency management
• COMPLETED: Multi-stage Docker builds for both frontend and backend services
• Add just frontend-test target
• COMPLETED: just frontend-check command validates linting and tests
• COMPLETED: Three-tier testing command structure with CI orchestration

Testing Coverage#

• COMPLETED: Comprehensive Vitest unit tests for utility functions and simple components
• COMPLETED: Extensive Playwright E2E tests for all user-visible capabilities
• COMPLETED: All tests pass just frontend-check validation
• COMPLETED: Test coverage for all converted template components
• COMPLETED: Three-tier testing architecture implemented:
  • Backend tests: ✅ 593 passed (1 xfailed) with testcontainers (Python + pytest)
  • Frontend tests: ✅ 149 unit tests + 161 E2E tests (3 skipped) with mocked APIs (Vitest + Playwright)
  • Full E2E tests: ✅ Docker infrastructure complete with service layer data seeding (Playwright + Docker backend)
• COMPLETED: Docker E2E Infrastructure:
  • Complete Docker Compose E2E environment (docker-compose.e2e.yml)
  • Service layer-based data seeding (scripts/seed_e2e_data.py)
  • Playwright global setup/teardown with Docker lifecycle management
  • Health checks and dependency management for all services
• COMPLETED: Testing Patterns & Lessons Learned:
  • SSR vs SPA testing evolution with comprehensive patterns documented
  • Environment detection for test vs production data
  • Mock data management with exact API structure matching
  • Docker infrastructure lessons and configuration reuse strategies
• COMPLETED: Command Integration: All three test layers integrated into justfile
  • just test-backend - Python backend tests with testcontainers
  • just test-frontend - Frontend tests with mocked APIs
  • just test-e2e - Full E2E tests with Docker backend (infrastructure complete)
  • just ci-check - Orchestrates all test layers for complete validation
• COMPLETED: Environment detection in tests with proper mock data fallbacks
• PARTIALLY COMPLETED: SSR authentication analysis and implementation strategy developed
• IN PROGRESS: SSR authentication integration for complete E2E test workflows
• Backend integration tests: Create test-seeding endpoint for full e2e testing with real backend (replaced by service layer seeding)

Testing Architecture Established:

• Layer 1 (Backend): Python backend tests with testcontainers for database integration - ✅ COMPLETE
• Layer 2 (Frontend Mocked): Vitest + Playwright with mocked API responses for fast feedback - ✅ COMPLETE
• Layer 3 (Full E2E): Playwright against real Docker backend for integration validation - ✅ Infrastructure Complete
• Mock API responses in Playwright tests (Layer 2) since backend isn't running during frontend e2e tests
• Unit tests for utility functions and simple component logic
• E2E tests for full user workflows and component integration
• Docker-based E2E testing with service layer data seeding and health monitoring
• Service layer data seeding ensures consistency and validation through business logic
• Comprehensive test coverage across all UI components with established testing patterns

Template Migration Accomplishments#

✅ COMPLETED - All Legacy Templates Converted:

Major UI Sections Completed#

• Dashboard & Layout: Complete SvelteKit layout with Shadcn-Svelte components
• Agent Management: Full agent CRUD, details modal with 5 tabs (Settings, Hardware, Performance, Log, Capabilities)
• Campaign Management: List, detail, create/edit/delete modals with progress tracking
• Attack Management: Comprehensive attack editor with dictionary, mask, and brute-force support
• Resource Management: List, detail, preview, and specialized dropdown components
• User Management: Full user CRUD with forms and validation
• Project Management: Project list, info display, and management features

Component Architecture Established#

• 39 Svelte components created from legacy templates
• Shadcn-Svelte integration throughout the application (note: Rails backend uses ViewComponent with plain Bootstrap HTML, not external component libraries)
• formsnap forms with Zod validation for all user input
• TypeScript interfaces for type safety across components
• Role-based access control implemented consistently

Component Pattern Note: The Rails backend implementation removed Railsboot component abstractions in favor of plain ERB + Bootstrap classes. The SvelteKit frontend uses Shadcn-Svelte components, which is appropriate for the modern TypeScript/Svelte ecosystem, but developers should be aware that the backend uses a different philosophy (direct Bootstrap HTML without component abstraction layers).

Testing Foundation Complete#

• Comprehensive Playwright e2e tests for all UI functionality
• Vitest unit tests where appropriate for utility functions
• 100% test coverage for converted template functionality
• Lint-clean codebase passing just frontend-check

SPA to SSR Migration Accomplishments#

✅ COMPLETED - Complete Architectural Migration:

Fundamental Architecture Changes#

• SvelteKit Adapter Migration: From adapter-static (SPA) to adapter-node (SSR)
• Service Decoupling: Frontend SvelteKit server + Backend FastAPI as separate services
• Progressive Enhancement: JavaScript-optional functionality with proper fallbacks
• Deep Linking: Full URL-based navigation and sharing capability restored

SSR Route Implementation Complete#

All major application routes successfully migrated with comprehensive SSR patterns:

• Dashboard (/): SSR dashboard statistics with live widget updates
• Campaigns (/campaigns, /campaigns/[id]): Pagination, search, and detail views via SSR
• Attacks (/attacks): Filtering and sorting through URL parameters
• Agents (/agents): Real-time monitoring with SSR initial data
• Resources (/resources, /resources/[id]): Metadata, preview, and content management
• Users (/users): Role-based access control with admin functionality
• Projects (/projects): Project switching and permission management
• Settings (/settings): Configuration management with proper persistence

Form Migration to SvelteKit Actions#

Complete migration from modal-based forms to dedicated routes with SvelteKit form actions:

• Campaign Forms: /campaigns/new, /campaigns/[id]/edit, /campaigns/[id]/delete
• Attack Forms: /attacks/new, /attacks/[id]/edit (Multi-step wizard with sliding animations)
• User Forms: /users/new, /users/[id] (Role management with proper form actions)
• Resource Upload: /resources/upload (Complex file upload with FileDropZone integration)
• Environment Detection: Test scenarios with mock data fallbacks implemented

"Stock Shadcn-Svelte" Philosophy Success#

• Superforms Integration: All forms use Superforms v2 with SvelteKit form actions
• Progressive Enhancement: Forms work without JavaScript enabled
• Minimal Custom Code: Leveraged Superforms' built-in SvelteKit integration
• Maintainability: Components stay close to stock Shadcn-Svelte patterns

Backend State Management Evolution#

• SvelteKit 5 Stores: Idiomatic reactive stores using runes ($state, $derived, $effect)
• SSR Hydration: Stores hydrated from server-side data with reactive updates
• Clean Data Flow: Server loads → store hydration → reactive component updates

Testing Architecture Transformation#

• Three-Tier Structure: Backend, Frontend Mocked, Full E2E testing layers
• Docker Infrastructure: Complete containerization for development and testing
• Environment Detection: Proper test/development/production environment handling
• Health Monitoring: Application health endpoints integrated with Docker health checks

Three-Tier Testing Architecture Accomplishments#

✅ COMPLETED - Comprehensive Testing Infrastructure:

Testing Layer Implementation#

Layer 1: Backend Tests (just test-backend)#

• Technology Stack: Python 3.13 + pytest + testcontainers
• Test Scope: Backend API endpoints, services, database operations, integration testing
• Infrastructure: PostgreSQL + MinIO containers with automated lifecycle management
• Test Results: ✅ 593 tests passing (1 xfailed) with comprehensive coverage
• Performance: Fast execution with parallel test capabilities
• Status: COMPLETE ✅ - Robust backend testing foundation established

Layer 2: Frontend Mocked Tests (just test-frontend)#

• Technology Stack: Vitest (unit) + Playwright (E2E with mocked APIs)
• Test Scope: Frontend components, user interactions, SSR rendering with mock data
• Mock Strategy: Environment detection with PLAYWRIGHT_TEST flag for test data
• Test Results: ✅ 149 unit tests + 161 E2E tests (3 skipped) all passing
• Performance: Fast feedback loop for frontend development iteration
• Status: COMPLETE ✅ - Comprehensive mocked frontend testing established

Layer 3: Full E2E Tests (just test-e2e)#

• Technology Stack: Playwright against real Docker backend stack
• Test Scope: Complete user workflows with real database, API, and authentication
• Infrastructure: ✅ Docker Compose E2E environment fully implemented
• Data Strategy: Service layer-based seeding with predictable test data
• Current Status: Infrastructure complete, authentication integration pending

Docker E2E Infrastructure Implementation#

Complete Docker Architecture#

• Backend Service: FastAPI with development Dockerfile including build tools
• Frontend Service: SvelteKit SSR with Node.js and pnpm package management
• Database Service: PostgreSQL v16+ with proper networking and data persistence
• Object Storage: MinIO compatible with existing testcontainers setup
• Caching Service: Redis for backend caching and task queue support

Docker Compose E2E Configuration#

• File: docker-compose.e2e.yml - Complete E2E testing environment
• Health Checks: All services with proper readiness validation
• Service Dependencies: Ordered startup with dependency management
• Port Management: Non-conflicting port allocation for parallel development
• Volume Management: Proper data persistence and log mounting

Sample Configuration Pattern:

backend:
  build:
    context: .
    dockerfile: Dockerfile.dev
    target: development
  healthcheck:
    test: [CMD, curl, -f, http://localhost:8000/api-info]
    interval: 30s
    timeout: 10s
    retries: 5
    start_period: 60s

E2E Data Seeding Architecture#

Service Layer Data Seeding#

• File: scripts/seed_e2e_data.py - Comprehensive test data creation
• Architecture: Service layer delegation for all data persistence operations
• Validation: Pydantic schemas for all created objects with type safety
• Error Handling: Graceful cleanup and proper error propagation
• Data Strategy: Predictable test data with known credentials and IDs

Test Data Created#

• Users: Admin (admin@e2e-test.example) and regular user with known credentials
• Projects: "E2E Test Project Alpha" and "E2E Test Project Beta" with proper associations
• Campaigns: Sample campaign configurations with hash lists
• Agents: Test agent configurations with benchmark data
• Resources: Sample wordlists, rules, and attack resources

Service Layer Pattern:

async def create_e2e_test_users(session: AsyncSession) -> dict[str, int]:
    """Create test users using service layer with known credentials."""
    admin_create = UserCreate(
        username="e2e-admin",
        email="admin@e2e-test.example",
        password="admin-password-123",
        role=UserRole.admin,
        is_active=True,
    )

    # Persist through service layer (handles validation, hashing, etc.)
    admin_user = await create_user_service(session, admin_create)
    return {"admin_user_id": admin_user.id}

Playwright E2E Configuration#

Global Setup/Teardown Implementation#

• Files: frontend/tests/global-setup.e2e.ts and frontend/tests/global-teardown.e2e.ts
• Docker Management: Complete lifecycle management of Docker Compose stack
• Health Monitoring: Service readiness validation before test execution
• Data Seeding: Automated test data creation in Docker backend
• Cleanup Strategy: Proper resource cleanup with error handling

E2E Configuration Features#

• File: frontend/playwright.config.e2e.ts - E2E-specific configuration
• Serial Execution: Database consistency with single worker
• Browser Coverage: Chromium, Firefox, and WebKit testing
• Test Data Management: Integration with seeded backend data
• Real Backend Integration: Full authentication and API validation

Global Setup Pattern:

export default async function globalSetup() {
    // Start Docker stack with proper error handling
    execSync('docker compose -f ../docker-compose.e2e.yml up -d --build');

    // Wait for services with health checks
    await waitForServices();

    // Seed test data using backend container
    execSync('docker compose -f ../docker-compose.e2e.yml exec -T backend python scripts/seed_e2e_data.py');
}

Testing Command Integration#

Justfile Command Structure#

# Three-tier testing architecture
test-backend:
uv run pytest tests/ -xvs

test-frontend:
cd frontend && pnpm test && pnpm exec playwright test

test-e2e:
cd frontend && pnpm exec playwright test --config=playwright.config.e2e.ts

# Orchestrate all test layers
ci-check:
just format-check
just check
just test-backend
just test-frontend
# test-e2e pending authentication implementation

Testing Patterns & Lessons Learned#

SSR vs SPA Testing Evolution#

• Key Insight: SSR applications require different testing patterns than SPA applications
• SSR Pattern: Test actual rendered content, not loading states (data is pre-loaded)
• Environment Detection: Use PLAYWRIGHT_TEST flag for test data vs real API calls
• Store Testing: Test through component integration, not direct store unit tests
• Form Testing: Focus on SvelteKit action workflows rather than client-side form state

Mock Data Management#

• Structure Consistency: Mock data must match API response structure exactly
• Schema Validation: Use snake_case field names matching backend responses
• Environment Detection: Proper test environment detection in +page.server.ts files
• Progressive Enhancement: Test form functionality without JavaScript enabled

Docker Infrastructure Lessons#

• Configuration Reuse: Leverage existing docker-compose.dev.yml patterns
• Path Resolution: Use relative paths from frontend directory in global setup
• Service Dependencies: Proper health checks and startup ordering
• Development Mode: Use development Dockerfiles for E2E testing (includes build tools)

Test Performance Optimization#

• Layer Separation: Fast unit tests for development, comprehensive E2E for validation
• Parallel Execution: Backend and frontend tests can run in parallel
• Docker Caching: Proper image caching for faster E2E test startup
• Test Data Strategy: Predictable, minimal test data sets for reliable assertions

Current Implementation Status#

Completed Infrastructure#

• Docker Compose E2E environment: Fully functional with all services
• Data seeding architecture: Service layer-based with Pydantic validation
• Playwright global setup/teardown: Complete Docker lifecycle management
• E2E configuration: Separate config for full-stack testing
• Sample E2E tests: Authentication and project management workflows
• Command integration: All three tiers integrated into justfile

Pending Implementation#

• SSR Authentication Flow: Integration of authentication with SSR patterns
• Complete E2E Test Suite: Full coverage of all user workflows
• CI/CD Integration: GitHub Actions workflow for three-tier testing
• Performance Optimization: Docker image caching and parallel execution

Next Steps#

1. Implement SSR authentication patterns for proper E2E login workflows
2. Complete E2E test coverage for all major user journeys
3. Optimize Docker performance with better caching and startup times
4. Integrate with CI/CD for automated three-tier test execution

SSR Authentication Implementation#

ANALYSIS COMPLETED - IMPLEMENTATION PENDING

Problem Statement#

The SSR migration is fundamentally complete, but authentication remains the critical blocker for full E2E testing:

• Root Issue: SSR load functions make authenticated API calls to FastAPI backend but no session handling exists
• Current Impact: E2E tests fail because frontend service health checks return 401 responses
• Technical Gap: Migration from SPA to SSR completed without implementing server-side authentication

Authentication Architecture Strategy#

1. Session Cookie Management#

SvelteKit Hook Implementation (hooks.server.js):

export async function handle({
    event,
    resolve
}) {
    // Extract session cookie from request
    const sessionCookie = event.cookies.get('sessionid');

    // Set user context for load functions
    if (sessionCookie) {
        event.locals.session = sessionCookie;
        event.locals.user = await validateSession(sessionCookie);
    }

    return resolve(event);
}

SSR Load Function Pattern:

export const load: PageServerLoad = async ({ cookies, locals }) => {
    // Use session from hooks.server.js
    const sessionCookie = cookies.get('sessionid') || locals.session;

    if (!sessionCookie) {
        throw redirect(302, '/login');
    }

    try {
        const response = await serverApi.get('/api/v1/web/campaigns/', {
            headers: {
                'Cookie': `sessionid=${sessionCookie}`,
                'X-Requested-With': 'XMLHttpRequest'
            }
        });
        return { campaigns: response.data };
    } catch (error) {
        if (error.response?.status === 401) {
            throw redirect(302, '/login');
        }
        throw error(500, 'Failed to load data');
    }
};

2. Server-Side API Client#

Authenticated Request Handling:

export class ServerApiClient {
    async authenticatedRequest(
        endpoint: string,
        options: RequestInit,
        cookies: Cookies
    ) {
        const sessionCookie = cookies.get('sessionid');

        if (!sessionCookie) {
            throw new Error('No session cookie found');
        }

        return fetch(`${this.baseURL}${endpoint}`, {
            ...options,
            headers: {
                ...options.headers,
                'Cookie': `sessionid=${sessionCookie}`,
                'X-Requested-With': 'XMLHttpRequest'
            }
        });
    }
}

3. Login Form Integration#

SvelteKit Action-Based Login:

export const actions: Actions = {
    default: async ({ request, cookies }) => {
        const form = await superValidate(request, zod(loginSchema));

        if (!form.valid) {
            return fail(400, { form });
        }

        try {
            const response = await fetch(`${API_BASE_URL}/api/v1/web/auth/login`, {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify(form.data)
            });

            if (!response.ok) {
                return fail(401, { form, message: 'Invalid credentials' });
            }

            // Extract and set session cookie
            const setCookieHeader = response.headers.get('set-cookie');
            const sessionMatch = setCookieHeader?.match(/sessionid=([^;]+)/);

            if (sessionMatch) {
                cookies.set('sessionid', sessionMatch[1], {
                    httpOnly: true,
                    secure: true,
                    sameSite: 'strict',
                    maxAge: 60 * 60 * 24 * 7 // 7 days
                });
            }

            throw redirect(303, '/');
        } catch (error) {
            return fail(500, { form, message: 'Login failed' });
        }
    }
};

Test Environment Integration#

Environment Detection Pattern#

export const load: PageServerLoad = async ({ cookies }) => {
    // Bypass authentication in test environments
    if (process.env.NODE_ENV === 'test' ||
        process.env.PLAYWRIGHT_TEST ||
        process.env.CI) {
        return {
            campaigns: mockCampaignData,
            user: mockUserData
        };
    }

    // Normal authentication flow
    return authenticatedLoad(cookies);
};

Implementation Phases#

Phase 1: Core Authentication Setup#

• Create hooks.server.js for session handling
• Implement server-side API client with cookie management
• Create login/logout routes with proper form actions
• Update environment configuration for API endpoints

Phase 2: Load Function Updates#

• Update all +page.server.ts files to use authenticated API calls
• Implement proper error handling for 401/403 responses
• Add test environment detection for E2E tests
• Ensure cookie forwarding in all API requests

Phase 3: Testing Integration#

• Update E2E seed data to include user sessions
• Modify Docker health checks to use authenticated endpoints
• Implement login flow in E2E tests
• Test session persistence across page navigation

FastAPI Backend Requirements#

Session Endpoint Compatibility#

Backend must support:

• Session-based authentication (not just JWT)
• Cookie-based session management
• Proper CORS configuration for SvelteKit frontend
• Health check endpoints that work without authentication

Required Backend Implementation#

@app.post("/api/v1/web/auth/login")
async def login(credentials: LoginRequest, response: Response):
    user = authenticate_user(credentials.email, credentials.password)
    if not user:
        raise HTTPException(401, "Invalid credentials")

    session_id = create_user_session(user.id)

    response.set_cookie(
        "sessionid", session_id, httponly=True, secure=True, samesite="strict"
    )

    return {"success": True, "user": user}

Success Criteria#

• All SSR load functions can make authenticated API calls
• E2E tests pass with Docker backend authentication
• Session persistence works across page navigation
• Proper login/logout flow implemented
• Test environment detection bypasses authentication
• Health checks work without breaking Docker startup

Current Blockers#

1. Authentication Method: Need to determine if FastAPI backend should implement session-based auth or modify approach
2. CORS Configuration: Ensure proper CORS setup for cookie-based authentication
3. Health Check Strategy: Implement unauthenticated health endpoints for Docker startup
4. E2E Test Flow: Design proper login sequence for E2E test scenarios

Documentation Update#

• Update the architecture documentation to reflect the decoupled SvelteKit SSR + FastAPI architecture (found in docs/architecture/*.md)
• Update the API reference documentation for SSR integration patterns and server-side data loading (found in docs/api/overview.md and docs/development/api-reference.md)
• Update the user guide with new UI workflows, form patterns, and screenshots from e2e tests (found in docs/user-guide/*.md)
• Update the developer guide with SvelteKit SSR development patterns, Docker usage, and testing architecture (found in docs/development/*.md)
• Update the getting started guide with new decoupled service setup instructions and screenshots (found in docs/getting-started/*.md)
• Update the troubleshooting guide for SvelteKit SSR and Docker-specific issues (found in docs/user-guide/troubleshooting.md)
• Update the FAQ for new SSR, form handling, and Docker-related questions (found in docs/user-guide/faq.md)

Infrastructure Success: The three-tier testing architecture provides a solid foundation for development confidence. Layer 1 and Layer 2 are fully operational with excellent test coverage. Layer 3 infrastructure is complete and ready for authentication implementation to enable full-stack E2E testing.

Visual Theme Configuration#