Immune 2.0 Documentation

Welcome to the technical documentation for Immune 2.0.

Overview

Immune 2.0 is a self-hosted AI platform designed to empower users to build websites, automate content, and deploy intelligent workflows without writing code.

• Backend Architecture: Details on the Laravel Core and Domain-Driven Design.
• Python Worker Layer: Information on the distributed AI worker system (Video, Audio, Scraping).
• Frontend & Scene: Guide to the Blade/HTMX frontend and the 3D Scene engine.
• Database Schema: Overview of the database tables and relations.
• API Reference:
  • Endpoint Details
  • WebSocket Channels

Infrastructure

• Deployment Guide: setup for Laravel, Python, and Workers.
• Requirements
• Shopify Extension: Documentation for the Shopify App Extension.
• Browser Extension (Extenrico): Guide for the Immune Chrome extension.
• Shopify Integration Architecture: Details on syncing data and Webhooks.
• Limitations & Security: Known issues and security posture.

Getting Started

Refer to the README.md in the project root for installation and setup instructions.

Auto-generated API Route Manifest

Generated: 2026-03-27 22:39:31

API Reference

The application exposes a mix of RESTful API endpoints (for data), blade routes (for UI), and WebSocket channels (for real-time updates).

REST API (routes/api.php)

Use php artisan docs:compile --routes to generate an auto-maintained manifest in docs/api-routes-auto.md.

These are the main API endpoints in routes/api.php (prefixed with /api from Laravel's API router):

• GET /api/user (auth:sanctum)
• Scene/evolution endpoints under /api/scene (agents, messages, tick, stats, relationships, etc.)
• Canvas & agent queue endpoints (/api/canvas/generate, /api/canvas/status/{id}, /api/agent/tasks, /api/agent/result, /api/agent/queue/*)
• Shopify API telemetry endpoints /api/shopify/record and /api/shopify/config
• Workflow task endpoints under /api/agent/workflow/* and /api/chat/workflows
• Request update endpoints /api/requests/internal, /api/requests/{id}/response, /api/requests/{id}/progress
• Internal worker endpoint /api/internal/artisan
• Telegram webhook /api/telegram/webhook
• Database action endpoint /api/db/{table}/{operation}
• Extension APIs /api/extension/* (auth, config, save, chat, sync-chat, saved)
• Audio upload endpoints /api/upload-audio-chunk, /api/finalize-audio-chunks
• Article endpoints /api/articles/{id}, /api/articles/{id}/video-path

Note: the sign-in/sign-up flows are implemented in web routes (routes/web.php) and are documented below in this page for full context.

Authentication

The application uses Session definitions (Cookie-based) authentication. There are no stateless JWT/API tokens for the main user session.

Cookies Required:

• XSRF-TOKEN: CSRF protection token (Standard Laravel).
• immune_session: Main session identifier.

Login

POST /sign-in

• Content-Type: application/x-www-form-urlencoded or application/json
• Parameters:
  • email: (string) User email.
  • password: (string) User password.
• Response:
  • Success: 302 Redirect to / (or HTMX partial update).
  • Failure: 422 Unprocessable Entity (Validation errors) or 429 (Rate Limit).

Register

POST /sign-up

• Parameters:
  • username: (string) Unique username.
  • email: (string) Valid email.
  • password: (string) Min 8 chars.
• Response:
  • Success: 302 Redirect (triggers Email Verification event).

Endpoint Details

Generate Article Video

POST /articles/{id}/video/generate

Triggers the AI Video Generation Workflow for a specific article.

Request:

• URL Param: id (integer) - Article ID.
• Query Param: ?force=true (optional) - Force regeneration if video exists.
• Headers:
  • HX-Request: true (Optional, returns HTML progress bar instead of JSON)

Response (JSON):

{
  "status": "processing",
  "progress": 0,
  "stage": "Initializing..."
}

Process:

1. Creates an App\Domains\Intelligence\Models\AiRequest.
2. Dispatches Article Video Generator workflow to Python slaves.
3. Polls status via GET /articles/{id}/video/status/{requestId}.

Sessions & Recording

• POST /api/shopify/record: Ingests rrweb events from Shopify or other sources.
• GET /admin/visits/video/{sessionId}: Generates/retrieves the session video.
• GET /admin/visits/replay/{sessionId}: Session replay player interface.

Video Editor

• GET /video-editor/project/{sessionId}: Load project.
• POST /video-editor/project/{sessionId}: Save project.
• POST /video-editor/render/{sessionId}: Trigger video rendering.
• POST /video-editor/tts/generate: Trigger Text-To-Speech generation.
• POST /video-editor/clip/regenerate: AI regeneration of a specific clip.

Browser Extension (/api/extension/*)

• GET /api/extension/config: Get extension configuration.
• GET /api/extension/auth: Authenticate extension user (returns user data + CSRF token).
• POST /api/extension/save: Save content from the current page (URL, title, text, HTML).
• POST /api/extension/chat: Send a chat message with page context for AI analysis.
• POST /api/extension/sync-chat: Sync chat history for extension.
• GET /api/extension/saved: List all saved content for authenticated user.
• DELETE /api/extension/saved/{id}: Delete a specific saved content item.

Sites & Builder

• GET /site/{id}/api/{modelSlug}: Headless CMS API for site data.
• POST /sites/{id}/duplicate: Clone a site.

Intelligence / Workflows

• GET /api/chat/workflows: List available chat workflows.
• GET /api/chat/workflow/{id}: Get workflow details.
• POST /api/agent/workflow/run/create: Start a workflow run.
• POST /api/agent/workflow/run/{run}/event: Post workflow events (status updates).
• POST /api/requests/internal: Agent queue/internal workflow request entrypoint.
• POST /api/requests/{id}/response: Set internal request response (worker callback).
• POST /api/requests/{id}/progress: Set internal request progress.

Scene / Agent Simulation

• GET /api/scene/agents: List scene agents.
• GET /api/scene/messages: Get recent scene messages.
• GET /api/scene/agents/{id}: Agent details.
• PATCH /api/scene/agents/{id}: Update agent state.
• POST /api/scene/agents/{id}/interact: Record interaction with an agent.
• GET /api/scene/agents/{id}/memory: Get agent memory context.
• POST /api/scene/agents/{id}/learn: Teach agent a fact.
• GET /api/scene/agents/{id}/timeline: Agent event timeline.
• POST /api/scene/evolution/tick: Advance simulation tick.
• GET /api/scene/experiment/stats: Get evolution experiment stats.
• GET /api/scene/relationships: List agent relationships.
• POST /api/scene/news: Inject news/event into simulation.
• GET /api/scene/evolution/report: Evolution report.
• POST /api/agent/{id}/update: Update agent from async worker.

Chat & Conversation

• GET /chat: Chat interface.
• POST /chat: Create a new chat conversation.
• GET /requests/{conversationId}/feed: Conversation message feed.
• GET /request/{id}: Get single chat request message.
• POST /requests/empty: Clear conversation messages.

WebSocket Channels (Reverb)

The application uses Laravel Reverb for real-time broadcasting.

Channels

• user.{id}: Private channel for user-specific notifications (job completion, alerts).
• workflow.{id}: Updates on workflow node execution status.
• chat.{conversationId}: Real-time AI chat stream.

Key Route Groups

• admin.*: Protected routes for the dashboard.
• public.site.*: Public-facing routes for user-generated sites.
• video-editor.*: Routes for the video creation tool.

Laravel Core Documentation

Architecture Overview

The backend is built on Laravel 10, utilizing a Domain-Driven Design (DDD) approach to organize code logically by business context rather than just technical layers.

Directory Structure

app/
├── Domains/           # Business logic grouped by domain
├── Http/              # Request handling (Controllers, Middleware)
├── Services/          # Cross-cutting application services
├── Models/            # (Mostly moved to Domains, but some may exist here)
├── Jobs/              # Queueable jobs
└── Console/           # Artisan commands

Domains

The application is split into the following primary domains:

1. Publishing

Handles content creation and management.

• Articles, Translations, SEO metadata.
• Media handling.

2. Intelligence

The "Brain" of the system.

• Workflows and Agents.
• Node execution logic.
• Chat interfaces.

3. Commerce

E-commerce functionality.

• Products, Orders, Payments (Stripe).
• Cart management.

4. Platform

Core site building features.

• Sites, Pages, Components.
• Themes and templates.

5. Identity

User management and authentication.

• Users, Roles, Permissions.
• Session handling.

6. Arcade

Gamification and interactive elements.

• Games, Flashcards.

7. Dev

Developer tools and system utilities.

• Code Reviews, Error Logging.

Key Services

Services in app/Services handle logic that crosses multiple domains or interacts with external systems.

Key Services

Services in app/Services handle logic that crosses multiple domains or interacts with external systems.

Services Deep Dive

1. AIService (App\Services\AIService)

Central interface for LLM operations. Supports fallback strategies (Gemini -> Ollama).

Key Methods:

• enhanceArticle(string $title, string $content): array - Improves clarity and SEO.
• generateArticle(string $topic, string $intent): array - Creates full HTML articles from scratch.
• auditArticle(string $title, string $content, ?string $keyword): array - Performs SEO audit (E-E-A-T score, missing topics).
• generateContentStrategy(string $topic): array - Generates a cluster plan with kommercial/transactional intent.
• translateContent(string $content, string $targetLang): array - Translates HTML while preserving structure and IDs.

2. BuilderService (App\Services\BuilderService)

Manages the structure of WebsitePage content JSON. Implements a block-based editor logic.

Block Operations:

• addBlock(WebsitePage $page, array $data): Adds a new block (Text, Image, Container).
• updateBlock(WebsitePage $page, string $blockId, array $data): Updates settings or HTML content.
• moveBlock(WebsitePage $page, string $blockId, ?string $newParentId, int $newIndex): Handles drag-and-drop reordering.
• ensureBlockIds(WebsitePage $page): Self-healing method to assign UUIDs to legacy blocks.

3. EvolutionService (App\Services\EvolutionService)

Runs the simulation for autonomous agents in the 3D Scene.

Core Loop:

• tick(): Main simulation step. Updates stats (Hunger, Energy) for all agents.
• evolve(SceneAgent $agent): Calculates stat changes based on DNA and current state.
• triggerAgentConversation($initiator, $responder): Dispatches a workflow to start an AI dialogue.
• mutateDNA($agent, $trait, $amount): Adjusts genetic parameters based on experiences (e.g., positive interactions increase sociability).

Comprehensive File Inventory

Controllers (app/Http/Controllers)

Admin

• app/Http/Controllers/AdminController.php
• app/Http/Controllers/DashboardController.php
• app/Http/Controllers/SeoManagerController.php
• app/Http/Controllers/DatabaseController.php
• app/Http/Controllers/CommandHistoryController.php
• app/Http/Controllers/ImageUploadController.php
• app/Http/Controllers/MediaController.php
• app/Http/Controllers/SiteSettingController.php

API

• app/Http/Controllers/Api/Auth/AuthController.php
• app/Http/Controllers/Api/CanvasAIController.php
• app/Http/Controllers/Api/CanvasTemplateController.php
• app/Http/Controllers/Api/CustomModelAPIController.php
• app/Http/Controllers/Api/DatabaseActionController.php
• app/Http/Controllers/Api/FlashcardController.php
• app/Http/Controllers/Api/GameController.php
• app/Http/Controllers/Api/InternalAgentController.php
• app/Http/Controllers/Api/MultiplayerController.php
• app/Http/Controllers/Api/SceneController.php
• app/Http/Controllers/Api/SessionRecordingController.php
• app/Http/Controllers/Api/TelegramWebhookController.php

Auth & HTMX

• app/Http/Controllers/Htmx/HTMXArticleController.php
• app/Http/Controllers/Htmx/HTMXEditorController.php
• app/Http/Controllers/Htmx/HTMXHomeController.php
• app/Http/Controllers/Htmx/HTMXSettingsController.php
• app/Http/Controllers/Htmx/HTMXSignInController.php
• app/Http/Controllers/Htmx/HTMXSignUpController.php
• app/Http/Controllers/Htmx/HTMXUserController.php
• app/Http/Controllers/SignInController.php
• app/Http/Controllers/SignUpController.php

Features

• app/Http/Controllers/ArticleController.php

• app/Http/Controllers/ArticleAudioController.php

• app/Http/Controllers/ArticleGenerationController.php

• app/Http/Controllers/ArticleVideoController.php

• app/Http/Controllers/AudioController.php

• app/Http/Controllers/Builder/BlockController.php

• app/Http/Controllers/Builder/PageController.php

• app/Http/Controllers/CartController.php

• app/Http/Controllers/ChatController.php

• app/Http/Controllers/ChatMessageController.php

• app/Http/Controllers/ChatWorkflowController.php

• app/Http/Controllers/CheckController.php

• app/Http/Controllers/CheckoutController.php

• app/Http/Controllers/ConversationController.php

• app/Http/Controllers/DropshippingController.php

• app/Http/Controllers/DynamicRecordController.php

• app/Http/Controllers/EditorController.php

• app/Http/Controllers/FlashcardController.php

• app/Http/Controllers/GameController.php

• app/Http/Controllers/HomeController.php

• app/Http/Controllers/NavigationController.php

• app/Http/Controllers/OrderController.php

• app/Http/Controllers/OrdersController.php

• app/Http/Controllers/PaymentController.php

• app/Http/Controllers/PaymentSettingsController.php

• app/Http/Controllers/ProjectFeaturesController.php

• app/Http/Controllers/PublicWebsiteController.php

• app/Http/Controllers/SceneController.php

• app/Http/Controllers/ScriptController.php

• app/Http/Controllers/SeoController.php

• app/Http/Controllers/SequenceController.php

• app/Http/Controllers/SettingsController.php

• app/Http/Controllers/SitesController.php

• app/Http/Controllers/SnapshotController.php

• app/Http/Controllers/StandaloneWorkflowController.php

• app/Http/Controllers/UserController.php

• app/Http/Controllers/VideoEditorController.php

• app/Http/Controllers/VisitController.php

• app/Http/Controllers/WebsiteBuilderController.php

• app/Http/Controllers/WebsiteVersionController.php

• app/Http/Controllers/WorkflowController.php

Services (app/Services)

• app/Services/AIService.php
• app/Services/BlockParser.php
• app/Services/BuilderService.php
• app/Services/Canvas/CanvasBuilder.php
• app/Services/Checks/BrowserCheckHandler.php
• app/Services/Checks/ContentCheckHandler.php
• app/Services/Checks/Contracts/CheckHandler.php
• app/Services/Checks/DatabaseCheckHandler.php
• app/Services/Checks/HttpCheckHandler.php
• app/Services/Dropshipping/AliExpressService.php
• app/Services/EvolutionService.php
• app/Services/FormBuilderService.php
• app/Services/LaravelExportService.php
• app/Services/PerformanceCollector.php
• app/Services/SiteGeneratorService.php
• app/Services/StaticExportService.php
• app/Services/StripeService.php

Domain Models (app/Domains)

• app/Domains/Arcade/Models/Level.php
• app/Domains/Arcade/Models/LevelWord.php
• app/Domains/Arcade/Models/Room.php

Documentation Sprint Plan (Start Here)

This section is the starting point for incremental docs maintenance. Add entries here as you complete each stage.

1) Immediate (start now)

• Audit existing docs structure (done)
• Add summary of core domains and key models (this file)
• Add update section listing un-documented routes and APIs
• Add “How to contribute docs” with format and style rules

2) Next session (finish later)

• Expand api.md with full endpoint list and usage examples
• Expand database.md with table structure and relationships
• Expand frontend.md with HTMX frame, SPA behavior, and script loading (guest/app bundle details)
• Add workflows.md covering: workflow node types, execution flow, logging, error handling

3) Long-term

• Add diagrams: domain map, request flow, deployment architecture
• Add testing guidelines for Feature/API/HTMX tests
• Add “migration story”: how code changed from v1 to v2 (important for maintainers)

4) Quick win helpers

• docs/backend/laravel.md for architecture reference

• docs/api.md for API reference

• docs/database.md for model schema

• docs/frontend.md for UI/asset flow

• docs/infrastructure.md for setup + environment

• app/Domains/Arcade/Models/RoomPlayer.php

• app/Domains/Arcade/Models/UserProgress.php

• app/Domains/Arcade/Models/Word.php

• app/Domains/Commerce/Models/Attribute.php

• app/Domains/Commerce/Models/AttributeValue.php

• app/Domains/Commerce/Models/Order.php

• app/Domains/Commerce/Models/Payment.php

• app/Domains/Commerce/Models/Product.php

• app/Domains/Identity/Models/SSOProvider.php

• app/Domains/Identity/Models/SessionRecording.php

• app/Domains/Identity/Models/User.php

• app/Domains/Intelligence/Models/AiRequest.php

• app/Domains/Intelligence/Models/CanvasTemplate.php

• app/Domains/Intelligence/Models/ChatMessage.php

• app/Domains/Intelligence/Models/Conversation.php

• app/Domains/Intelligence/Models/SceneAgent.php

• app/Domains/Intelligence/Models/SceneObject.php

• app/Domains/Intelligence/Models/SceneTrigger.php

• app/Domains/Intelligence/Models/Schema.php

• app/Domains/Intelligence/Models/Script.php

• app/Domains/Intelligence/Models/Sequence.php

• app/Domains/Intelligence/Models/Workflow.php

• app/Domains/Intelligence/Models/WorkflowNode.php

• app/Domains/Intelligence/Models/WorkflowRun.php

• app/Domains/Intelligence/Models/WorkflowRunLog.php

• app/Domains/Platform/Models/Check.php

• app/Domains/Platform/Models/CheckResult.php

• app/Domains/Platform/Models/CommandHistory.php

• app/Domains/Platform/Models/CustomEntry.php

• app/Domains/Platform/Models/CustomModel.php

• app/Domains/Platform/Models/DataField.php

• app/Domains/Platform/Models/DataModel.php

• app/Domains/Platform/Models/DataRecord.php

• app/Domains/Platform/Models/ExperimentStats.php

• app/Domains/Platform/Models/Form.php

• app/Domains/Platform/Models/FormSubmission.php

• app/Domains/Platform/Models/PerformanceMetric.php

• app/Domains/Platform/Models/SessionRecording.php

• app/Domains/Platform/Models/SessionRecordingChunk.php

• app/Domains/Platform/Models/Visit.php

• app/Domains/Publishing/Models/Article.php

• app/Domains/Publishing/Models/ArticleTranslation.php

• app/Domains/Publishing/Models/AudioFile.php

• app/Domains/Publishing/Models/Comment.php

• app/Domains/Publishing/Models/Keyword.php

• app/Domains/Publishing/Models/Language.php

• app/Domains/Publishing/Models/NavigationItem.php

• app/Domains/Publishing/Models/Notebook.php

• app/Domains/Publishing/Models/Section.php

• app/Domains/Publishing/Models/SiteSetting.php

• app/Domains/Publishing/Models/SiteSettingVersion.php

• app/Domains/Publishing/Models/SiteText.php

• app/Domains/Publishing/Models/Tag.php

• app/Domains/Publishing/Models/Theme.php

• app/Domains/Publishing/Models/VideoProject.php

• app/Domains/Publishing/Models/Website.php

• app/Domains/Publishing/Models/WebsitePage.php

• app/Domains/Dev/Models/CodeReview.php

• app/Domains/Platform/Models/ShakeLog.php

• app/Domains/Platform/Models/WebsiteVersion.php

Commands (app/Console/Commands)

• app/Console/Commands/EnhanceArticlesCommand.php
• app/Console/Commands/GenerateArticleFromOllama.php
• app/Console/Commands/GenerateNewsArticlesCommand.php
• app/Console/Commands/GitPullUpdate.php
• app/Console/Commands/ImportTranslations.php
• app/Console/Commands/PruneSessionRecordings.php
• app/Console/Commands/RunChecks.php
• app/Console/Commands/RunScheduledWorkflows.php
• app/Console/Commands/SEOAuditCommand.php
• app/Console/Commands/SEOStrategizeCommand.php

Configuration (config/)

• config/app.php: Core application settings.
• config/auth.php: Authentication guards and providers.
• config/broadcasting.php: WebSocket/Pusher settings.
• config/cache.php: Cache store configuration.
• config/checks.php: Custom health check settings.
• config/cors.php: Cross-Origin Resource Sharing.
• config/csp.php: Content Security Policy.
• config/database.php: Database connections (MySQL/Redis).
• config/filesystems.php: Disk storage (Local, S3).
• config/gemini.php: Gemini AI API settings.
• config/hashing.php: Password hashing usage.
• config/location.php: Geolocation settings.
• config/logging.php: Log channels (Stack, Daily).
• config/mail.php: Mailer settings (SMTP).
• config/queue.php: Queue connections (Redis/Sync).
• config/reverb.php: Laravel Reverb (WebSocket) settings.
• config/sanctum.php: API token authentication.
• config/services.php: Third-party services (Stripe, Socialite).
• config/session.php: Session driver settings.
• config/view.php: Blade view paths.

Routes (routes/)

• routes/web.php: Standard browser routes.
• routes/api.php: API endpoints (prefixed with /api).
• routes/admin.php: Admin routes (prefixed with /admin).
• routes/channels.php: WebSocket broadcast channels.
• routes/console.php: Artisan console commands.
• routes/chat.php: Chat system routes.
• routes/check.php: Health check routes.
• routes/editor.php: Editor specific routes.
• routes/htmx.php: HTMX-only endpoints.
• routes/lang.php: Translation routes.
• routes/site_settings.php: Settings management routes.
• routes/sitemap.php: Sitemap generation.
• routes/user.php: User dashboard routes.
• routes/websites.php: Public website routes.

Auto-generated API route manifest

To keep API docs in sync automatically:

1. Run: php artisan docs:compile --check --routes
2. Inspect: docs/api-routes-auto.md (generated from routes/api.php).
3. Merge this into docs/api.md as needed (automation minimizes manual update drift).

Database & Migrations

• database/migrations/: Contains 80+ migration files defining the schema history.
• database/factories/: Model factories for testing.

Database Seeders (database/seeders/)

• DatabaseSeeder.php: Main entry point.

• ArticleVideoWorkflowSeeder.php

• AudioWorkflowSeeder.php

• ChatWorkflowSeeder.php

• DefaultChatWorkflowSeeder.php

• EcommerceSeeder.php

• EvolutionWorkflowSeeder.php

• GameWorldSeeder.php

• HomeArticleSeeder.php

• HomePageSeeder.php

• MechanicSeeder.php

• NewsInjectorWorkflowSeeder.php

• NewsSourcesSeeder.php

• SceneAgentSeeder.php

• SeoSeeder.php

• StarterSeeder.php

• TelegramTTSWorkflowSeeder.php

• ThemeSeeder.php

• TourSceneWorkflowSeeder.php

• TranslationSeeder.php

• WebsiteChatWorkflowSeeder.php

• WebsiteSeeder.php

• WordGeneratorWorkflowSeeder.php

• WordSeeder.php

Tests (tests/)

Feature Tests

• tests/Feature/AdminBulkActionsTest.php
• tests/Feature/AdminTest.php
• tests/Feature/ArticleTest.php
• tests/Feature/ChatMessageTest.php
• tests/Feature/ConversationTest.php
• tests/Feature/CustomModelValidationTest.php
• tests/Feature/ExampleTest.php
• tests/Feature/ExportVideoTest.php
• tests/Feature/FeatureToggleTest.php
• tests/Feature/FlashcardDownloadTest.php
• tests/Feature/HTMX/EditorTest.php
• tests/Feature/HTMX/HomeTest.php
• tests/Feature/HTMX/SocialAuthTest.php
• tests/Feature/MultiWordTagTest.php
• tests/Feature/NotebookTest.php
• tests/Feature/SessionRecordingTest.php
• tests/Feature/SiteSettingTest.php
• tests/Feature/TTSGameTest.php
• tests/Feature/TagFeedTest.php
• tests/Feature/TranslationTest.php
• tests/Feature/WebsiteBuilderTest.php
• tests/Feature/WritingGameTest.php

Unit Tests

• tests/Unit/Enums/BlockCategoryTest.php
• tests/Unit/Enums/BlockTypeTest.php
• tests/Unit/ExampleTest.php
• tests/Unit/Services/BuilderServiceTest.php

Core

• tests/TestCase.php
• tests/CreatesApplication.php

Python Backend Documentation

Architecture Overview

The Python backend operates as a Distributed Worker System, handling computationally intensive and AI-driven tasks that are decoupled from the main Laravel application. It communicates via WebSockets.

Core Components

• Master (main.py): The central WebSocket server that acts as a task router. It receives tasks from Laravel and dispatches them to available workers.
• Worker (run.py / slv/main.py): The slave process that executes the actual tasks. It connects to the Master and listens for incoming jobs.

Directory Structure

python_backend/
├── main.py                 # WebSocket Master Server
├── run.py                  # Worker Entry Point
├── slv/                    # Slave Worker Package
│   ├── services/           # Service Implementations
│   │   ├── video/          # Video generation pipeline
│   │   ├── audio.py        # TTS and Voice Cloning
│   │   ├── scraping.py     # Browser automation (Playwright)
│   │   ├── browser_animation.py # Visuals via browser rendering
│   │   └── session_recorder.py  # Session replay logic
│   └── workflow/           # Node execution handlers

AI Services

1. Video Generation (slv/services/video/)

Composes videos from articles or text.

• Segments logic to split text into scenes.
• Integrates with browser_animation.py for visual assets.
• Uses moviepy for final assembly.

WebSocket Protocol

The Python Master (main.py) acts as a WebSocket server handling communication between Clients (frontend/users) and Slaves (Python workers).

Endpoints:

• Clients: ws://<BIND_ADDRESS>:8765
• Slaves: ws://<BIND_ADDRESS>:9001

Event Types (Client -> Master):

Slave Routing:

• The Master maintains a list of slaves_idle and slaves_busy.
• When a request arrives, an idle slave is popped, linked to the client, and the message is forwarded.
• If no slave is available, an error event is returned to the client.

Video Generation Pipeline

The video service (slv/services/video/) transforms text articles into TikTok-style videos.

Key Components:

• Generator (generator.py): Orchestrates the pipeline.
• Analysis (analysis.py): Uses LLM (gemma3) to extract "viral" highlights.
• Visuals: Uses HTML templates rendered via Playwright.

Pipeline Steps:

1. Ingestion: generate_video_from_article_id(article_id) fetches content from Laravel.
2. Analysis: analyze_for_highlights() breaks text into segments (Quote, Stats, Timeline, etc.).
3. Project State: create_highlight_project() builds a JSON state with tracks (Audio, Video, Overlay, Music).
4. Asset Generation:
   • Audio: TTS (Coqui/gTTS) for each segment narration.
   • Visuals: generate_ai_html_only() creates an HTML file from templates (quote.html, etc.) for each segment.
5. Rendering: render_project():
   • Renders HTML clips to MP4 using Playwright.
   • Concatenates Video, Audio, and Music clips using moviepy.
6. Export: Saves the final MP4 to storage/app/public/videos and returns the path.

Diagram Types: Supported visual templates: quote, stats, flowchart, comparison, timeline, infographic, social, definition, quiz, news.

2. Audio Service (slv/services/audio.py)

Handles Text-to-Speech operations.

• Supports multiple engines (e.g., gTTS, Coqui).
• Implements voice cloning capabilities.

3. Scraping Service (slv/services/scraping.py)

Advanced web scraping.

• Uses Playwright for rendering JavaScript.
• Implements anti-detection mechanisms.

4. Browser Animation (slv/services/browser_animation.py)

Generates high-quality visuals by rendering HTML/CSS/GSAP in a headless browser and capturing screenshots/screencasts. This allows for web-native design tools to create video assets.

5. Session Recorder (slv/services/session_recorder.py)

Processes session replay data (rrweb events) to generate video files of user sessions.

Comprehensive File Inventory

Core

• python_backend/main.py
• python_backend/run.py
• python_backend/create_assets.py
• python_backend/reproduce_highlight_video.py
• python_backend/reproduce_render.py
• python_backend/tools_config.py

Package (slv/)

• python_backend/slv/__init__.py
• python_backend/slv/auth.py
• python_backend/slv/config.py
• python_backend/slv/main.py
• python_backend/slv/agents/__init__.py
• python_backend/slv/agents/llm.py
• python_backend/slv/agents/memory.py
• python_backend/slv/core/__init__.py
• python_backend/slv/core/database.py
• python_backend/slv/core/utils.py

Services (slv/services/)

• python_backend/slv/services/__init__.py
• python_backend/slv/services/animation.py
• python_backend/slv/services/audio.py
• python_backend/slv/services/browser_animation.py
• python_backend/slv/services/enhanced_diagrams.py
• python_backend/slv/services/gold_scorer.py
• python_backend/slv/services/motion_graphics.py
• python_backend/slv/services/scraping.py
• python_backend/slv/services/session_recorder.py
• python_backend/slv/services/telegram.py
• python_backend/slv/services/tools.py
• python_backend/slv/services/visual_factory.py
• python_backend/slv/services/animation_engine/__init__.py
• python_backend/slv/services/animation_engine/scene.py

Video Pipeline (slv/services/video/)

• python_backend/slv/services/video/__init__.py
• python_backend/slv/services/video/ai_templates.py
• python_backend/slv/services/video/analysis.py
• python_backend/slv/services/video/compositor.py
• python_backend/slv/services/video/config.py
• python_backend/slv/services/video/diagrams.py
• python_backend/slv/services/video/generator.py
• python_backend/slv/services/video/test_fix.py
• python_backend/slv/services/video/visuals.py
• python_backend/slv/services/video/web_visuals.py

Workflow Engine (slv/workflow/)

• python_backend/slv/workflow/__init__.py
• python_backend/slv/workflow/engine.py
• python_backend/slv/workflow/handlers.py
• python_backend/slv/workflow/nodes.py
• python_backend/slv/workflow/video_clip_handler.py

Test Scripts

• python_backend/test_audio_debug.py
• python_backend/test_full_flow.py
• python_backend/test_template_gen.py
• python_backend/test_video_gen.py
• python_backend/verify_html_flow.py
• python_backend/verify_phase2.py
• python_backend/verify_phase3.py
• python_backend/verify_phase4.py
• python_backend/verify_phase5.py
• python_backend/verify_phase6.py
• python_backend/verify_story.py
• python_backend/verify_telegram.py
• python_backend/verify_upload.py
• python_backend/verify_video_gen.py

Database Schema Documentation

The database is structured to support a modular Domain-Driven architecture. The table list below is synced from migration file names in database/migrations.

Core Domains

Identity Domain

users

• Core: id, email, password, username, role.
• Profile: name, bio, image, avatar.
• Social: provider (google, etc), provider_id.
• Settings: preferences (JSON), chat_workflow_id (FK -> workflows).
• Relationships:
  • articles: HasMany Article
  • followers/followings: BelongsToMany User

Publishing Domain

articles

• Core: id, user_id (FK), section_id (FK), position.
• Flags:
  • is_public (bool): Visibility toggle.
  • type (enum): post, page, product, docs.
  • content_equity_score (int): Calculated value (0-100) combining SEO + Potential.
• Commerce: price, sku, inventory.
• Relationships:
  • translations: HasMany ArticleTranslation (Content stored here).
  • tags: BelongsToMany Tag.
  • favoritedUsers: BelongsToMany User.

article_translations

• Core: id, article_id (FK), lang (en, fr, etc).
• Content: title, slug, content (JSON/HTML), description, seo_score.

sections

• Core: id, name, notebook_id (FK).
• Purpose: Grouping articles (e.g., "Blog", "Tutorials").

Platform & Builder

• websites: Sites created by the builder.
• website_pages: Individual pages within sites.
• website_versions: History/snapshots of site configuration.
• themes: Visual themes for sites.
• site_settings: Global configuration.
• shake_logs: Client-side error reporting and context logs.

Intelligence & Workflows

• workflows: Definitions of workflow graphs.
• workflow_runs: Execution history.
• ai_requests: Log of LLM interactions.
• notebooks, sections: Knowledge organization.
• chat_messages, conversations: AI chat history.
• saved_contents: User-saved page content from the browser extension (URL, title, text, HTML).

Commerce

• products: E-commerce items.
• orders: Transaction records.
• payments: Payment processing logs.
• attributes, attribute_values: Dynamic product properties.

Arcade / Games

• words, levels: Game data for word games.
• user_progress: Tracking player advancement.
• rooms, room_players: Multiplayer game state.

Specialized Modules

• session_recordings: Session replay data (Shopify integration).
• video_projects: Video editor project files.
• custom_models, data_fields, data_records: User-defined database schemas (Headless CMS features).

Dev & Maintenance

• code_reviews: Historical code analyses and AI code reviews.

Full Table Inventory (from migrations)

The table list is generated from database/migrations/*_create_*.php and other schema migrations.

• users + auth support: password_reset_tokens, personal_access_tokens, sessions (via Laravel sessions if used)
• session_recordings, session_recording_chunks
• notebooks, sections
• user_follower
• articles, article_translations, article_tag, article_favorite, comments, tags
• trading/finance: symbols, ohlvcs, signals, orders, trades, payments (renamed)
• visits & analytics: visits, command_histories, performance_metrics, shake_logs
• intelligent agents: schemas, conversations, chat_messages, ai_requests, canvas_templates, workflow_runs, workflows, scene_agents, scene_triggers, scene_objects, experiment_stats
• CMS/site builder: themes, site_settings, site_setting_versions, site_texts, custom_models, data_models, data_fields, data_records, forms, form_submissions, website_versions
• e-commerce: products, attributes, attribute_values
• gamified pages: words, levels, room_players, user_progress (and related arcade models)
• integration / user connectivity: sso_providers, clients
• automation / job workflows: checks, check_results
• extension/context: saved_contents

How to keep this current

1. Run php artisan migrate:status and ls database/migrations.
2. Regenerate docs from route/migration state (under construction) by running:
   • php artisan docs:compile --check --routes
3. Manually verify any new migration names are added in this list or the new auto-generated docs section.

Frontend Documentation

Technology Stack

The Immune 2.0 frontend uses a hybrid approach to deliver a fast, dynamic user experience without the complexity of a full SPA (Single Page Application) framework everywhere.

• Blade Templates: Server-side rendering for the initial page structure.
• HTMX: Handles dynamic interactions by swapping HTML partials from the server. This allows for SPA-like feel (page transitions, soft refreshes) while keeping logic on the backend.
• Vanilla JavaScript: Used for client-side interactivity where HTMX is not sufficient.
• Bootstrap 5: The primary CSS framework for styling.

3D Scene Architecture (resources/js/scene/)

The 3D environment is built on Three.js and manages a persistent world state synchronized via WebSockets.

Core Loop (SceneManager.js)

• Initialization: Sets up the Renderer, Camera, Composer (Bloom/Post-processing), and Lighting (Day/Night cycle).
• Update Loop:
  • Updates PlayerController (physics/movement).
  • Updates EntityManager (agents, NPCs).
  • Updates TerrainChunkManager (infinite terrain generation).
  • Renders the scene + post-processing.
  • Checks for interaction triggers.

Key Components

• InputManager: Maps keyboard/mouse events to actions (e.g., 'F' for flashlight, 'Enter' for chat).
• NetworkManager: Syncs world state (agent positions, chat messages) with the Laravel/Python backend.
• EntityManager: Handles spawning/despawning of gltf assets and simple mesh entities.

Canvas Builder (resources/js/builder/)

A visual node graph editor for designing Agent Workflows.

Architecture (GraphManager.js)

• Hybrid Rendering:
  • Nodes: HTML elements (divs) for accessibility and CSS styling.
  • Connections: SVG paths (Bezier curves) for smooth lines between ports.
• State Management: Tracks nodes, connections, panX, panY, and scale.
• Interaction:
  • Drag & Drop: Uses HTML5 Drag API for adding nodes from the sidebar.
  • Pan & Zoom: Custom implementation handling CSS transforms on the workspace layers.
  • AI Workflow Generation: Integrated chat interface (workflow_generated event) allows users to prompt an AI agent to dynamically generate workflow nodes and connections on the canvas.

Session Recording

The frontend includes a custom recording script (based on rrweb) for capturing user sessions, particularly for the Shopify integration.

• Recorder: Captures DOM mutations and inputs.
• Replayer: Reconstructs the session for viewing.

Video Editor

A specialized frontend interface for the video generation workflow.

• Located in resources/views/video-editor (inferred).
• Uses drag-and-drop interfaces for arranging video segments.

Comprehensive File Inventory

JavaScript (resources/js)

Core & Immune

• resources/js/app.js

• resources/js/bootstrap.js

• resources/js/chat-app.js

• resources/js/fraud-detector.js

• resources/js/guest.js

• resources/js/inline-toolbar.js

• resources/js/scene.js

• resources/js/word-game.js

• resources/js/word-match-game.js

• resources/js/immune/Core.js

• resources/js/immune/config.js

• resources/js/immune/runtime.js

• resources/js/immune/debug/Logger.js

• resources/js/immune/events/Bus.js

• resources/js/immune/network/SocketClient.js

• resources/js/immune/ui/ChatManager.js

• resources/js/immune/utils/ColorUtils.js

Canvas Engine

• resources/js/immune/canvas/Engine.js
• resources/js/immune/canvas/Input.js
• resources/js/immune/canvas/Transformer.js
• resources/js/immune/canvas/history/Stack.js
• resources/js/immune/canvas/math/Matrix3.js
• resources/js/immune/canvas/math/Vector2.js
• resources/js/immune/canvas/nodes/BaseNode.js
• resources/js/immune/canvas/nodes/ImageNode.js
• resources/js/immune/canvas/nodes/LineNode.js
• resources/js/immune/canvas/nodes/ShapeNode.js
• resources/js/immune/canvas/nodes/TextNode.js

Builder

• resources/js/builder/GraphManager.js
• resources/js/builder/NodeRenderer.js
• resources/js/builder/SocketHandler.js
• resources/js/builder/Templates.js
• resources/js/agent-builder.js

3D Engine (scene)

• resources/js/scene/Decorations.js
• resources/js/scene/PlayerBot.js
• resources/js/scene/PlayerController.js
• resources/js/scene/WorldBuilder.js
• resources/js/scene/index.js
• resources/js/scene/animals/Bear.js
• resources/js/scene/animals/Deer.js
• resources/js/scene/animals/Raccoon.js
• resources/js/scene/animals/index.js
• resources/js/scene/buildings/Structures.js
• resources/js/scene/buildings/index.js
• resources/js/scene/core/InputManager.js
• resources/js/scene/core/SceneManager.js
• resources/js/scene/environment/BiomeManager.js
• resources/js/scene/environment/Particles.js
• resources/js/scene/environment/Terrain.js
• resources/js/scene/environment/TerrainChunk.js
• resources/js/scene/environment/TerrainChunkManager.js
• resources/js/scene/environment/Vegetation.js
• resources/js/scene/environment/index.js
• resources/js/scene/lighting/Atmosphere.js
• resources/js/scene/lighting/index.js
• resources/js/scene/managers/EntityManager.js
• resources/js/scene/managers/SimulationManager.js
• resources/js/scene/network/NetworkManager.js
• resources/js/scene/ui/UIManager.js
• resources/js/scene/utils/FurShader.js
• resources/js/scene/utils/SeededRandom.js

Editors

• resources/js/editor/easy-form.js
• resources/js/video-editor/Canvas.js
• resources/js/video-editor/Storyboard.js
• resources/js/video-editor/Timeline.js
• resources/js/video-editor/index.js
• resources/js/visual-editor/blocks/DesignBlock.js
• resources/js/visual-editor/blocks/StyleBlock.js
• resources/js/visual-editor/index.js

Views (resources/views)

Auth

• resources/views/auth/sign-in/index.blade.php
• resources/views/auth/sign-in/partials/form-fields.blade.php
• resources/views/auth/sign-in/partials/index.blade.php
• resources/views/auth/sign-up/index.blade.php
• resources/views/auth/sign-up/partials/form-fields.blade.php
• resources/views/auth/sign-up/partials/index.blade.php
• resources/views/auth/verify-email-notice.blade.php

Admin

• resources/views/administration/activity.blade.php
• resources/views/administration/agents.blade.php
• resources/views/administration/appearance/index.blade.php
• resources/views/administration/articles/edit.blade.php
• resources/views/administration/articles/write.blade.php
• resources/views/administration/create.blade.php
• resources/views/administration/edit.blade.php
• resources/views/administration/features/index.blade.php
• resources/views/administration/index.blade.php
• resources/views/administration/list.blade.php
• resources/views/administration/media/index.blade.php
• resources/views/administration/navigation/index.blade.php
• resources/views/administration/pages/index.blade.php
• resources/views/administration/partials/model-stats.blade.php
• resources/views/administration/partials/sidebar.blade.php
• resources/views/administration/products/index.blade.php
• resources/views/administration/seo-manager/ideas.blade.php
• resources/views/administration/seo-manager/index.blade.php
• resources/views/administration/seo-manager/keywords.blade.php
• resources/views/administration/seo/index.blade.php
• resources/views/administration/snapshots/index.blade.php
• resources/views/administration/stat.blade.php

Builder

• resources/views/builder/canvas.blade.php
• resources/views/builder/database/entries.blade.php
• resources/views/builder/database/entry-form.blade.php
• resources/views/builder/database/index.blade.php
• resources/views/builder/database/schema.blade.php
• resources/views/builder/edit.blade.php
• resources/views/builder/flow.blade.php
• resources/views/builder/partials/block-settings.blade.php
• resources/views/builder/partials/block.blade.php
• resources/views/builder/partials/component-renderer.blade.php
• resources/views/builder/partials/navbar.blade.php
• resources/views/builder/partials/page-list.blade.php
• resources/views/builder/partials/settings-form.blade.php
• resources/views/builder/partials/sidebar-left.blade.php
• resources/views/builder/preview.blade.php
• resources/views/builder/workflows/editor.blade.php
• resources/views/builder/workflows/index.blade.php

Components

• resources/views/components/ad-slot.blade.php
• resources/views/components/article/layout.blade.php
• resources/views/components/article/scripts.blade.php
• resources/views/components/article/styles.blade.php
• resources/views/components/article/tip.blade.php
• resources/views/components/block-renderer.blade.php
• resources/views/components/blocks/accordion.blade.php
• resources/views/components/blocks/audio.blade.php
• resources/views/components/blocks/blockquote.blade.php
• resources/views/components/blocks/blog-list.blade.php
• resources/views/components/blocks/button.blade.php
• resources/views/components/blocks/card.blade.php
• resources/views/components/blocks/cart-view.blade.php
• resources/views/components/blocks/chart.blade.php
• resources/views/components/blocks/chat-bubble.blade.php
• resources/views/components/blocks/code.blade.php
• resources/views/components/blocks/columns.blade.php
• resources/views/components/blocks/container.blade.php
• resources/views/components/blocks/data-list.blade.php
• resources/views/components/blocks/design.blade.php
• resources/views/components/blocks/faq.blade.php
• resources/views/components/blocks/feed.blade.php
• resources/views/components/blocks/footnote.blade.php
• resources/views/components/blocks/gauge.blade.php
• resources/views/components/blocks/grid.blade.php
• resources/views/components/blocks/h1.blade.php
• resources/views/components/blocks/h2.blade.php
• resources/views/components/blocks/h3.blade.php
• resources/views/components/blocks/header.blade.php
• resources/views/components/blocks/heading.blade.php
• resources/views/components/blocks/image.blade.php
• resources/views/components/blocks/list.blade.php
• resources/views/components/blocks/paragraph.blade.php
• resources/views/components/blocks/pricing-table.blade.php
• resources/views/components/blocks/progress-bar.blade.php
• resources/views/components/blocks/section.blade.php
• resources/views/components/blocks/shop-grid.blade.php
• resources/views/components/blocks/style.blade.php
• resources/views/components/blocks/subheading.blade.php
• resources/views/components/blocks/table.blade.php
• resources/views/components/blocks/tabs.blade.php
• resources/views/components/blocks/testimonials.blade.php
• resources/views/components/blocks/text.blade.php
• resources/views/components/blocks/timeline.blade.php
• resources/views/components/blocks/tip.blade.php
• resources/views/components/blocks/video.blade.php
• resources/views/components/blocks/widgets.blade.php
• resources/views/components/builder-navbar.blade.php
• resources/views/components/builder/block.blade.php
• resources/views/components/editor/loader.blade.php
• resources/views/components/editor/script.blade.php
• resources/views/components/flashcard-game.blade.php
• resources/views/components/form-error-message.blade.php
• resources/views/components/form-success-message.blade.php
• resources/views/components/htmx/head.blade.php
• resources/views/components/main-navbar-tailwind.blade.php
• resources/views/components/main-navbar.blade.php
• resources/views/components/navbar-items.blade.php
• resources/views/components/navbar.blade.php
• resources/views/components/redirect.blade.php
• resources/views/components/rrweb.blade.php
• resources/views/components/table.blade.php
• resources/views/components/word-game.blade.php
• resources/views/components/word-match-game.blade.php
• resources/views/components/writing-game.blade.php

Other Views

• resources/views/articles/builder.blade.php

• resources/views/articles/detail.blade.php

• resources/views/articles/partials/... (see directories)

• resources/views/chat/...

• resources/views/checks/...

• resources/views/command_history/index.blade.php

• resources/views/dashboard/index.blade.php

• resources/views/database/...

• resources/views/docs/show.blade.php

• resources/views/editor/...

• resources/views/errors/...

• resources/views/flashcards/index.blade.php

• resources/views/home/index.blade.php

• resources/views/home/partials/...

• resources/views/layouts/...

• resources/views/pages/show.blade.php

• resources/views/payment/...

• resources/views/products/show.blade.php

• resources/views/scene/...

• resources/views/settings/...

• resources/views/shop/index.blade.php

• resources/views/site_settings/...

• resources/views/site_texts/...

• resources/views/sitemap.blade.php

• resources/views/sites/...

• resources/views/users/...

• resources/views/vendor/pagination/...

• resources/views/visits/...

• resources/views/websites/...

• resources/views/workflows/...

Infrastructure & Deployment

System Requirements

• PHP: 8.2+
• Node.js: 16+
• Python: 3.10+
• Database: MySQL 8.0+ or PostgreSQL
• Redis: Required for Queue and Cache

Deployment Architecture

The application runs as three distinct services that must operate simultaneously:

1. Web Service (Laravel)

• Role: Serves HTTP requests, API, and WebSocket Handshake.
• Command: php artisan serve (Dev) or Nginx/PHP-FPM (Prod).
• Key Config: .env (Database, Redis, Mail settings).

2. Python Master & Slaves

• Role: Handles heavy AI tasks, Video Rendering, and WebSocket event routing.
• Location: /python_backend
• Command: python main.py
  • Starts the Master WebSocket server on port 8765.
  • Spawns Slave processes.
• Dependencies: Listed in python_backend/requirements.txt (implied).

3. Queue Workers

• Role: Processes background jobs (Article Audits, Notifications).
• Command: php artisan queue:work --tries=3

Supervisor Configuration (Recommended)

For production, use supervisord to manage processes.

[program:immune-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/immune/artisan queue:work --sleep=3 --tries=3
autostart=true
autorestart=true
numprocs=2

[program:immune-python]
command=python3 /var/www/immune/python_backend/run.py
directory=/var/www/immune/python_backend
autostart=true
autorestart=true
stderr_logfile=/var/log/immune-python.err.log
stdout_logfile=/var/log/immune-python.out.log

Build Process

Frontend

Assets are compiled using Vite.

npm install
npm run build

Generates assets in public/build/.

Composer

composer install --optimize-autoloader --no-dev
php artisan optimize

Root Project Files

Build & Config

• composer.json, composer.lock: PHP usage dependencies.
• package.json, package-lock.json: Node.js dependencies.
• docker-compose.yml (when available): local container setup.

Infrastructure Automation

• app/Console/Commands/DocsCommand.php supports --routes to generate an up-to-date API manifest (docs/api-routes-auto.md).

• php artisan docs:compile --check --routes should be part of CI.

• Use php artisan migrate:status for database state check, and php artisan queue:work + python_backend/main.py for runtime stack.

• vite.config.js: Vite build configuration.

• tailwind.config.js: Tailwind CSS configuration.

• postcss.config.js: PostCSS configuration.

• phpunit.xml: PHPUnit testing configuration.

• supervisord.conf: Supervisor process manager config.

• docker-compose.yml (if present): Docker setup.

Environment

• .env: Environment variables.
• .env.example: Template for environment variables.
• .gitignore: Git exclusion rules.
• .editorconfig: Editor coding style rules.
• .gitattributes: Git attribute settings.

Scripts

• artisan: Laravel CLI entry point.
• translations.json: Translation strings.
• words.json: Default word list.

Required Environment Variables

Beyond standard Laravel .env entries, the following are required:

Limitations & Security

This document outlines the known limitations of the platform, features that are currently experimental or non-functional, and the technical security measures in place.

1. Known Limitations

1.1 Video Generation Speed

• Issue: Generating video exports from session replays is a resource-intensive process.
• Impact: It relies on a distributed Python worker system using Headless Browsers.
• Limitation: Processing times can vary significantly (1-5 minutes per minute of video). Queues may backlog if hardware resources are insufficient.
• Queueing: Jobs are processed FIFO. Priority queuing is not yet implemented.

1.2 3D Scene Performance

• Issue: The immersive 3D Scene (/scene) uses Three.js with high-fidelity PBR materials and dynamic lighting.
• Limitation: Performance drops significantly on mobile devices or computers without dedicated GPUs.
• Workaround: Currently, there is no automatic "Low Quality" mode fallback. 60FPS is only guaranteed on desktop M1/RTX class hardware.

1.3 Session Recorder (rrweb)

• Issue: The recorder captures DOM and mutations, not a video stream.
• Limitation: It cannot capture content inside <canvas> (unless explicitly handled), WebGL contexts, or cross-origin iframes.
• Result: Replays of complex interactive 3D sites or games may look "empty" or incorrect.
• Privacy: The recorder automatically masks password inputs but does not perform PII scrubbing on general text fields by default.

2. What Doesn't Work (Yet)

• API Token Generation: There is no UI for users to generate personal access tokens (PATs). All API interaction must go through session cookies or internal service-to-service calls.
• Real-time Collaboration: While the Video Editor has WebSocket connections, true multi-user simultaneous editing (OT/CRDT) is not yet implemented. Last-write-wins applies.
• Shopify App Store Installation: The extension is ready for the store, but the automated billing and installation flow (/install route) is currently in dev mode and requires manual partner account setup.
• Multi-Region Storage: All session data is currently stored in a single region DB. Sharding strategy is planned but not implemented.

3. Security Posture

3.1 Authentication & Authorization

• Method: Strictly Session-based (Cookies) for browser access.
• Sanctum: Stateful API authentication is enabled via EnsureFrontendRequestsAreStateful middleware in the API group, allowing the browser extension to use cookie-based auth with credentials: 'include'.
• No JWTs: We avoid storing JWTs in LocalStorage to prevent XSS token theft.
• CSRF: All state-changing web requests (POST, PUT, DELETE) are protected by Laravel's VerifyCsrfToken middleware. The $except array is empty — no routes are excluded.
• Authorization: Role-based access control (RBAC) via CheckRole middleware ensures admin routes are protected.
• Internal Services: Service-to-service authentication uses a configurable token (INTERNAL_SERVICE_TOKEN) via config('services.immune.internal_token'). No hardcoded secrets exist in the codebase.

3.2 Configuration Conventions

• config() over env(): All application code uses config() to read environment values. Direct env() calls are only permitted inside config/*.php files. This ensures compatibility with php artisan config:cache.
• Required .env variables: INTERNAL_SERVICE_TOKEN, OPENAI_API_KEY, NTFY_CHANNEL (if notifications enabled), NTFY_ENABLED.

3.3 Network Security

• HSTS: HstsMiddleware is enabled, forcing HTTPS on all connections.
• COOP: CoopMiddleware (Cross-Origin Opener Policy) is active to isolate the browsing context, protecting against Spectre/Meltdown class side-channel attacks.
• CORS: HandleCors is configured to allow * origins for the API (necessary for the recorder to work on any merchant site), but critical admin endpoints are session-protected.
• Rate Limiting: ThrottleRequests is applied to API routes (agent-api group) to prevent abuse.

3.4 Route Protection

• All file upload routes (/upload-image, /wysiwyg/upload) require authentication.
• All content generation routes (/generate-article) require authentication.
• Editor routes (/wysiwyg/*) are protected by auth middleware.

3.5 Shopify Integration

• Consent Gated: The recorder script is never injected until the visitor explicitly grants "Analytics" consent via the Shopify Customer Privacy API.
• No 3rd Party Cookies: We do not set third-party cookies. We rely on the session ID generated by the script for the duration of the visit.
• Data Privacy: No PII (Personally Identifiable Information) is explicitly scraped unless modifying the recorder config. By default, password inputs are ignored.

3.6 Infrastructure Isolation

• Python Workers: Video processing occurs in isolated Python processes, separate from the main PHP application server.
• No Arbitrary Code Execution: Script execution features (ScriptController::execute, SequenceController::run) have been removed. No shell_exec or exec of user-provided code exists.
• Input Validation: Usage of FormRequest classes ensures strict type checking.
• SQL Injection: All database queries use Eloquent ORM bindings, preventing raw SQL injection vectors.

Shopify Extension Documentation

This document details the architecture, installation, and operation of the Immune Session Recorder for Shopify.

1. Overview

The Immune Session Recorder is a Shopify Theme App Extension. This means it integrates directly into the merchant's Onlin Store theme without modifying their code files manually. It allows merchants to enable/disable the recorder via the Shopify Theme Editor (App Embeds).

• Location: shopify_extension/
• Type: Theme App Extension
• Key Functionality: Records visitor sessions only after obtaining GDPR/CCPA analytics consent via Shopify's Customer Privacy API.

2. Directory Structure

shopify_extension/
├── package.json                 # Dependencies (@shopify/app, @shopify/cli)
├── shopify.app.toml             # Main app configuration (Keys, Scopes)
└── extensions/
    └── immune-session-recorder/
        ├── shopify.extension.toml   # Extension metadata
        ├── assets/
        │   └── shopify-recorder.js  # The core recording logic (compresses & sends events)
        └── blocks/
            └── recorder_embed.liquid # The Liquid integration logic (Consent handling)

3. Installation Guide

Prerequisites

• Node.js & NPM
• A Shopify Partner Account
• A Development Store

Deployment Steps

1. Navigate to the extension directory:

   cd shopify_extension
   npm install
   

2. Deploy to Shopify:

   npm run deploy
   

   Follow the CLI prompts to select your Organization and App.

3. Enable on Development Store:

   1. Go to your Shopify Admin.
   2. Navigate to Online Store > Themes.
   3. Click Customize on your active theme.
   4. Open the App Embeds tab (icon on the far left sidebar).
   5. Toggle Immune Session Recorder to ON.
   6. Click Save.

4. Technical Implementation

Consent Handling (recorder_embed.liquid)

We strictly adhere to Shopify's Privacy requirements. The recorder does not start until the user has granted Analytics Consent.

1. Check Existing Consent: On page load, checking Shopify.customerPrivacy.getTrackingConsent().
2. Listen for Changes: Subscribes to Shopify.customerPrivacy.subscribe('consentChanged', ...) to detect when a user accepts the cookie banner.
3. Lazy Load: The actul shopify-recorder.js script is dynamically injected (document.createElement('script')) only when consent.analytics === true.

Recorder Script (shopify-recorder.js)

• Library: Uses a custom build of rrweb for DOM Mutation Observation.
• Endpoint: Sends data to POST /api/session/record on your self-hosted instance.
• Batching: Events are compressed and sent in batches (every 5-10 seconds) to minimize network impact.

5. Development

To work on the extension locally:

cd shopify_extension
npm run dev

This will start a local tunnel (Cloudflare) and allow you to preview changes in your Development Store in real-time.

6. Client Portal

Shopify store owners can view their session recordings through a dedicated client portal.

Access

• URL: https://gabriel0.com/client/login
• Credentials: Contact support for your store-specific credentials

Features

• View all session recordings from your store
• Watch replays of customer sessions
• Filter by duration, device type, and country
• Secure access - only see recordings from your own store domain

Creating Client Accounts

To create a new client account, run:

php artisan tinker

Then:

\App\Models\Client::create([
    'shop_domain' => 'your-store.myshopify.com',
    'email' => 'owner@yourstore.com',
    'name' => 'Store Owner Name',
    'password' => bcrypt('secure-password-here'),
]);

Shopify Integration Specification

This document outlines the technical architecture, data flow, and feature specifications for the functionality of the Immune Session Replay recorder on Shopify stores.

1. Architecture Overview

• Frontend: rrweb-based Javascript recorder injected into the Shopify store via Script Tag or Theme File.
• Backend: Laravel API receiving event batches.
• Database: MySQL/MariaDB for structured storage.
• Video Processing: Python-based worker pipeline (Master/Slave architecture).
• Notifications: ntfy.sh external service.

2. Data Storage & Schema

Table: session_recordings

3. Features & Logic

3.1 Session Replay (rrweb)

• Recorder: The frontend script (shopify-recorder.js) uses rrweb to capture DOM mutations, mouse movements, and inputs.
• Batching: Events are sent in batches to POST /api/shopify/record.
• Merging: The backend store method uses firstOrNew on session_id. Incoming events are appended (array_merge) to the existing events JSON array.
• Replay View: blade template (visits.replay) initializes a new rrweb.Replayer with the stored JSON events.

3.2 Country & Device Detection

• Country:
  • Priority 1: CF-IPCountry header (Cloudflare).
  • Priority 2: Stevebauman\Location (GeoIP database lookup).
• Device:
  • Parsed from User-Agent string using Jenssegers\Agent.
  • Categories: mobile, tablet, desktop, robot.

3.3 Multi-Stage Notifications

The system sends alerts to ntfy.sh based on session duration thresholds. To prevent spam, it uses a state machine tracked by notification_level.

• Level 0 (Start): No notification sent.
• Level 1 (> 10s):
  • Trigger: duration > 10 AND notification_level < 1.
  • Action: Send POST to https://ntfy.sh.
  • Payload: Title="New Session (FR)", Message="New visit from FR".
  • Update: Set notification_level = 1.
• Level 2 (> 60s):
  • Trigger: duration > 60 AND notification_level < 2.
  • Action: Send POST to https://ntfy.sh.
  • Payload: Title="Session Update (FR)", Message="Visitor from FR is still active (>1m)".
  • Update: Set notification_level = 2.

3.4 Video Export

• Trigger: Admin clicks "Export MP4".
• Flow:
  1. VisitController@exportVideo sets video_status to pending.
  2. An AiRequest task (session_video_generation) is created.
  3. Python Master (python_backend/main.py) detects task and dispatches to Worker.
  4. Python Worker (python_backend/main.py) launches headless browser, replays session, and captures screen to MP4 (using ffmpeg).
  5. On completion, video_path is updated and video_status set to completed.

4. API Specification

Endpoint: POST /api/shopify/record

Payload:

{
  "session_id": "uuid-v4-string",
  "shop": "shop-domain.com",
  "events": [
    { "type": 1, "timestamp": 1700000000, "data": {...} },
    ...
  ]
}

Response:

{ "success": true }

5. Installation on Shopify (New: Theme App Extension)

We have migrated to a Shopify Theme App Extension, which is the modern standard for injecting scripts into Shopify stores. This allows merchants to enable/disabe the recorder via the Theme Editor without touching code.

Deployment

1. Navigate to the extension directory:

   cd shopify_extension
   npm install
   

2. Deploy the extension to Shopify:

   npm run deploy
   

3. Follow the CLI prompts to select your Partner Organization and App.

Enabling on Store

1. Go to the Shopify Admin > Online Store > Themes.
2. Click Customize on the active theme.
3. Click App embeds (icon on the far left).
4. Enable Immune Session Recorder.
5. (Optional) Configure the API Endpoint in the settings if needed.
6. Click Save.

Legacy Installation (Manual)

Deprecated. Use the App Extension method above.

To manually enable the session recorder, add the following snippet to your theme's layout/theme.liquid file, just before the closing </head> tag:

<!-- Immune Session Recorder -->
<script>
  window.immuneConfig = {
    endpoint: "https://gabriel0.com/api/shopify/record",
    shop: "{{ shop.permanent_domain }}"
  };
</script>
<script src="https://gabriel0.com/js/shopify-recorder.js" async></script>