Technical Architecture

System Overview

The “Everything That Can Happen” platform is built with a modern, edge-optimized architecture for scalability, performance, and maintainability. The stack uses Astro for the frontend (with React islands for interactivity), Cloudflare Pages for hosting, Railway for backend deployment, and supports both file-based and MongoDB storage through a repository pattern abstraction layer.

Current Production Architecture

🚀 Live Deployment:

• Frontend: https://everything-happens.pages.dev/ (Cloudflare Pages)
• Backend API: https://everything-happens-production.up.railway.app/ (Railway)

Architecture Diagram

flowchart TB
    subgraph "🌐 Production Infrastructure"
        CF[Cloudflare Pages<br>Frontend Hosting<br>Global Edge Network]
        RW[Railway<br>Backend Deployment<br>NestJS API Service]
    end

    subgraph "🖥️ Frontend Layer"
        WF[Web Frontend<br>Astro + React Islands<br>SSR Enabled]
    end

    subgraph "⚙️ Backend Services"
        GS[Game Service<br>NestJS API]
        AS[Auth Service<br>JWT + Email + RBAC]
        SS[Story Services<br>Clean Architecture]
        IS[Image Services<br>Specialized Processing]
        LS[Logging Service<br>Structured Logging]
    end

    subgraph "📊 Data Services"
        CS[CRUD Services<br>Repository Pattern]
        RP[Repository Pattern<br>Storage Abstraction]
        FB[(File-based<br>JSON Storage)]
        DB[(MongoDB Atlas<br>Cloud Database)]
    end

    subgraph "🤖 External Services"
        LLM[OpenAI API<br>GPT & DALL-E]
        EMAIL[Email Service<br>SMTP Provider]
    end

    CF --> WF
    WF <-- "HTTPS API" --> RW
    RW --> GS
    RW --> AS
    RW --> SS
    RW --> IS
    RW --> LS

    SS --> CS
    IS --> CS
    GS --> CS
    AS --> CS
    LS --> CS

    CS --> RP
    RP --> FB
    RP --> DB

    SS --> LLM
    IS --> LLM
    AS --> EMAIL
    LS --> DB

    style CF fill:#f96,stroke:#333,stroke-width:2px,color:#000
    style RW fill:#4a9,stroke:#333,stroke-width:2px,color:#000
    style WF fill:#f9f,stroke:#333,stroke-width:2px,color:#000
    style GS fill:#bbf,stroke:#333,stroke-width:2px,color:#000
    style AS fill:#bfb,stroke:#333,stroke-width:2px,color:#000
    style SS fill:#e8f5e8,stroke:#333,stroke-width:2px,color:#000
    style IS fill:#fbf,stroke:#333,stroke-width:2px,color:#000
    style CS fill:#fff3e0,stroke:#333,stroke-width:2px,color:#000
    style LS fill:#fbb,stroke:#333,stroke-width:2px,color:#000
    style RP fill:#ddf,stroke:#333,stroke-width:2px,color:#000
    style FB fill:#bfb,stroke:#333,stroke-width:2px,color:#000
    style DB fill:#9fb,stroke:#333,stroke-width:2px,color:#000
    style LLM fill:#ffd,stroke:#333,stroke-width:2px,color:#000
    style EMAIL fill:#dfd,stroke:#333,stroke-width:2px,color:#000

Component Details

1. Production Infrastructure

Cloudflare Pages (Frontend Hosting)

• Global Edge Network: Deployed to 275+ locations worldwide
• SSR Support: Server-side rendering for dynamic content
• Automatic Deployments: Connected to GitHub for continuous deployment
• Environment Management: Configuration via wrangler.toml
• Performance: Optimized static assets and edge caching

Railway (Backend Deployment)

• Containerized Deployment: Automatic Docker-based deployments
• Environment Variables: Secure configuration management
• Health Monitoring: Built-in health checks and monitoring
• Auto Scaling: Automatic horizontal and vertical scaling
• GitHub Integration: Automatic deployments from git pushes
• Custom Domains: Public HTTPS endpoints for API access

2. Web Frontend (Astro + React Islands)

• Astro-based SSR site with static optimization
• React islands for interactive game UI and dynamic features
• Hosted on Cloudflare Pages for global edge performance
• Responsive design, minimal JS shipped for static content
• Environment-specific API endpoint configuration

3. Backend Services (NestJS on Railway)

Clean Service Architecture

The backend implements a layered service architecture with clear separation of concerns, following modern software engineering principles:

graph TD
    subgraph "🎮 Controllers Layer"
        SC[StoryController<br>HTTP Endpoints]
        SMC[StoryManagementController<br>Admin Endpoints]
        AC[AuthController<br>Authentication]
    end

    subgraph "🧠 Business Logic Layer"
        SS[StoryService<br>Story Lifecycle & Permissions]
        SNS[StoryNodeService<br>AI Generation & Workflows]
    end

    subgraph "🛠️ Specialized Services"
        IGS[ImageGenerationService<br>DALL-E Integration]
        MIS[MultiLayerImageService<br>Parallax Image Management]
        IBS[ImageBackupService<br>Image Recovery & Regeneration]
    end

    subgraph "📊 Data Access Layer"
        SCS[StoryCrudService<br>Story Database Operations]
        SNCS[StoryNodeCrudService<br>Node Database Operations]
    end

    subgraph "🗃️ Repository Layer"
        SR[Story Repository<br>Storage Abstraction]
        SNR[StoryNode Repository<br>Storage Abstraction]
        DB[(MongoDB Atlas<br>Primary Storage)]
        FS[(File Storage<br>Development/Backup)]
    end

    SC --> SS
    SC --> SNS
    SMC --> SS

    SS --> SCS
    SNS --> SNCS
    SNS --> IGS
    SNS --> MIS
    SNS --> IBS

    IGS --> SNCS
    MIS --> SNCS
    IBS --> SNCS

    SCS --> SR
    SNCS --> SNR

    SR --> DB
    SR --> FS
    SNR --> DB
    SNR --> FS

    style SC fill:#e3f2fd
    style SMC fill:#e3f2fd
    style AC fill:#e3f2fd
    style SS fill:#f3e5f5,stroke:#7b1fa2
    style SNS fill:#e8f5e8,stroke:#388e3c
    style IGS fill:#e8f5e8,stroke:#388e3c
    style MIS fill:#e8f5e8,stroke:#388e3c
    style IBS fill:#e8f5e8,stroke:#388e3c
    style SCS fill:#fff3e0,stroke:#f57c00
    style SNCS fill:#fff3e0,stroke:#f57c00

Service Responsibilities

Business Logic Services

• StoryService: Story lifecycle management, permission validation, complex creation workflows
• StoryNodeService: AI story generation, image coordination, business rule validation
• StoryNodeSettingsService: AI parameter customization, settings inheritance, and validation

Specialized Services

• ImageGenerationService: DALL-E API integration, prompt optimization, image download/storage, standardized model-specific defaults
• MultiLayerImageService: Multi-layer image generation for parallax interfaces with enhanced quality selection
• ImageBackupService: Image recovery, manual regeneration, backup management
• ImagePricingService: Real-time cost calculation and transparent pricing for AI image generation
• StoryNodeSettingsService: AI parameter customization, settings inheritance hierarchy, copy-on-write behavior
• StoryNodeHealthCheckService: Health monitoring, maintenance utilities, and diagnostic operations for story nodes
• ImageLayerSettingsService: Multi-layer image customization with preset management, layered prompt control, and visual theme consistency

Recent Enhancements (v0.6.3)

Parallax Animation System

• Physics Correction: Fixed backwards parallax movement to match real-world depth perception
• Component Consistency: Unified behavior between React (ParallaxStoryDisplay.tsx) and Astro (ParallaxImageDisplay.astro) implementations
• Animation Intensities: Background (5), Middle (15), Foreground (25) for realistic depth effects

Image Quality Optimization

• Variant Selection: Foreground layers now use “original” quality variants for maximum detail
• Size Standardization: Backend image generation uses proper model-specific defaults instead of hardcoded 1024x1024
• Full-Screen Coverage: Foreground images sized at 105% width for complete viewport coverage

Technical Improvements

• Cross-Component Synchronization: Both parallax implementations maintain identical behavior
• Quality vs Performance: Background/middle layers optimized for performance, foreground prioritizes quality
• Backward Compatibility: All changes maintain compatibility with existing stories

Data Access Services

• StoryCrudService: Pure CRUD operations for Story entities
• StoryNodeCrudService: Pure CRUD operations for StoryNode entities

Maintenance and Health Services

• StoryNodeHealthCheckService: Dedicated service for story node health monitoring, diagnostic operations, and maintenance utilities. This service handles all health checks and fix operations that should be run manually via admin endpoints rather than during normal user flows. Provides basic node existence checks, advanced health diagnostics, and extensible framework for future maintenance operations.

Story Node Health Check System

The health check system provides a dedicated framework for maintenance operations that are separated from normal user flows to ensure optimal performance and proper administrative oversight.

Core Architecture:

• Service Pattern: {Module}HealthCheckService naming convention for consistency
• Admin-Only Access: All endpoints require ADMIN or MODERATOR role authorization
• Structured Logging: Comprehensive logging of all health check operations with user context
• Performance Isolation: Health checks run independently of user-facing operations

Available Endpoints:

• POST /admin/story-node-health/check-node/:nodeId: Basic node existence and validation checks
• POST /admin/story-node-health/advanced-check/:nodeId: Comprehensive health diagnostics with detailed reporting

Implementation Benefits:

• Performance Optimization: Removes maintenance operations from critical user paths
• Administrative Control: Provides manual execution control for maintenance operations
• Extensible Framework: Designed to support future health check and fix utilities
• Audit Trail: Full logging of all maintenance operations for system monitoring

Future Expansion Capabilities:

• View count fixing and validation utilities
• Orphaned node detection and cleanup
• Data consistency validation across story trees
• Performance optimization recommendations
• Automated maintenance scheduling and reporting

Service Architecture Benefits

1. Clear Separation of Concerns: Business logic separate from data access
2. Single Responsibility: Each service has one focused purpose
3. Clean Dependencies: Unidirectional dependency flow
4. Easy Testing: Services can be tested independently
5. Maintainability: Changes isolated to specific service layers
6. Scalability: Services can be optimized or scaled independently

Image Layer Settings System

The Image Layer Settings system provides advanced control over multi-layer image generation, allowing storytellers to create consistent visual themes through customizable presets and per-layer prompt configuration. The layer settings get passed to new story nodes from the parent, so you can customize presets at key points in the story for the settings to be automagically applied to child nodes and their branches.

Architecture Overview

Core Components:

• ImageLayerSettingsController: RESTful API for CRUD operations on image layer settings
• ImageLayerSettingsService: Business logic for preset management, validation, and sharing
• ImageLayerSettingsRepository: Data persistence with MongoDB integration
• ImageLayerSettingsSchema: Comprehensive data model with validation rules

Key Features

Preset Management System:

• UUID-based Presets: Unique identifiers for sharing settings across story nodes
• Template Presets: Pre-configured visual themes (Fantasy, Sci-Fi, Horror, etc.)
• Custom Presets: User-created configurations for specific visual styles
• Copy-on-Write: Smart duplication when updating shared presets

Layer-Specific Configuration:

• Background Layer: Environmental and atmospheric settings
• Middle Layer: Character and main content customization
• Foreground Layer: Overlay and special effects control
• Per-Layer Prompts: Independent AI instructions for each visual layer

Visual Consistency Features:

• Theme Templates: Pre-configured settings for common story genres
• Style Inheritance: Automatic application of visual themes
• Quality Settings: Configurable image generation quality per layer
• Size Optimization: Layer-specific image dimensions for performance

Integration Points

Frontend Integration:

• React Components: ImageLayerSettingsForm, PresetSelector, LayerConfigPanel
• Real-time Validation: Immediate feedback on configuration changes
• Preview System: Visual representation of layer combinations
• Preset Dropdown: Easy selection and switching between configurations

Backend Integration:

• Story Node Linking: Each story node can reference a specific preset UUID
• Automatic Application: Settings applied during image generation workflow
• Inheritance Resolution: Automatic parent-to-child settings inheritance
• Fallback Hierarchy: Graceful degradation when presets are unavailable
• Cost Calculation: Integration with pricing system for accurate estimates

Inheritance Architecture

Hierarchical Settings Resolution:

The system implements a sophisticated inheritance chain that resolves image layer settings through multiple levels with clear priority ordering:

1. Node-specific preset UUID (highest priority): Direct preset assignment overrides all inheritance
2. Parent node preset UUID (inherited): Settings flow down from parent nodes automatically
3. Story-wide default settings (fallback): Story-level configuration as backup
4. System default settings (lowest priority): Built-in system defaults ensure functionality

Inheritance Implementation:

Resolution Algorithm Workflow:

• Node Validation: Identify current story node and validate relationships
• Direct Assignment Check: Verify if node has explicitly assigned preset UUID
• Parent Chain Traversal: Walk up story tree to find inherited settings
• Story Default Fallback: Apply story-wide configuration if no inheritance found
• System Default Application: Use built-in defaults as final fallback option

Data Model Integration:

• Story Node Entity: Contains optional preset UUID reference for override capability
• Parent Relationship: Maintains story tree structure for inheritance resolution
• UUID References: Links to preset configurations through unique identifiers
• Async Resolution: Handles complex inheritance chains with efficient lookup patterns

Branch Differentiation Support:

• Sibling Independence: Child nodes from the same parent can use different presets
• Branch Tracking: System maintains inheritance chains for complex story trees
• Performance Optimization: Cached resolution prevents repeated parent lookups
• Conflict Resolution: Node-specific settings always override inherited settings

Layer-Specific AutoGenerateImages Inheritance (v0.6.5):

The system now properly handles layer-specific autoGenerateImages settings during node generation:

• Inheritance Collection: Upfront collection of inherited layer settings UUIDs before image generation
• Temporary NodeImages Structure: Creates temporary structure with inherited UUIDs for new nodes
• Data Flow Fix: Ensures both layer instruction loading and autoGenerate checking have access to correct UUIDs
• Per-Layer Control: Respects individual layer autoGenerateImages settings, allowing fine-grained control over which layers generate images
• Cost Optimization: Prevents unwanted image generation, reducing AI costs when layers are disabled
• Legacy Fallback Prevention: Eliminates fallback to legacy layer configuration when proper settings are available

UUID Inheritance Rule (Critical):

🚨 CRITICAL: Child nodes must inherit the exact same imageLayerSettingsUUID from their parent node, never create copies. This prevents unnecessary database bloat and maintains proper shared settings architecture.

Inheritance Behavior:

• Direct UUID Reference: Child nodes inherit parent’s imageLayerSettingsUUID directly
• No New Records: Inheritance never creates new settings records
• Single Source of Truth: Multiple nodes share the same settings record for consistency

When New Settings Records Are Created:

1. Initial Story Creation: When no parent exists to inherit from
2. Manual Customization: When users explicitly create custom settings
3. Explicit Branching: When users choose to “branch” from inherited settings

Implementation Note:

• The inheritFromParentNode() method uses direct UUID reference, not createByCopy()
• This ensures shared settings behavior and prevents record duplication
• Child nodes can still override settings by creating their own custom record

Persistent Images Implementation (Fixed v0.6.9.8):

🔄 FIXED: Persistent images feature now works correctly for the Parallax Astro theme through robust endpoint implementation.

Endpoint Behavior (GET /api/v1/stories/nodes/:nodeId/persistent-image/:layer):

• Layer-Specific Settings: First checks node’s nodeImages[layer].imageLayerSettingsUUID for layer-specific persistentImages setting
• Story-Level Fallback: Falls back to story-level persistentImages setting when layer settings are missing
• Default Enabled: Defaults to persistentImages: true when no settings are found, ensuring backward compatibility
• Recursive Search: Performs parent chain traversal to find inherited images when persistent images are enabled

Robust Compatibility:

• Pre-Migration Nodes: Works correctly for nodes created before the ImageLayerSettings migration
• Missing UUIDs: Handles nodes without proper imageLayerSettingsUUID structure gracefully
• Mixed Configurations: Supports stories with both new layer-specific and legacy story-level settings
• Fallback Strategy: Multiple fallback levels ensure feature works regardless of migration status

Frontend Integration:

• Automatic Detection: Client-side script automatically calls persistent image endpoint for each layer
• Visual Inheritance: Applies inherited images with proper styling and opacity indicators
• Debug Logging: Comprehensive console logging for troubleshooting inheritance chains
• Performance: Only applies inherited images when current node lacks layer-specific images

Performance Optimizations

Caching Strategy:

• Preset Caching: Frequently used presets cached in memory
• UUID Resolution: Fast lookup for preset configurations
• Template Preloading: Common templates loaded at application start
• Lazy Loading: On-demand loading of custom presets

Database Optimization:

• Indexed Queries: Optimized lookups by UUID and usage patterns
• Bulk Operations: Efficient handling of multiple preset operations
• Change Tracking: Minimal updates for configuration modifications
• Cleanup Procedures: Automatic removal of unused custom presets

Image Generation Pricing System

The pricing system provides transparent cost calculation and tracking for AI image generation, enabling informed decision-making and accurate cost monitoring across the platform.

Architecture Overview

graph TB
    subgraph "💰 Pricing Calculation Flow"
        USER[User Selection] --> FORM[Story Creation Form]
        FORM --> FRONTEND[Frontend Pricing Calc]
        FRONTEND --> DISPLAY[Real-time Price Display]
        FORM --> SUBMIT[Form Submission]
        SUBMIT --> BACKEND[Backend Validation]
        BACKEND --> STORE[Store Pricing Data]
    end

    subgraph "🔢 Pricing Engine"
        CONSTANTS[Pricing Constants]
        CALC[Calculate Function]
        FORMAT[Format Function]
        VALIDATE[Validation Logic]
    end

    subgraph "📊 Cost Tracking"
        DB_STORY[(Story Records<br>Estimated Costs)]
        LOG_TOKEN[TOKEN Category Logs<br>Actual Costs]
        MONITOR[Cost Monitoring<br>Admin Interface]
    end

    FRONTEND --> CONSTANTS
    BACKEND --> CALC
    CALC --> FORMAT
    STORE --> DB_STORY
    BACKEND --> LOG_TOKEN
    LOG_TOKEN --> MONITOR

    style USER fill:#e3f2fd
    style CONSTANTS fill:#f3e5f5,stroke:#7b1fa2
    style CALC fill:#e8f5e8,stroke:#388e3c
    style DB_STORY fill:#fff3e0,stroke:#f57c00

Core Components

Pricing Constants (backend/src/constants/image-pricing.constants.ts):

• Comprehensive Pricing Table: All AI models, sizes, and quality combinations
• Utility Functions: Calculation, formatting, and validation utilities
• Type-Safe Structure: Full TypeScript support with proper typing

Frontend Pricing System:

• Real-time Calculation: Immediate price updates as users change settings
• EstimatedPriceDisplay Component: Dedicated React component for price visualization
• Form Integration: Seamless integration with story creation and editing forms
• State Management: Efficient React hooks for live price updates

Backend Integration:

• Automatic Price Calculation: Stories automatically store estimated costs
• Enhanced Logging: TOKEN category logs include detailed pricing information
• CRUD Service Integration: Price calculation during story creation and updates
• Validation: Backend verification of frontend pricing calculations

Pricing Features

Real-time Price Display Features:

• Dynamic Calculation: Instant price updates as users modify generation parameters
• Visual Breakdown: Clear display of model, size, and quality selections
• Cost Transparency: Real-time preview of estimated generation costs
• User Interface Integration: Seamlessly embedded in story creation workflows

Cost Tracking Integration:

• Automatic Price Storage: Stories automatically store estimated generation costs
• Backend Validation: Server-side verification of pricing calculations
• Audit Trail: Complete tracking of estimated vs actual costs
• Integration with CRUD Operations: Seamless price calculation during story operations

Enhanced TOKEN Logging:

• Detailed Cost Logging: Comprehensive tracking of actual image generation costs
• Model-Specific Categorization: Separate logging for different AI models (DALL-E, GPT-Image)
• User Context Tracking: Association of costs with specific users and stories
• Administrative Visibility: Real-time cost monitoring for system administrators

Data Schema Integration

Story Schema Enhancement:

• Cost Integration: Estimated image generation costs stored with story configuration
• Model Selection: AI generation model preferences (DALL-E 3, GPT-Image-1, DALL-E 2)
• Size Configuration: Configurable image dimensions for different use cases
• Quality Settings: Quality level preferences affecting both cost and visual output

LOG Schema Enhancement:

• Cost Categorization: Detailed tracking of image generation expenses by type
• Model Identification: Specific AI model used for cost attribution
• Quality Correlation: Link between quality settings and actual costs
• Context Preservation: Complete audit trail of generation parameters and outcomes

Performance and Scalability

Client-side Calculation:

• No API Calls: Price calculation happens in the browser
• Instant Updates: Real-time pricing without network latency
• Efficient Rendering: Minimal component re-renders

Centralized Pricing Logic:

• Single Source of Truth: Backend pricing constants authority
• Easy Updates: Pricing changes in one location
• Version Control: Track pricing changes over time

Cost Monitoring:

• Debug Endpoint: Access to detailed cost logs via /api/v1/logs/debug-recent
• Administrative Interface: Cost visibility in story management
• Audit Trail: Complete history of actual generation costs

Business Value

Cost Transparency:

• User Education: Clear understanding of generation costs
• Budget Planning: Informed decision-making for story creators
• Quality vs Cost: Visible tradeoffs between quality settings and pricing

Operational Benefits:

• Cost Tracking: Monitor actual vs estimated costs
• Usage Analytics: Understand cost patterns and optimization opportunities
• Resource Planning: Predict infrastructure costs based on usage

Story Node Settings Integration System

The Story Node Settings Integration provides granular control over AI generation parameters at the individual story node level, enabling sophisticated narrative customization and dynamic storytelling experiences.

Core Architecture

graph TB
    subgraph "🎯 Settings Resolution Flow"
        REQ[API Request] --> CTRL[StoryNodeSettingsController]
        CTRL --> SVC[StoryNodeSettingsService]
        SVC --> RESOLVE{Settings Resolution}
    end

    subgraph "🔄 Resolution Hierarchy"
        RESOLVE --> CUSTOM[Custom Node Settings]
        RESOLVE --> PARENT[Parent Node Inheritance]
        RESOLVE --> STORY[Story Defaults]
        RESOLVE --> SYSTEM[System Defaults]
    end

    subgraph "💾 Data Layer"
        CUSTOM --> SETTINGS_DB[(StoryNodeSettings Collection)]
        CUSTOM --> NODE_DB[(StoryNode Collection)]
        STORY --> STORY_DB[(Story Collection)]
    end

    subgraph "🤖 AI Integration"
        RESOLVE --> AI_PARAMS[AI Generation Parameters]
        AI_PARAMS --> GPT[GPT Generation]
        AI_PARAMS --> DALLE[DALL-E Generation]
    end

    style REQ fill:#e3f2fd
    style RESOLVE fill:#f3e5f5,stroke:#7b1fa2
    style CUSTOM fill:#e8f5e8,stroke:#388e3c
    style AI_PARAMS fill:#fff3e0,stroke:#f57c00

Technical Components

StoryNodeSettingsController:

• Settings Retrieval: API endpoints for accessing effective node parameters
• Custom Configuration: Ability to set and manage node-specific settings
• Settings Removal: Clean removal of custom settings with fallback to inheritance
• Shared Updates: Bulk update capabilities for settings used across multiple nodes
• Validation Services: Comprehensive parameter validation before application

StoryNodeSettingsService:

• Settings Resolution: Implements hierarchical fallback system (Node → Parent → Story → System)
• UUID Management: Handles unique identifier generation for settings records
• Copy-on-Write: Creates new settings versions when updating shared configurations
• Validation Engine: Comprehensive parameter validation with safety checks
• Inheritance Logic: Manages parent-child settings inheritance during node creation

Data Schema

StoryNodeSettings Collection:

• Unique Identification: UUID-based identifier for cross-referencing and sharing
• AI Personality: Custom system prompts for AI behavior and response style
• Generation Instructions: Specialized prompts for titles, narrative text, and choices
• Visual Guidance: Image generation instructions for consistent visual themes
• Audit Information: Creation and modification timestamps for tracking changes

StoryNode Reference:

• Node Identification: Unique identifiers for story node and parent story
• Settings Reference: Optional UUID linking to custom settings configuration
• Inheritance Control: Explicit flags for custom vs inherited settings behavior
• Relationship Management: Parent-child links for inheritance chain resolution

Settings Resolution Algorithm

Resolution Workflow:

1. Node-Specific Check: Verify if current node has custom settings configuration
2. Parent Chain Traversal: Walk up the story tree to find inherited settings
3. Story-Level Fallback: Apply story-wide default settings if no inheritance found
4. System Default Application: Use built-in platform defaults as final fallback

Resolution Features:

• Recursive Inheritance: Automatic traversal of parent-child relationships
• Efficient Caching: Optimized lookups to minimize database queries
• Graceful Degradation: Guaranteed settings resolution with multiple fallback levels
• Performance Optimization: Lazy loading and cached resolution for complex inheritance chains

Key Features

UUID-Based Sharing:

• Multiple nodes can reference the same settings UUID
• Enables consistent styling across related story sections
• Reduces storage overhead for shared configurations

Copy-on-Write Updates:

• Version Management: Creates new settings versions instead of modifying existing ones
• Reference Integrity: Maintains data consistency across all referencing nodes
• Bulk Updates: Efficiently updates all nodes using shared settings
• Change Isolation: Prevents unintended modifications to shared configurations

Comprehensive Validation:

• Parameter length validation (prompts must be under specific character limits)
• Content safety checks (prevents inappropriate content injection)
• AI compatibility verification (ensures parameters work with AI models)
• Performance optimization warnings (identifies settings that may slow generation)

Integration Points

AI Generation Services:

• All AI generation calls use effective parameters from this system
• Parameters are resolved just-in-time during generation requests
• Supports both GPT text generation and DALL-E image generation

Story Creation Workflow:

• New nodes automatically inherit settings from parent nodes
• Settings inheritance is applied during the node creation process
• Maintains consistency in branching narratives

Content Management:

• Storytellers can modify settings through the web interface
• Preview functionality allows testing settings before applying
• Settings can be shared between collaborating authors

Performance Optimizations

• Caching: Frequently accessed settings are cached to reduce database queries
• Lazy Loading: Settings are only resolved when needed for AI generation
• Batch Operations: Multiple setting updates are batched for efficiency
• Minimal Storage: Only stores settings that differ from defaults

Security & Authorization

• Role-Based Access: Only Storyteller+ roles can modify settings
• Story Ownership: Users can only modify settings for stories they own or have edit access to
• Input Sanitization: All parameter inputs are sanitized and validated
• Audit Logging: All settings changes are logged for security auditing

API Response Features

Settings Resolution Response:

• Settings Identification: Clear indication of custom vs inherited settings
• Parameter Details: Complete configuration data for AI generation
• Fallback Information: Visibility into inheritance chain and default values
• Context Preservation: Full audit trail of settings sources and modifications

This system enables sophisticated narrative control while maintaining clean architecture and performance through intelligent caching and fallback hierarchies.

API/Backend Architecture

• REST API for game logic, story generation, and user management
• Modular NestJS architecture with dependency injection
• Repository pattern for flexible data storage (file-based or MongoDB)
• Deployed as containerized service on Railway platform

Enhanced Story Generation Workflow

Multi-Service Coordination for Story Creation:

1. StoryNodeService: Orchestrates the overall story generation workflow
2. AI Generation: Uses OpenAI GPT-3.5-turbo for story content generation
3. Image Generation: Delegates to specialized image services for visual content
4. Data Persistence: Uses CRUD services for clean database operations
5. Business Logic: Applies validation, permissions, and workflow rules

Service Integration Workflow:

1. Story Content Generation: AI-powered narrative creation using OpenAI GPT models
2. Data Persistence: Clean database operations through dedicated CRUD services
3. Image Generation: Asynchronous visual content creation with multi-layer support
4. Business Logic: Validation, permissions, and workflow rule enforcement
5. Performance Optimization: Efficient coordination between specialized services

4. Auth Service (JWT + Email)

• Handles user authentication and email-based communication
• Implements JWT-based authentication
• Supports email verification and password reset

5. Data Storage (Repository Pattern)

Repository Interface

• Abstract interface defining core data operations
• Supports story nodes, user data, and analytics
• Enables seamless switching between storage implementations
• Consistent API regardless of underlying storage

File-based Storage Implementation

• Local JSON file storage for development
• Maintains existing file structure in data/story_nodes/
• Easy debugging and direct file access
• Suitable for local development and testing

MongoDB Atlas Implementation

• Production-ready cloud database storage
• Mongoose schemas for data validation
• Scalable and managed NoSQL solution
• Supports advanced querying and indexing

6. Logging System

The application implements a comprehensive logging system for monitoring, debugging, and audit trails.

Logging Architecture

• Centralized Logging Service: NestJS-based service with structured logging
• Multiple Log Levels: DEBUG, INFO, WARN, ERROR, FATAL
• Categorized Logging: USER, STORY, AUTH, API, SYSTEM, DATABASE, IMAGE, EMAIL, TOKEN
• Unified Interface: Single logEvent() function for consistent logging across all categories (dev journal 152)
• Dual Output: Database storage + console logging for immediate visibility
• User Context Tracking: Automatic capture of user information and IP addresses

Enhanced Token Usage Tracking

• TOKEN Log Category: Dedicated category for OpenAI API usage and cost tracking (dev journal 149)
• Comprehensive Cost Logging: Tracks both GPT text generation and DALL-E image generation costs
• Token Metrics: Detailed prompt/completion token counts for billing analysis
• Model-Specific Tracking: Separate tracking for different OpenAI models (gpt-3.5-turbo, dall-e-3, etc.)
• Cost Estimation: Real-time cost estimates based on current OpenAI pricing

Log Schema

Core Log Structure:

• Identification: Unique identifiers and categorization system
• Content: Structured title and message fields for detailed information
• Temporal Data: Precise timestamps for chronological tracking
• User Context: User identification and IP address for security auditing
• Extensible Metadata: Flexible context-specific information storage
• Token Tracking: Specialized fields for OpenAI API usage and cost monitoring

Logging Features

• Structured Metadata: Extensible metadata field for context-specific information
• Error Stack Traces: Automatic capture of error details and stack traces
• User Activity Tracking: Links logs to specific users and sessions
• Request Correlation: Request ID tracking for distributed tracing
• Performance Monitoring: Timing and performance metrics capture
• Cost Analytics: Real-time OpenAI API usage and cost monitoring

Admin Interface

• Real-time Log Viewer: Web-based interface for viewing and filtering logs
• Advanced Filtering: Filter by level, category, user, IP address, date range
• Search Functionality: Full-text search across log titles and messages
• Pagination: Efficient handling of large log volumes
• Export Capabilities: Log data export for external analysis

Unified Logging Method

Standardized Logging Interface:

• Category-Based Organization: Structured categorization (STORY, AUTH, USER, API, IMAGE, TOKEN)
• Required Parameters: Category, title, and detailed message content
• Optional Context: User identification, IP addresses, and story/node references
• Extensible Metadata: Additional context data for specialized use cases
• HTML Support: Rich message formatting for enhanced readability

Example Usage

Logging Applications:

• User Activity: Story node views, navigation patterns, interaction tracking
• Authentication Events: Login attempts, password resets, account verification
• Content Management: Story creation, editing, publishing, and sharing activities
• Cost Monitoring: AI generation usage, image processing costs, resource consumption
• Security Auditing: Access control violations, permission changes, system modifications await loggingService.logEvent( LogCategory.AUTH, “User Login”, “User logged in successfully”, req.ip, user.userUUID, undefined, // no storyId undefined, // no nodeId { userEmail: user.email, loginMethod: “email”, userAgent: req.get(“User-Agent”), } );

// API request logging await loggingService.logEvent( LogCategory.API, “Story Generation API Request”, “User accessed story generation endpoint”, req.ip, user?.userUUID, undefined, undefined, { userEmail: user?.email, endpoint: “/api/v1/story/generate-next”, method: req.method, userAgent: req.get(“User-Agent”), } );

### 7. Role-Based Access Control (RBAC)

The application implements a comprehensive RBAC system for secure access management.

#### Role Hierarchy

```typescript
enum Role {
	GUEST = "guest", // Unauthenticated users
	PLAYER = "player", // Standard authenticated users
	STORYTELLER = "storyteller", // Content creators
	MODERATOR = "moderator", // Content moderators
	ADMIN = "admin", // Full system access
}

Permission System

Permission Model:

• Action-Based Control: Create, read, update, delete operations with granular control
• Resource-Specific: Permissions tied to specific system resources (stories, users, logs)
• Constraint Support: Additional conditions for fine-grained access control
• Extensible Design: Flexible architecture for future permission types

Role Capabilities

• GUEST: Read-only access to public stories and content
• PLAYER: Can play games, make choices, save progress, create custom story branches
• STORYTELLER: Can create and edit stories, manage story content, access analytics
• MODERATOR: Can moderate user content, manage user accounts, access moderation tools
• ADMIN: Full system access including user management, system settings, logs, and analytics

Authorization Guards

Guard Architecture:

• Role-Based Protection: Route-level access control using hierarchical roles
• Permission-Based Control: Fine-grained access using action-resource combinations
• Composite Guards: Multiple guard layers for comprehensive security
• Decorator Integration: Clean, declarative security annotations

User Context

Context Management:

• Automatic Injection: User information automatically available in protected routes
• Role Information: Complete role and permission data included in context
• Session Management: Secure session handling with automatic user identification
• Request Correlation: User context linked to logging and audit trails

Security Features

• JWT-based Authentication: Secure token-based authentication
• Argon2 Password Hashing: Industry-standard password security
• Role Inheritance: Hierarchical role system with inherited permissions
• Audit Logging: All authorization decisions logged for security auditing
• Session Management: Secure session handling with automatic cleanup

8. Hierarchical Image Storage & Processing System

The platform implements a comprehensive, scalable image storage and processing system designed for collaborative storytelling with multi-layered visual content. This system provides the foundation for advanced features like parallax story interfaces and responsive image delivery.

Storage Architecture

Cloudflare R2 Object Storage with a hierarchical folder structure:

/images/story/{ifid}/node/{nodeUUID}/layer/{layerId}/{imageId}~{sizeId}.{format}

Structure Breakdown:

1. Level 1: /story/{ifid}

   • {ifid} is the unique Interactive Fiction IDentifier (UUID v4) of the story
   • Example: "A38D04D6-07B0-47B6-85F2-1379AFC221DF"

2. Level 2: /node/{nodeUUID}

   • {nodeUUID} is a UUIDv7 generated once on node creation for temporal ordering
   • Also generates deterministic UUIDv5 ({nodeUUID5}) from {ifid} + {ancestryId}
   • {ancestryId} represents full ancestry path: "0-1-2-3" (first node is always 0)

3. Level 3: /layer/{layerId}

   • Supports multiple visual layers per node
   • Standard layers: "background", "middle" (default), "foreground"
   • Extensible for custom layer types

4. Level 4: {imageId}~{sizeId}.{format}

   • {imageId}: Human-readable identifier ("main", "alt1", "derpy-looking-cat")
   • {sizeId}: Size variant from centralized definition table
     • "original" → PNG or original uploaded format
     • "full", "tablet", "mobile", "thumb" → WebP resized versions
   • {format}: File extension ("png" for originals, "webp" for resized)

Backend Services

ImagePathService (backend/src/story/services/image-path.service.ts):

• Centralized service for managing hierarchical image storage paths
• UUID generation (UUIDv7 for temporal ordering, UUIDv5 for deterministic paths)
• Path construction and validation for the hierarchical structure
• Image metadata management with comprehensive TypeScript interfaces
• Helper methods for listing variants and organizing by layers
• Input sanitization and validation

CloudflareStorageService (Enhanced):

• uploadImageHierarchical() method using new path structure
• Integration with ImagePathService for path generation
• Maintains backward compatibility with existing uploadImage() method
• Proper error handling and logging for hierarchical uploads

Image Processing Pipeline

🚀 WebAssembly-Powered Cloudflare Workers (cloudflare-workers/image-resizer.ts) handle professional-grade on-demand image resizing:

Core Technology Stack:

• WebAssembly Engine: @cf-wasm/photon for high-performance image processing
• Quality Algorithm: Lanczos3 sampling for professional-grade resize quality
• Format Conversion: PNG → WebP with configurable quality settings (80% default)
• Memory Management: Explicit .free() calls prevent memory leaks in WebAssembly
• Performance: 95% file size reduction (1.9MB → 50KB for thumbnails)

Processing Workflow:

1. Request Parsing: Extract image parameters from hierarchical URL structure

2. Cache Check: Look for existing processed image in R2 storage

3. Original Fetch: Retrieve 1024px PNG from R2 bucket ({imageId}~original.png)

4. WebAssembly Processing:

   // Load image into WebAssembly memory
   const photonImage = PhotonImage.new_from_byteslice(imageBytes);
   
   // Resize with professional Lanczos3 sampling
   const resizedImage = resize(
   	photonImage,
   	targetWidth,
   	targetHeight,
   	SamplingFilter.Lanczos3
   );
   
   // Convert format with quality settings
   const processedBytes = isWebP
   	? resizedImage.get_bytes_webp()
   	: resizedImage.get_bytes();
   
   // Critical memory cleanup
   photonImage.free();
   resizedImage.free();

5. Cache Storage: Store processed image back to R2 with proper metadata

6. Edge Response: Serve optimized image with appropriate cache headers

Key Features:

• Real Image Optimization: Actual pixel-level resizing (not CSS display sizing)
• Bandwidth Efficiency: Up to 97% smaller file sizes for thumbnails
• Quality Preservation: Lanczos3 maintains visual fidelity during downsizing
• Format Modernization: Automatic PNG → WebP conversion where supported
• Error Resilience: Graceful fallback to original images on WebAssembly failures
• Comprehensive Testing: 35/35 tests passing with WebAssembly mocking
• Memory Safety: Explicit memory management prevents worker memory leaks

Performance Metrics:

Variant	Original Size	Processed Size	Reduction	Quality
thumb	1.9MB	~50KB	97%	Lanczos3
mobile	1.9MB	~120KB	94%	Lanczos3
tablet	1.9MB	~300KB	84%	Lanczos3
full	1.9MB	~800KB	58%	Lanczos3

Technical Architecture:

• Edge Caching: 24-hour TTL for global performance optimization
• R2 Integration: Seamless integration with Cloudflare R2 object storage
• CORS Support: Proper cross-origin resource sharing headers
• Error Handling: Comprehensive error recovery and logging
• Request Lifecycle: Complete HTTP request/response management

Shared Type System

Centralized Types (backend/src/story/types/image-storage.types.ts):

• Comprehensive TypeScript interfaces for all image storage components
• Utility functions for path construction and validation
• Type guards for runtime validation
• URL generation utilities
• Size definition constants shared across backend and workers

Size Definition Table

Centralized size definitions used across backend and Workers:

Image Size Variants:

• Original: 1024px PNG format for maximum quality preservation
• Full: 1024px WebP with 85% quality for desktop viewing
• Tablet: 768px WebP with 80% quality for tablet devices
• Mobile: 480px WebP with 75% quality for mobile devices
• Thumbnail: 200px WebP with 70% quality for preview purposes

Migration Infrastructure

Migration Tools (backend/src/migrations/005-hierarchical-image-storage.ts):

• Utilities to transition from old flat structure to new hierarchical organization
• Dry-run mode for safe testing
• Automatic mapping from old paths to new structure
• UUID generation for migration (with placeholder implementation)
• Comprehensive reporting and error handling
• Batch processing capabilities

Benefits

• Scalability: Hierarchical structure supports unlimited stories and nodes without performance degradation
• Performance: On-demand resizing with edge caching reduces server load and improves global performance
• Multi-Layer Support: Native support for background/middle/foreground layers enables parallax story interfaces
• Cache-Friendly: Predictable paths enable efficient CDN caching strategies
• Developer Experience: Comprehensive TypeScript interfaces, validation, and utilities
• Future-Proof: Extensible for new sizes, layers, and formats
• Deterministic: UUIDv5 generation ensures consistent paths for reproducible builds

9. LLM Service (OpenAI API)

• Used for dynamic story and image prompt generation
• Accessed directly via OpenAI API

Data Layer Architecture

The data layer is implemented using the repository pattern, providing a clean abstraction over the storage mechanism. This allows the application to switch between storage implementations or use them simultaneously without affecting the business logic.

Repository Pattern Implementation

1. Interface Definition (IStoryRepository):

   • Core Operations: Standard CRUD operations with async/await support
   • Type Safety: Full TypeScript integration with generic type support
   • Promise-Based: Modern async patterns for database operations
   • Null Safety: Explicit null handling for missing records

2. Storage Implementations:

   • FileStoryRepository: Implements file-based storage using the local filesystem
   • MongoStoryRepository: Implements MongoDB storage using Mongoose
   • DualStoryRepository: Implements simultaneous operations on both storage systems

3. Configuration:

   • Storage type controlled via STORAGE_TYPE environment variable:
     • file (default): Uses file-based storage
     • mongo: Uses MongoDB storage
     • dual: Uses both storage systems simultaneously
   • MongoDB connection configured via environment variables:
     • MONGODB_URI: Connection string for MongoDB Atlas
     • MONGODB_DB_NAME: Database name (defaults to ‘everything-happens’)

4. Centralized Database Connection Management:

   • Unified Connection Service: DatabaseConnection singleton class handles all MongoDB connections
   • Environment Configuration: Automatically configures database name from environment variables with intelligent fallbacks
   • Connection Lifecycle: Manages connection establishment, health monitoring, and cleanup
   • Development Utilities: Provides convenient functions for scripts and migrations:

   Database Connection Patterns:

   • Simple Operations: High-level wrapper functions for basic database access

   • Complex Operations: Direct client access for advanced database operations

   • Automatic Cleanup: Guaranteed connection cleanup through proper resource management

   • Error Handling: Comprehensive error catching and resource cleanup

   • Migration Support: Simplified migration scripts with automatic connection handling

   • Error Handling: Robust connection error handling with descriptive error messages

   • Security: Credential masking in logs, secure connection management

5. Dependency Injection:

   • Repository implementations are provided through NestJS’s dependency injection
   • Services consume the repository interface without knowing the concrete implementation
   • Easy to add new storage implementations without changing business logic

MongoDB Integration

The application uses MongoDB as the primary database, with schemas defined using Mongoose. For complete schema definitions, data models, relationships, and indexing strategies, see:

📋 Schema Definitions

This dedicated document contains:

• Complete TypeScript interfaces for all schemas
• Schema features and relationships
• Entity relationship diagrams
• Indexing strategies
• Migration history
• File locations

Core Schemas Overview:

• Story Schema: High-level story metadata and entry points
• Story Node Schema: Individual story segments with choices and content
• User Schema: Authentication and role-based access control (RBAC)
• Log Schema: Comprehensive logging for monitoring and audit trails
• Analytics Schema: User behavior and story performance tracking

All schemas are located in backend/src/schemas/ and follow consistent patterns for timestamps, indexing, and validation.

Story and Image Generation Workflow (Backend - Clean Service Architecture)

This section details the process by which new story nodes and their associated images are generated and how existing nodes are handled, now implemented with clean service architecture and proper separation of concerns.

Service Coordination Overview

The story generation workflow now follows a clean layered architecture where:

• Controllers handle HTTP requests and responses
• Business Logic Services orchestrate workflows and apply business rules
• Specialized Services handle specific domains (image generation, AI processing)
• CRUD Services manage pure database operations
• Repository Layer abstracts storage mechanisms

1. New Story Node Generation (StoryNodeService.generateNextNode)

When a player makes a choice that leads to a new, non-existent story node:

1. Story Content Generation (AI Integration - GPT-3.5-turbo):

   • The StoryNodeService orchestrates the story generation workflow
   • Constructs detailed prompts including current scenario, story context, player choice, and node relationships
   • Enhanced Context: Uses parent node’s storySoFar summary for improved narrative continuity (dev journal 174)
   • Model Selection: Supports multiple models (gpt-3.5-turbo, gpt-4) with per-story configuration (dev journal 173)
   • Sends prompt to OpenAI Chat Completions API with structured JSON response format
   • Returns parsed LlmGeneratedContent with title, storyText, storySoFar, options, and imageUrl: null

2. Data Persistence (CRUD Service Delegation):

   • Clean Separation: StoryNodeService delegates all database operations to StoryNodeCrudService
   • Creates formatted StoryNodeData object with generated content
   • Saves node data through CRUD service using repository pattern
   • Repository abstraction enables MongoDB, file-based, or dual storage

3. Image Generation (Specialized Service Coordination):

   • Service Delegation: StoryNodeService coordinates with specialized image services
   • ImageGenerationService: Handles DALL-E API integration, prompt optimization, and image download
   • MultiLayerImageService: Manages multi-layer image generation for parallax interfaces
   • ImageBackupService: Provides recovery and manual regeneration capabilities
   • Conditional Generation: Respects story’s autoGenerateImages flag for cost control (dev journal 151)
   • Model Support: Configurable image generation models (dall-e-3, dall-e-2, gpt-image-1) with model-specific parameters

4. Workflow Coordination Example:

   // StoryNodeService orchestrates the complete workflow
   async generateNextNode(dto: GenerateStoryNodeDto): Promise<StoryNodeData> {
     // 1. AI story generation (business logic)
     const storyContent = await this.generateStoryContentWithAI(dto);
   
     // 2. Data persistence (delegate to CRUD service)
     const savedNode = await this.storyNodeCrudService.saveStoryNode(storyContent);
   
     // 3. Image generation coordination (delegate to image services)
     if (savedNode.autoGenerateImages) {
       await this.multiLayerImageService.generateAndAddImageForNode(savedNode);
     }
   
     // 4. Analytics and logging
     await this.incrementNodeViewCount(savedNode.nodeId);
   
     return savedNode;
   }

2. Existing Story Node Retrieval (StoryNodeService.getStoryNode)

When the frontend requests an existing story node:

1. Data Retrieval (CRUD Service Delegation):

   • StoryNodeService delegates data retrieval to StoryNodeCrudService
   • CRUD service uses repository pattern for storage abstraction
   • Supports MongoDB primary with file-based fallback

2. Retroactive Image Generation (Business Logic):

   • After successful node retrieval, StoryNodeService applies business rules
   • Checks if node lacks images but has content suitable for generation
   • Coordinates with image services for retroactive image generation
   • ImageBackupService: Handles missing image recovery and regeneration

3. Data Updates (Clean Delegation):

   • If images are generated, delegates updates to StoryNodeCrudService
   • CRUD service persists changes through repository layer
   • Maintains clean separation between business logic and data access

3. Service Architecture Benefits

Clear Responsibilities:

• StoryService: High-level story management, permissions, lifecycle
• StoryNodeService: AI generation workflows, image coordination, business rules
• StoryCrudService: Pure story entity database operations
• StoryNodeCrudService: Pure node entity database operations
• ImageGenerationService: DALL-E integration and image processing
• MultiLayerImageService: Parallax-specific image generation
• ImageBackupService: Image recovery and manual regeneration

Clean Dependencies:

• Controllers → Business Logic Services
• Business Logic Services → Specialized Services + CRUD Services
• Specialized Services → CRUD Services (for data persistence)
• CRUD Services → Repository Layer
• Repository Layer → Storage Systems

Enhanced Maintainability:

• Single Responsibility: Each service has one focused purpose
• Easy Testing: Services can be tested independently with mocked dependencies
• Flexible Storage: Repository pattern enables storage system changes
• Scalable Architecture: Services can be optimized or scaled independently

Project Folder Structure

The project is organized into distinct frontend (both Next.js and Astro), backend, documentation, and testing directories to maintain clarity and separation of concerns.

/
├── backend/                   # NestJS Backend Application
│   ├── src/
│   │   ├── chat/              # Chat module (controller, service, DTOs)
│   │   │   ├── chat.controller.ts
│   │   │   ├── chat.module.ts
│   │   │   ├── chat.service.ts
│   │   │   └── chat.dto.ts
│   │   ├── story/             # Story module with clean service architecture
│   │   │   ├── controllers/   # HTTP request handlers
│   │   │   │   ├── story.controller.ts
│   │   │   │   └── story-management.controller.ts
│   │   │   ├── services/      # Business logic and specialized services
│   │   │   │   ├── story.service.ts              # Story lifecycle management
│   │   │   │   ├── story.crud.service.ts         # Story CRUD operations
│   │   │   │   ├── story-node.service.ts         # AI generation & workflows
│   │   │   │   ├── story-node.crud.service.ts    # Node CRUD operations
│   │   │   │   ├── image-generation.service.ts   # DALL-E integration
│   │   │   │   ├── multi-layer-image.service.ts  # Parallax image management
│   │   │   │   └── image-backup.service.ts       # Image recovery & regeneration
│   │   │   ├── repositories/  # Data access layer
│   │   │   │   └── mongo-story.repository.ts
│   │   │   ├── dto/          # Data transfer objects
│   │   │   ├── interfaces/   # Service interfaces
│   │   │   └── story.module.ts
│   │   ├── auth/              # Authentication and authorization
│   │   │   ├── controllers/
│   │   │   ├── services/
│   │   │   ├── guards/
│   │   │   ├── decorators/
│   │   │   └── auth.module.ts
│   │   ├── logging/           # Centralized logging system
│   │   │   ├── logging.controller.ts
│   │   │   ├── logging.service.ts
│   │   │   └── logging.module.ts
│   │   ├── schemas/           # Mongoose schemas
│   │   │   ├── story.schema.ts
│   │   │   ├── story-node.schema.ts
│   │   │   ├── user.schema.ts
│   │   │   ├── log.schema.ts
│   │   │   └── analytics.schema.ts
│   │   ├── config/            # Configuration utilities
│   │   │   └── database-connection.ts  # Centralized database connection management
│   │   ├── repositories/      # Repository implementations
│   │   │   ├── mongo-story.repository.ts
│   │   │   ├── file-story.repository.ts
│   │   │   └── dual-story.repository.ts
│   │   ├── migrations/        # Database migrations
│   │   ├── scripts/           # Utility scripts
│   │   ├── app.controller.ts
│   │   ├── app.module.ts
│   │   ├── app.service.ts
│   │   └── main.ts            # Backend application entry point
│   ├── test/                  # Backend unit and integration tests
│   ├── node_modules/
│   ├── .gitignore
│   ├── nest-cli.json
│   ├── package.json
│   ├── README.md
│   ├── tsconfig.build.json
│   └── tsconfig.json
├── frontend/                  # Next.js Frontend Application (Legacy)
│   ├── public/                # Static assets served by Next.js
│   │   ├── data/
│   │   │   └── story_nodes/   # JSON files for story content
│   │   └── images/            # Static images for scenarios, UI etc.
│   ├── src/
│   │   ├── app/               # Next.js App Router (pages and layouts)
│   │   │   ├── chat/          # /chat page
│   │   │   ├── game/          # /game page
│   │   │   ├── page.tsx       # Root (welcome) page
│   │   │   ├── layout.tsx     # Root layout
│   │   │   └── globals.css    # Global styles
│   │   ├── components/        # Reusable React components
│   │   ├── hooks/             # Custom React hooks
│   │   ├── lib/               # Library functions, API helpers (e.g., chatgpt.ts)
│   │   ├── store/             # State management (e.g., Zustand, Redux)
│   │   ├── styles/            # Other style files
│   │   └── types/             # TypeScript type definitions
│   ├── .next/                 # Next.js build output
│   ├── node_modules/
│   ├── .gitignore
│   ├── next.config.ts
│   ├── package.json
│   ├── postcss.config.mjs
│   ├── tailwind.config.js
│   └── tsconfig.json
├── frontend-astro/            # Astro Frontend Application (Current)
│   ├── public/                # Static assets served by Astro
│   │   ├── backend/           # Copied backend data for local development
│   │   │   └── src/
│   │   │       └── data/
│   │   │           └── story_nodes/ # JSON files for story content
│   │   └── images/            # Static images for scenarios, UI etc.
│   │       └── generated/     # DALL-E generated images for story nodes
│   ├── src/
│   │   ├── components/        # Shared components
│   │   │   ├── astro/         # Astro components
│   │   │   └── react/         # React islands
│   │   ├── layouts/           # Astro layouts
│   │   ├── pages/             # Astro pages
│   │   │   ├── index.astro    # Home page
│   │   │   ├── game.astro     # Game page
│   │   │   ├── chat.astro     # Chat page
│   │   │   └── 404.astro      # Not found page
│   │   ├── hooks/             # React hooks
│   │   ├── lib/               # Shared utilities and API client
│   │   ├── store/             # State management
│   │   ├── styles/            # Tailwind and global styles
│   │   └── types/             # TypeScript types
│   ├── node_modules/
│   ├── .gitignore
│   ├── astro.config.mjs
│   ├── package.json
│   ├── tailwind.config.js
│   └── tsconfig.json
├── docs/                      # Project Documentation
│   ├── dev-journal/           # Developer journal entries
│   ├── api-documentation.md
│   ├── implementation-status.md
│   ├── project-overview.md
│   ├── technical-architecture.md
│   └── user_guide.md
├── images/                    # General project images (e.g., for READMEs, distinct from frontend/public/images)
├── tests/                     # End-to-end or integration tests (for the whole application)
├── .cursor/                   # Cursor specific files
├── .git/                      # Git repository files
└── everything-happens.code-workspace # VS Code workspace file

Key Directories & Purpose:

• backend/src: Contains all the source code for the NestJS backend, organized by modules.
• frontend/public: Static assets for the legacy Next.js frontend.
• frontend-astro/public: Static assets for the current Astro frontend, including copied backend data for local development.
• frontend-astro/src/components/react: React islands for interactive components in the Astro frontend.
• frontend-astro/src/pages: Astro pages that define the routes of the application.
• docs/: All project-related documentation, including API specs, dev journals, and architectural overviews.

Database Schema & Relationships

Backend Schema Overview

Our backend schemas are organized across multiple files for maintainability and separation of concerns:

Schema Locations:

• Core Schemas: backend/src/schemas/ - Shared schemas used across modules

Schema Files:

1. backend/src/schemas/user.schema.ts - User authentication and authorization
2. backend/src/schemas/story-node.schema.ts - Individual story segments and choices
3. backend/src/schemas/log.schema.ts - Comprehensive logging and audit trails
4. backend/src/schemas/analytics.schema.ts - User behavior and performance tracking
5. backend/src/schemas/story.schema.ts - Story metadata and configuration

MongoDB Schemas

The application uses MongoDB as the primary database, with schemas defined using Mongoose. For complete schema definitions, data models, relationships, and indexing strategies, see:

📋 Schema Definitions

This dedicated document contains:

• Complete TypeScript interfaces for all schemas
• Schema features and relationships
• Entity relationship diagrams
• Indexing strategies
• Migration history
• File locations

Core Schemas Overview:

• Story Schema: High-level story metadata and entry points
• Story Node Schema: Individual story segments with choices and content
• User Schema: Authentication and role-based access control (RBAC)
• Log Schema: Comprehensive logging for monitoring and audit trails
• Analytics Schema: User behavior and story performance tracking

All schemas are located in backend/src/schemas/ and follow consistent patterns for timestamps, indexing, and validation.

File-Based Storage Format

The application also supports a file-based storage system, primarily used for development and as a fallback. Files are stored in JSON format:

Story Node JSON Format

Located in backend/src/data/story_nodes/{nodeId}.json

{
	"nodeId": "string",
	"storyId": "string",
	"parentId": "string",
	"title": "string",
	"storyText": "string",
	"options": [
		{
			"text": "string",
			"nextNodeId": "string"
		}
	],
	"customChildren": [
		{
			"text": "string",
			"nextNodeId": "string"
		}
	],
	"imageUrl": "string",
	"layerImages": {
		"background": "string",
		"middle": "string",
		"foreground": "string"
	},
	"viewCount": 0,
	"lastViewed": "2025-05-27T12:00:00.000Z",
	"ancestryId": "string",
	"debug": {
		"openaiPrompt": "string",
		"systemPrompt": "string",
		"nodeUUID": "string",
		"ancestryId": "string",
		"nodeUUID5": "string"
	}
}

Storage Strategy

The application implements a dual-storage strategy with the following characteristics:

1. Storage Types:

   • mongodb: Primary storage system using MongoDB Atlas
   • file: File-based JSON storage
   • dual: Both systems simultaneously (configurable via STORAGE_TYPE env var)

2. Dual Storage Behavior:

   • Reads: Attempts MongoDB first, falls back to file system
   • Writes: Performs operations on both systems when in dual mode
   • Migration: Tools provided to sync data between systems

3. Repository Pattern:

   interface IStoryRepository {
   	findById(nodeId: string): Promise<StoryNode | null>;
   	save(node: StoryNode): Promise<StoryNode>;
   	update(
   		nodeId: string,
   		node: Partial<StoryNode>
   	): Promise<StoryNode | null>;
   	delete(nodeId: string): Promise<boolean>;
   	exists(nodeId: string): Promise<boolean>;
   }

4. Implementation Classes:

   • MongoStoryRepository: MongoDB implementation
   • FileStoryRepository: File system implementation
   • DualStoryRepository: Combines both storage systems

Data Migration

The system includes migration tools for:

1. Initial story seeding
2. File to MongoDB migration
3. Schema updates

Migration scripts are located in backend/src/migrations/ and can be run using:

npm run migrate:mongo      # Migrate file-based nodes to MongoDB

The migration process:

1. Scans the file system for existing story nodes
2. Validates and transforms data to match MongoDB schema
3. Checks for existing nodes in MongoDB to prevent duplicates
4. Provides detailed migration status reporting

Data Flow

1. User Interaction Flow

User → Frontend → API Gateway → Game Service → LLM/DB → Response

2. Image Generation Flow

Game Service → Image Service → Image Generation API → CDN → Frontend

3. Authentication Flow

User → Frontend → Auth Service → JWT Verification → Protected Resources

Authentication Architecture:

The system implements JWT-based authentication with the following components:

1. Frontend Authentication State:

   • Nanostores for reactive auth state management
   • LocalStorage fallback for persistent sessions
   • Automatic token validation on page load
   • Dynamic navigation based on authentication status

2. Backend JWT Implementation:

   • NestJS Passport integration with JWT strategy
   • Argon2 password hashing for security
   • JWT tokens stored in HttpOnly cookies
   • Protected routes using @UseGuards(JwtAuthGuard)

3. Authentication Endpoints:

   • POST /api/auth/login: User authentication with email/password
   • POST /api/auth/register: New user registration
   • GET /api/auth/verify: JWT token verification
   • POST /api/auth/logout: Session termination and cookie cleanup

4. Security Features:

   • JWT secret from environment variables
   • HttpOnly cookies to prevent XSS attacks
   • Secure cookie settings for production
   • Role-based authorization with @CurrentUser() decorator

5. Frontend Integration:

   • Automatic auth state synchronization
   • Protected route navigation
   • Seamless login/logout user experience
   • Error handling with graceful fallbacks

API Structure

REST Endpoints

1. Game Management

• POST /api/game/start
• POST /api/game/choice
• GET /api/game/state
• GET /api/game/history

2. User Management

• POST /api/auth/register
• POST /api/auth/login
• GET /api/auth/profile
• PUT /api/auth/profile

3. Content Management

• GET /api/content/scenarios
• GET /api/content/paths
• POST /api/content/share
• GET /api/content/explore

4. Chat/LLM Integration

• POST /api/v1/chat/completions — Proxy endpoint for ChatGPT (OpenAI) integration
  • Request: { message: string, history?: Array<{role: string, content: string}> }
  • Response: { response: string, usage: object }

5. Logging and Monitoring

• GET /api/v1/logs — Retrieve system logs with filtering and pagination (Admin only)
  • Query params: page, limit, level, category, userId, userEmail, ipAddress, startDate, endDate, search
  • Response: { logs: Log[], total: number, page: number, totalPages: number }
• GET /api/v1/logs/stats — Get logging statistics and metrics (Admin only)
  • Response: { totalLogs: number, logsByLevel: object, logsByCategory: object }
• GET /api/v1/logs/recent — Get recent log entries (Admin only)
  • Query params: limit
  • Response: Log[]
• GET /api/v1/logs/levels — Get available log levels
  • Response: string[]
• GET /api/v1/logs/categories — Get available log categories
  • Response: string[]

WebSocket Events

1. Game Events

• game:state:update
• game:choice:made
• game:image:ready

2. User Events

• user:joined
• user:left
• user:typing

Security Considerations

1. Authentication and Authorization

• JWT-based Authentication: Secure token-based authentication with HttpOnly cookies
• Role-Based Access Control (RBAC): Hierarchical role system with granular permissions
• Argon2 Password Hashing: Industry-standard password security with salt
• Session Management: Secure session handling with automatic cleanup and token validation
• Multi-factor Authentication: Email verification for account security
• Rate Limiting: API rate limiting to prevent abuse and brute force attacks

2. Data Protection

• HTTPS Encryption: End-to-end encryption for all client-server communication
• Data Encryption at Rest: MongoDB encryption for sensitive data storage
• Input Validation: Comprehensive validation using class-validator and DTOs
• XSS Protection: Content Security Policy and input sanitization
• SQL Injection Prevention: Mongoose ODM with parameterized queries
• CSRF Protection: Cross-site request forgery protection for state-changing operations

3. API Security

• Authentication Guards: NestJS guards for route-level authentication enforcement
• Authorization Guards: Role and permission-based access control at the endpoint level
• CORS Configuration: Properly configured cross-origin resource sharing
• Request Validation: Automatic request validation with error handling
• Audit Logging: Complete audit trail of all security-related events
• IP Address Tracking: User IP tracking for security monitoring and fraud detection

4. Role-Based Security Model

• Guest Access: Limited read-only access to public content
• Player Security: Authenticated access with user-specific data isolation
• Content Creator Protection: Storyteller role with content creation permissions
• Moderation Controls: Moderator role with user and content management capabilities
• Administrative Security: Admin role with full system access and audit capabilities

Performance Optimization

1. Astro’s Performance Features

• Partial Hydration (“Islands”)

  • Only hydrates interactive components
  • Static content remains lightweight HTML/CSS
  • React components load only when needed
  • Significantly reduced JavaScript payload

• Server-Side Rendering (SSR)

  • Pre-renders pages on the server
  • Faster First Contentful Paint (FCP)
  • Better SEO optimization
  • Reduced client-side processing

• Zero JavaScript by Default

  • Ships zero client-side JavaScript for static content
  • Opt-in JavaScript only where needed
  • Smaller bundle sizes
  • Faster page loads

2. Caching Strategy

• Static Asset Caching

  • Cloudflare CDN for image delivery
  • Long-term caching for story images
  • Browser-level caching for static assets
  • Automatic cache invalidation on deployments

• API Response Caching

  • Story content cached at edge
  • Cached responses for frequently accessed nodes
  • Dynamic TTL based on content type
  • Cache-Control headers optimization

3. Load Distribution

• Edge Network

  • Cloudflare Pages for global distribution
  • Automatic edge caching
  • Regional failover
  • DDoS protection

• Resource Loading

  • Lazy loading for images
  • Deferred loading for non-critical assets
  • Preloading for critical paths
  • Dynamic import for React islands

Monitoring and Logging

1. Application Monitoring

• Error Tracking: Automatic capture of errors with stack traces and context
• Performance Metrics: Request timing, database query performance, API response times
• User Analytics: User activity tracking, story progression analytics, choice patterns
• System Health: Service availability, database connectivity, external API status

2. Implemented Logging System

• Centralized Logging: NestJS-based logging service with MongoDB storage
• Structured Log Levels: DEBUG, INFO, WARN, ERROR, FATAL with appropriate routing
• Categorized Logging: USER, STORY, AUTH, API, SYSTEM, DATABASE, IMAGE, EMAIL categories
• User Context Tracking: Automatic capture of user ID, email, and IP address
• Audit Trails: Complete audit trail for user actions, authentication events, and system changes
• Real-time Monitoring: Web-based admin interface for real-time log viewing and filtering
• Advanced Search: Full-text search across log messages with metadata filtering
• Export Capabilities: Log data export for external analysis and compliance reporting

3. Log Retention and Management

• Database Storage: Persistent storage in MongoDB with indexing for performance
• Console Output: Dual output to console for immediate development visibility
• Metadata Enrichment: Automatic capture of request IDs, user agents, and contextual information
• Error Context: Stack traces and error details automatically captured and stored

Deployment Strategy

1. Infrastructure

• Container orchestration
• CI/CD pipeline
• Environment management
• Backup strategy

2. Scaling

• Auto-scaling rules
• Load balancing
• Database scaling
• Cache scaling

Advanced Frontend Features

Multi-Layered Parallax Story Interface

The platform is designed to support an advanced multi-layered parallax story interface that transforms traditional story navigation into an immersive 2.5D cinematic experience. This feature leverages modern CSS primitives and progressive enhancement to create depth and visual richness while maintaining performance and accessibility.

Key Features:

• Multi-layer image system (background, main, foreground) for visual depth
• CSS scroll-driven animations for smooth parallax effects
• View Transitions API for seamless node navigation
• Progressive enhancement ensuring compatibility across all browsers
• Responsive design optimized for all device types

Technical Implementation:

• Astro SSR for pre-rendering layer structure and metadata
• React Islands for complex parallax state management and interactions
• Modern CSS primitives including scroll-driven animations, anchor positioning, and container queries
• Cloudflare R2 storage organized by story folders for efficient layer delivery

For detailed implementation specifications, see: Multi-Layered Parallax Story Interface Design

Visual Node Editor (React Flow Integration)

The Visual Node Editor provides a sophisticated graph-based interface for story creation and management, enabling storytellers to visualize complex narrative structures and edit content directly within a node-graph interface.

Architecture Overview:

• React Flow Framework: Graph-based visualization library for complex node structures
• Real-time Synchronization: Immediate backend integration for all graph operations
• Performance Optimization: Efficient rendering for large story graphs (1000+ nodes)
• Interactive Editing: In-place editing of node content without page navigation

Core Components:

Frontend Architecture (VisualNodeEditor.tsx):

• Graph Visualization: Transform story data into React Flow compatible format
• Node Management: Create, edit, delete, and connect story nodes visually
• State Management: React hooks for managing graph state and API interactions
• Type Safety: Comprehensive TypeScript interfaces for all graph operations

Data Transformation Pipeline:

StoryNodes → transformToFlowData() → ReactFlowNodes → Graph Display
Backend API ← handleAPIUpdates() ← User Interactions ← Graph Interface

Node Types and Behaviors:

Existing Nodes:

• Visual Display: Title, content preview, connection indicators
• Inline Editing: Direct title and description editing with auto-save
• Navigation Links: Jump to specific story nodes for play-testing
• Status Indicators: Visual feedback for node completion and configuration

Missing Nodes:

• Placeholder Display: Clear visual indication of referenced but uncreated nodes
• One-Click Creation: Green “Create” button with plus icon for instant node creation
• Smart Defaults: New nodes created with sensible default content
• Cost Optimization: Skip automatic image generation to prevent unexpected AI charges

API Integration Architecture:

Node Creation:

• Endpoint: POST /api/v1/stories/nodes
• Payload Validation: Backend DTO compliance with proper field mapping
• Parent-Child Linking: Automatic relationship establishment
• Immediate UI Updates: Real-time graph updates without page refresh

Node Editing:

• Endpoint: PATCH /api/v1/stories/nodes/:nodeId
• Field Mapping: title → node title, storyText → node content
• Error Handling: Graceful error management with user-friendly messages
• State Synchronization: Local state updates reflect backend changes immediately

Performance Optimizations:

Stable Reference Management:

• React Flow Compatibility: Stable nodeTypes objects to prevent warning spam
• Callback Optimization: Efficient handler functions with proper dependency arrays
• Memory Management: Optimal resource usage for large graph structures

Graph Layout and Navigation:

• Automatic Layout: Intelligent node positioning for optimal readability
• Zoom and Pan Controls: Smooth navigation for complex story structures
• Fit-to-View: Automatic graph sizing for optimal viewing experience
• Mini-map Integration: Overview navigation for large story graphs

Error Handling and Reliability:

API Error Management:

• Network Failures: Graceful degradation with retry mechanisms
• Validation Errors: Clear user feedback for invalid operations
• Permission Checks: Role-based access control enforcement
• Data Consistency: Rollback failed operations to maintain graph integrity

User Experience Features:

Interactive Workflow:

• Single-Click Operations: Streamlined node creation and editing workflow
• Immediate Feedback: Loading states and success indicators for all operations
• Keyboard Navigation: Accessibility support for keyboard-only navigation
• Responsive Design: Optimal experience across all device types

Visual Feedback:

• Color Coding: Different visual styles for node types and states
• Connection Visualization: Clear representation of story flow and relationships
• Status Indicators: Icons and styling to show node completion status
• Animation Effects: Smooth transitions for state changes and updates

Technical Implementation Details:

State Management Pattern:

// Graph data loading and transformation
const [nodes, setNodes] = useState<Node[]>([]);
const [edges, setEdges] = useState<Edge[]>([]);

// API integration with error handling
const handleNodeUpdate = useCallback(
	async (nodeId: string, data: any) => {
		try {
			const response = await api.story.updateNode(nodeId, data);
			setNodes((nodes) =>
				nodes.map((node) =>
					node.id === nodeId
						? { ...node, data: { ...node.data, ...response } }
						: node
				)
			);
		} catch (error) {
			// Error handling and user feedback
		}
	},
	[setNodes]
);

React Flow Integration:

• Custom Node Types: Specialized components for story-specific node behaviors
• Edge Customization: Custom connection styles and interaction behaviors
• Layout Algorithms: Automatic node positioning with manual override capability
• Event Handling: Comprehensive graph interaction management

Backend Integration:

• API Client: Structured API calls with authentication and error handling
• Data Validation: Frontend validation matching backend DTO requirements
• State Synchronization: Immediate local updates with backend confirmation
• Conflict Resolution: Handling simultaneous edits and version conflicts

Future Enhancement Capabilities:

Collaboration Features:

• Real-time Multi-user Editing: WebSocket integration for simultaneous editing
• Change Tracking: Visual indicators for modifications by different users
• Conflict Resolution: Automatic and manual conflict resolution workflows
• Version History: Complete audit trail of graph modifications

Advanced Visualization:

• Story Analytics: Visual representation of player paths and engagement
• Performance Metrics: Node popularity and completion statistics
• Graph Export: Save story structures as images or structured data
• Template System: Reusable story structure templates for rapid development

Framework and Implementation Choices

Frontend

• Framework: Astro 4.x with React Islands
• State Management: Nanostores (Astro recommended)
• UI Components: React + Tailwind CSS
• Form Handling: React Hook Form + Zod
• API Client: Built-in Astro fetch with TypeScript
• Testing: Vitest + React Testing Library
• Build Tool: Vite (built into Astro)
• Styling: Tailwind CSS + PostCSS

Backend

• Core Services:
  • Game Engine: NestJS + TypeScript
  • Story Management: NestJS + TypeScript
• Database: MongoDB Atlas
• API Documentation: Swagger/OpenAPI
• Testing: Jest + Supertest
• Validation: class-validator + class-transformer

Storage

• Primary Database: MongoDB Atlas
• File Storage: Local JSON (development)
• Image Storage: Cloudflare R2
• Repository Pattern: Dual storage support (MongoDB + File-based)

Infrastructure

• CDN: Cloudflare
• Hosting: Cloudflare Pages
• CI/CD: GitHub Actions
• Monitoring: Cloudflare Analytics
• Error Tracking: Sentry
• Image Generation: OpenAI DALL-E 3
• Story Generation: OpenAI GPT-3.5-turbo

Social Features Implementation

Phase 1: Basic Social

• User-generated content
• Created Stories/Nodes
• Story Node View counts
• Content sharing
• Share Story/Node button

Phase 2: Advanced Social

• Social media integration
• Achievements / Cosmetics
• Follower system
• Profile customization
• Activity feed

Phase 3: Community Features

• Livestream integration
• Messaging other players
• Chat/Forum system
• Marketplace
• Events system
• Achievement sharing

Scaling Strategy

Application Scaling

• Edge Computing (Cloudflare Pages)

  • Global distribution
  • Automatic scaling
  • DDoS protection
  • Zero-downtime deployments

• API Scaling (NestJS)

  • Stateless architecture
  • Load balancing
  • Rate limiting
  • Request caching

Database Scaling (MongoDB Atlas)

• Horizontal Scaling

  • Automatic sharding
  • Replica sets
  • Read replicas
  • Multi-region deployment

• Performance Optimization

  • Indexed queries
  • Document denormalization
  • Aggregation pipelines
  • Caching strategies

Content Delivery

• Static Assets

  • Cloudflare CDN caching
  • Automatic asset optimization
  • Image compression
  • Edge caching

• Dynamic Content

  • Server-side rendering (Astro)
  • Partial hydration
  • Incremental static regeneration
  • API response caching

Image Management and Storage

Multi-Layer Image System

• Layer Support: Background, middle, and foreground layers for parallax effects
• Hierarchical Storage: UUID-based storage system using story IFID and node UUID
• Image Generation: DALL-E 3 integration with model selection support
• Format Support: PNG, JPEG, WebP with multiple size variants

Image Regeneration (Simplified)

• Unique UUID Strategy: Each regenerated image gets a new UUID v7 identifier
• No Backup Required: Old images remain in nodeImages structure automatically
• Main Image Update: New image URL becomes the primary imageUrl for the node
• Preserved History: Previous images remain accessible through nodeImages metadata
• DRY Implementation: Single regeneration method serves all use cases

Image Storage Structure

NodeImages: {
  [layerId: string]: {
    [imageId: string]: {
      imageId: string;
      variants: ImageVariant[];
      createdAt: Date;
      updatedAt: Date;
    }
  }
}

Modular Mechanics System (v0.7.1.0)

The Modular Mechanics System provides a flexible framework for extending story functionality through YAML-defined modules. The system supports custom field injection, dynamic UI generation, and persistent data storage for story and storynode entities.

Architecture Overview

Core Components:

• ModulesService: Module lifecycle management, activation/deactivation, YAML loading
• YamlModuleParserService: Parse YAML module definitions with deterministic UUID generation
• EntityFieldInjectionService: Dynamic field injection for story and storynode entities
• EntityVariableService: Variable storage and retrieval with proper scoping
• ModulesController: RESTful API for module management and custom field operations

Key Features

Module Definition System:

• YAML-based Configuration: Module definitions stored in /modules/ directory
• Deterministic UUIDs: Consistent module identification based on module_id
• Variable Definitions: Support for multiple data types (string, number, boolean, object, array)
• Scope Management: Variables can be scoped to story, storynode, nodesettings, or imagelayersettings
• Default Values: Automatic default value creation and management

Soft Delete System:

• Preserved UUIDs: Module UUIDs remain consistent across activation cycles
• Enabled Field: Uses enabled: false instead of hard deletes
• Reactivation Support: Previously deactivated modules can be reactivated seamlessly
• Data Integrity: No orphaned records or UUID conflicts

Custom Field Injection:

• Dynamic Field Generation: Fields appear in UI based on active modules
• Type-Safe Editing: Form components adapt to field data types
• Change Detection: Proper state management for field editing
• Auto-Save: Automatic saving of field changes with validation

Database Schema

Story Modules Collection:

{
  story_uuid: String,        // Story identifier
  module_uuid: String,       // Module identifier (deterministic)
  enabled: Boolean,          // Activation status (default: true)
  config: Object,            // Module-specific configuration
  timestamps: true           // Created/updated timestamps
}

Entity Variables Collection:

{
  entity_type: String,       // 'story', 'storynode', 'nodesettings', 'imagelayersettings'
  entity_uuid: String,       // Entity identifier
  module_id: String,         // Module identifier
  variables: Object          // Key-value pairs of variable names and values
}

API Endpoints

Module Management:

• GET /api/v1/modules - List all available modules
• GET /api/v1/modules/story/:storyUuid/active - Get active modules for story
• POST /api/v1/modules/story/:storyUuid/activate - Activate module for story
• DELETE /api/v1/modules/story/:storyUuid/module/:moduleUuid - Deactivate module

Custom Fields:

• GET /api/v1/modules/story/:storyUuid/field-definitions - Get available field definitions
• GET /api/v1/modules/story/:storyUuid/custom-fields - Get story custom field values
• GET /api/v1/modules/storynode/:nodeUuid/custom-fields - Get node custom field values
• PUT /api/v1/modules/story/:storyUuid/custom-fields - Save story custom fields
• PUT /api/v1/modules/storynode/:nodeUuid/custom-fields - Save node custom fields

Frontend Integration

React Components:

• CustomFieldEditor: Dynamic form generation based on field types
• CustomFieldsContainer: Container component with module grouping
• ModuleSelector: UI for activating/deactivating modules per story

Key Features:

• Dynamic Form Generation: Form fields adapt to variable types
• Module Grouping: Fields grouped by module with collapsible sections
• Change Detection: Proper state management for original vs current values
• Auto-Save: Automatic saving with validation and error handling
• Type Support: String, number, boolean, object, array field types

Security Model

Access Control:

• Read Access: Modules can read story and related data
• Write Access: Modules can only write to their own variables
• Validation: All field updates validated against module definitions
• Scoping: Variables properly scoped by entity type and UUID

Data Isolation:

• Module Isolation: Each module’s variables isolated from others
• Entity Scoping: Variables scoped to specific entities (story, node, etc.)
• UUID Validation: All entity references validated before operations

Proof of Concept: Round Counter Module

Module Definition (modules/round-counter.yml):

module_id: round-counter
name: Round Counter
version: 1.0.0
description: Tracks the current game round, increments on each new node
enabled_by_default: false
variables:
    - name: current_round
      description: Current round number
      scope: storynode
      type: number
      include_in_prompts: true
      default_value: 1
      expression: "{current_round}+1"

Implementation Results:

• ✅ Module activation/deactivation works without UUID changes
• ✅ Custom fields appear in story and storynode edit pages
• ✅ Field editing works for all supported data types
• ✅ Change detection and save functionality works correctly
• ✅ Default values created automatically
• ✅ Data persistence across sessions

Technical Achievements

Performance Optimizations:

• Deterministic UUIDs: Eliminates UUID conflicts and lookup issues
• Soft Deletes: Preserves data integrity and module relationships
• Efficient Queries: Optimized database queries for field retrieval
• Caching: Intelligent caching of module definitions and field metadata

Reliability Features:

• Error Handling: Robust error handling throughout the system
• Validation: Comprehensive validation of module definitions and field updates
• Data Integrity: No data corruption or orphaned records
• Backward Compatibility: System maintains compatibility with existing data

Development Quality:

• Test Coverage: Comprehensive test coverage for all components
• Documentation: Complete API documentation and usage examples
• Code Quality: Clean, maintainable code with proper separation of concerns
• Extensibility: System designed for easy addition of new modules and features

Future Enhancements (Phase 3)

Expression Engine:

• Formula Support: Mathematical and string operations on variables
• Spreadsheet-like Functions: Advanced calculation capabilities
• Dynamic Updates: Real-time variable updates based on expressions

Advanced Features:

• Module Configuration: Schema validation and configuration UI
• Validation Rules: Custom validation rules for field constraints
• Complex Types: Support for more complex data structures
• Prompt Integration: Variable inclusion in AI prompt instructions

Extended Scoping:

• NodeSettings Integration: Custom fields for node settings entities
• ImageLayerSettings Integration: Custom fields for image layer configuration
• Cross-Entity References: Variables that reference other entities