- ## Frontend

  - ### Libraries

    - Typescript
    - Zodios
    - Svelte
    - NodeJS

  - ### Layout

    - #### Side pane

      Research Modes

      - Server Configuration

      - ##### Compiler

        - Compiler Configuration
        - Abstract Syntax Tree
        - Dataset Builder

      - ##### Prompting

        - Research Modes
        - Prompts
        - Prompt Configuration
        - Prompt Relations
        - Inference Window

      - ##### Trace

        - Logs

      - ##### WBS

        - Tasks
        - Phases

    - #### Status Bar

      - Compile
      - Prompt
      - WBS
      - UML

    - #### Content area

      - Terminal
      - LLM Prompt
      - WBS
    - Notifications

  - ### Classes

    - #### Base Classes

      - BaseState
      - BaseLibrary
      - BaseCRUD

    - #### Data Classes

      - Prompt / PromptLibrary
      - PromptConfig / PromptConfigLibrary
      - PromptPair / PromptPairLibrary
      - ResearchTier / ResearchTierLibrary
      - LLMModel / LLMModelLibrary
      - LLMServer / LLMServerLibrary
      - Server / ServerLibrary

  - ### UI Components

    - DynamicField
    - CrudModelView
    - GenericForm
    - TaskEditorModal
    - GenericListView
    - CollapsablePane

- ## Backend

  - ### Libraries

    - PyDantic
    - SQL Alchemy
    - PyDantic
    - FastAPI
    - Unicorn
    - SQLLite

  - ### Components

    - Engine
    - ASTSerializer
    - Controllers
    - Router / Endpoints
    - Database

    - #### API Schema

      - Create
      - Read
      - Update
      - Delete
    - Migrations & Seeds

  - ### Database Models & API Endpoints

    - ResearchMode
    - Prompt
    - PromptConfig
    - PromptPair
    - CompilerConfig
    - Manifest
    - BatchJob
    - CompilerJob
    - LLMModel
    - LLMServer
    - WBSPhase
    - WBSTask

  - ### Payloads

    - CommandPayload
    - DispatchContext

  - ### Artifacts & Persistent storage

    - CompileJobs
    - BatchJobs
    - AST / Source Code
    - Binary Code
    - BuildRegistry

  - ### Functionality

    - API Server
    - Database Storage
    - Compiler Interface
    - Data Generation

- ## Compiler

  - ### 5 Step Pipeline

    1. Frontend Lex/Parse (JSON AST to `ILanguageProvider` validation).
    2. Seeded Interning (Function/Object to Base 38 Macro mapping).
    3. Linearization (AST to 1D token stream).
    4. Logic Squeeze (SSA reduction, constant folding, DCE).
    5. Tier 0 Emission (.hex binary generation and Shadow Alias Registry mapping).

  - ### Components

    - DocumentWriter
    - Artifacts
    - Driver
    - RunConfig
    - CompilationResult/Manifest
    - ISRMap
    - Interner
    - ConfigProxy
    - Optimizer
    - SchemaBuilder
    - OptionDef
    - ILanguageProvider
    - SymbolRegistry
    - RotatingFileSink
    - TokenRegistry
    - VM

  - ### C++ Pybindings

    - Manifest
    - RunConfig
    - process_single_mission

# UML

- ## Frontend

      classDiagram
          class App {
              +TerminalController ctrl
              +String researchMode
          }

          class TerminalController {
              +Dataset dataset
              +CompilerConfig compilerConfig
              +String apiUri
              +Object systemStatus
              +executeCommand(commandName)
              +pollForResult(build_id)
              +handleMutation()
              +syncSystemLogs()
          }

          class Terminal {
              +String terminalInput
              +dispatchMutation()
          }

          class ASTViewer {
              +Object data
              +renderTree()
          }

          class RegisterGrid {
              +Object registers
              +Array gridData
          }

          class SystemLog {
              +Array logs
              +autoScroll()
          }

          class DatasetBuilder {
              +startBuild(count, depth)
              +pollDataset()
              +stopBuild()
          }

          App *-- TerminalController
          App *-- Terminal
          App *-- ASTViewer
          App *-- RegisterGrid
          App *-- SystemLog
          TerminalController *-- DatasetBuilder

- ## Backend

      classDiagram
          direction TB

          class BaseRouter {
              <<Gateway>>
              +handler
              +setup_routes()
          }

          class CommandPayload {
              <<Pydantic>>
              +String command
              +Dict selections
              +String code
              +DispatchContext context
          }

          class HexaCore {
              <<Service>>
              +compile_and_run(model_type, code, seed)
              +create_job(payload, db)
              +run_saved_job(build_id)
              +get_compiler_capabilities()
          }

          class BaseController {
              <<Generic>>
              +get_all()
              +get_by_id(id)
              +create(payload)
              +update(payload)
              +delete(id)
          }

          class CompileJobController {
              <<Controller>>
          }

          class ManifestController {
              <<Controller>>
          }

          class ASTController {
              <<Controller>>
          }

          class CompileJob {
              <<ORM>>
              +int id
              +String status
              +int ast_id
              +int config_id
              +int manifest_id
          }

          class BuildRegistry {
              <<ORM>>
              +int id
              +String label
              +int compiler_config_id
              +int ast_id
              +from_payload()
          }

          class Manifest {
              <<ORM>>
              +int id
              +JSON vm_state
              +JSON integrity
              +JSON return_status
          }

          class AST {
              <<ORM>>
              +int id
              +String file_hash
              +String file_path
              +String code()
              +JSON ast_json()
              +create_from_code()
          }

          class CompilerConfig {
              <<ORM>>
              +int id
              +String name
              +Boolean is_active
              +inject_columns()
          }

          BaseRouter --> BaseController : Routes to
          BaseController <|-- CompileJobController
          BaseController <|-- ManifestController
          BaseController <|-- ASTController

          CommandPayload --> HexaCore : Validates & Ingests
          HexaCore ..> CompileJob : Initializes
          HexaCore ..> Manifest : Hydrates from C++

          CompileJob "1" --> "1" AST : Requires
          CompileJob "1" --> "1" CompilerConfig : Requires
          CompileJob "1" --> "1" Manifest : Produces

          BuildRegistry "1" --> "1" AST : Tracks
          BuildRegistry "1" --> "1" CompilerConfig : Tracks
          BuildRegistry "1" --> "1" Manifest : Links

- ## Compiler

      sequenceDiagram
          autonumber
          participant FE as Frontend (Svelte)
          participant API as FastAPI (Backend)
          participant DB as SQLite (BuildRegistry)
          participant PYB as Pybind11 (libhexacore)
          participant CFG as hexa::RunConfig
          participant DRV as hexa::Driver
          participant VM as hexa::VM (Proprietary Engine)
          participant DW as hexa::DocumentWriter

          FE->>API: POST /dispatch (Source, CompilerConfig)
          API->>DB: Insert CompileJob (Status: PENDING)
          API->>PYB: process_single_mission(config_dict, ast_json)

          rect rgb(30, 30, 30)
              Note over PYB, DW: C++ Core Execution Subsystem
              PYB->>CFG: RunConfig::from_json(config_dict)
              PYB->>DRV: process_single_mission(config, ast)
              DRV->>VM: Initialize CompilerContext & Execute Pipeline
              Note over VM: Pass 1-5 Execution (Black Box)
              VM-->>DRV: Execution Complete (VMState, Registers)
              DRV->>DW: generate_report(status)
              DW-->>DRV: Telemetry & Artifacts JSON
              DRV-->>PYB: CompilationResult
          end

          PYB-->>API: Native Python Dict (Manifest Data)
          API->>DB: Update CompileJob (COMPLETED) & Insert Manifest
          API-->>FE: Return Execution Telemetry & Artifacts

- ## Integration

      sequenceDiagram
          autonumber
          participant FE as Frontend (Svelte 5)
          participant API as FastAPI (Backend)
          participant DB as SQLite (Registry)
          participant CPP as C++ Core (LibHexa)
          participant FS as Git-Backed Filesystem

          FE->>API: POST /dispatch (Source + Config)
          API->>DB: Hash Check (Idempotency Guard)
          alt Unique Hash
              API->>FS: Write Source & Git Commit
          end
          API->>DB: Initialize CompileJob (Status: PENDING)
          API-->>FE: Return build_id
          loop Telemetry Synchronization
              FE->>API: GET /task/{build_id}
          end
          API->>CPP: process_single_mission(AST, ConfigProxy)
          CPP->>CPP: 5-Pass Compile & VM Execution
          CPP-->>API: CompilationResult (Manifest, VMState)
          API->>DB: Update CompileJob (Status: COMPLETED)
          API-->>FE: Task Status: SUCCESS + Payload
          FE->>FE: Hydrate State (ASTViewer, RegisterGrid)

# Pipeline Algorithm

- ### Basic CRUD Operations

  1. #### Create

     1. The frontend
        - Opens the Prompt Registry pane
        - Validates the payload before sending it to the server
        - Sends a POST request to the backend
     2. The backend
        - receives the request
        - Validates the payload
        - Stores the record in the database
        - Sends a response to the frontend
     3. The frontend
        - Receives the response from the backend
        - Notifies the user of succes or failure

  2. #### Read

     1. The frontend
        - Opens the Prompt Registry pane
        - Sends a GET request to the backend, requesting data
     2. The backend
        - Receives the request
        - Validates the payload
        - Fetches the record from the database
        - Sends a response to the frontend
     3. The frontend
        - Receives the response from the backend
        - Hydrates the Promp Registry

  3. #### Update

     1. The frontend
        - Opens the Prompt Registry pane
        - Makes local changes to an existing record
        - Validates the payload before sending it to the server
        - Sends an UPDATE request to the backend
     2. The backend
        - Receives the request
        - Validates the payload
        - Updates the record in the database
        - Sends a response to the frontend
     3. The frontend
        - Receives the response from the backend
        - Notifies the user of success or failure

  4. #### Delete

     1. The frontend
        - Opens the Prompt Registry pane
        - Locates an existing record
        - Validates the payload before sending it to the server
        - Sends a DELETE request to the backend
     2. The backend
        - Receives the request
        - Validates the payload
        - Deletes the record from the database
        - Sends a response to the frontend
     3. The frontend
        - Receives the response from the backend
        - Notifies the user of success or failure

- ### Compiler Job

  1. #### Frontend Initialization

     - Opens the compiler configuration pane and establishes settings.
     - Opens the terminal and selects the target script.
     - Validates the payload data structure.

  2. #### Job Dispatch

     - Frontend transmits the payload to the server via HTTP POST.
     - Server receives and validates the incoming payload.
     - Server responds with a unique Job ID and begins asynchronous execution.
     - Frontend subscribes to the task by initiating a polling loop (HTTP GET) using the Job ID.

  3. #### Native Compilation

     - Server passes the validated payload to the C++ compiler via Pybind11.
     - Compiler executes the pipeline and saves output artifacts to disk.
     - Compiler returns the execution manifest back across the Pybind11 boundary.

  4. #### State Synchronization

     - Backend receives the manifest and persists it to the database.
     - Frontend polling loop detects the job status transition from "building" to "success".
     - Frontend issues a final GET request to fetch the manifest and hydrate the interface.

- ### Neural Request

  1. #### Frontend Initialization

     - Opens the prompt dashboard.
     - Selects a designated PromptPair and target Python script.
     - Validates the payload data structure.

  2. #### Backend Dispatch

     - Frontend transmits the payload to the server via HTTP POST.
     - Backend receives and validates the incoming request.
     - Backend persists the initial payload state in the database.

  3. #### LLM Execution & Persistence

     - Backend routes the payload to the designated local LLM server via HTTP POST.
     - LLM server processes the prompt and returns the generated inference.
     - Backend receives the inference result and updates the database record.

  4. #### State Synchronization

     - Backend returns the final inference response to the frontend.
     - Frontend renders the comparative results within the dual-pane Inference Window.

# Testing Plan

- ## 1. C++ Pybindings Validation (GTest & Pytest)

  - Test Cases:
    - `test_safe_assign_binding_integrity`: Pass Boolean, Integer, and Enum string types from Python dictionaries into C++ `hexa::RunConfig` via Pybind11.
    - `TestManifestBridge`: Validate C++ `hexa::CompilationResult` properties correctly reflect into Python `ManifestModel` schema.
    - `ConfigSafetyTest.HandlesMalformedJSONInjection`: Inject deeply nested or malformed JSON payloads into `RunConfig::from_json`.
  - Expected Outcomes: C++ layer extracts Python variables without segmentation faults. Type mismatches or overflows trigger controlled fallbacks or raise caught `std::invalid_argument` exceptions passed back to Python. `Manifest` generation strictly enforces mandatory fields.
  - Verification Methods: Pytest assertions on data type mapping (`isinstance`). GTest `EXPECT_NO_THROW` and `EXPECT_EQ` ensuring safe fallback values (e.g., `SEEDLESS_VALUE`).

- ## 2. Class Object Integrity (C++, Python, TypeScript)

  - Test Cases:
    - C++ Core: `OptimizerLogicTest` for dead code elimination and constant folding; `LinearizerTest` for nested math AST translation; `VMTest` for memory bound checks (`HighRegisterPressure`), loop termination, and stack underflow logic.
    - Python Backend: `TestOracle` and `HexaASTSerializer` for validating accurate translation of native Python `ast` nodes to JSON.
    - TypeScript Frontend: `BaseCRUD` memento pattern tests (`isDirty` flag logic). `BaseLibrary` collection hydration.
  - Expected Outcomes: Optimizer reduces AST complexity without altering deterministic output. VM halts predictably on stack underflow or type mismatch (`ThrowsOnTypeMismatch`). TS models track local state mutations and revert cleanly.
  - Verification Methods: GTest executing bytecode and validating literal extraction (`get_double`). Pytest validating dictionary structure of serialized AST. Vitest verifying Svelte `$state` reactivity and dirty flags.

- ## 3. Backend Endpoint & Pydantic Structure Validation

  - Test Cases:
    - `TestCompilerConfigDynamicOrchestration`: Verify FastAPI endpoint schema matches the dynamically generated C++ `SchemaBuilder` payload.
    - `test_dispatch_pipeline_success`: Post `CommandPayload` to `/api/dispatch` triggering database entry and background worker queue.
    - `TestCompileJobOrchestration`: Validate DB integrity and cascading foreign keys across `AST`, `CompilerConfig`, and `CompileJob`.
  - Expected Outcomes: API endpoints correctly enforce `BatchConfig` and `CommandPayload` Pydantic contracts. Missing required fields yield `422 Unprocessable Entity`. Authorized requests insert SQLite records and spawn multiprocessing tasks successfully.
  - Verification Methods: Pytest `TestClient` executing HTTP requests. SQLAlchemy `inspect(CompilerConfig)` asserting exact column parity with C++ configuration definitions.

- ## 4. Frontend Data Dispatch Accuracy

  - Test Cases:
    - `BaseCRUD.Validation`: Pass invalid/incomplete forms into TS model before dispatch.
    - `getValidPayload`: Verify stripping of UI-only properties (e.g., `isEditing`) before network transmission.
  - Expected Outcomes: Zod schemas intercept malformed data client-side, throwing `ValidationError` and halting `fetch`. Generated payloads strictly match the backend's expected JSON format.
  - Verification Methods: Vitest `expect(() => getValidPayload(true)).toThrow()`. Spying on internal `apiFetch` calls to assert the shape of the intercepted HTTP body.

- ## 5. End-to-End API Integration & Telemetry Synchronization

  - Test Cases:
    - `runIntegrationSuite`: Execute chained sequence creating `ResearchTier` -> `LLMServer` -> `Prompt` -> `LLMModel` -> `PromptConfig`.
    - `FullChainTest`: Inject Python AST payload, execute compiler pass, and await trace result.
  - Expected Outcomes: System maintains state synchronization across the network boundary. C++ execution yields physical `.hex` and `.meta.json` files. Database accurately links execution `Manifest` to the original `CompileJob`. WebSocket/Polling loops hydrate the UI `RegisterGrid` and `ASTViewer` with zero data mutation.
  - Verification Methods: Vitest polling tests resolving simulated backend responses. GTest `fs::exists` verifying absolute file paths of generated artifacts in the scoped temporary workspace.