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.

Frontend

Libraries

Layout

Side pane

Compiler

Prompting

Trace

WBS

Status Bar

Content area

Classes

Base Classes

Data Classes

UI Components

Backend

Libraries

Components

API Schema

Database Models & API Endpoints

Payloads

Artifacts & Persistent storage

Functionality

Compiler

5 Step Pipeline

Components

C++ Pybindings

UML

Frontend

Backend

Compiler

Integration

Pipeline Algorithm

Basic CRUD Operations

Create

Read

Update

Delete

Compiler Job

Frontend Initialization

Job Dispatch

Native Compilation

State Synchronization

Neural Request

Frontend Initialization

Backend Dispatch

LLM Execution & Persistence

State Synchronization

Testing Plan

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

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

3. Backend Endpoint & Pydantic Structure Validation

4. Frontend Data Dispatch Accuracy

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