Architecture

Aludel is arranged as a disciplined workshop: LiveView at the surface, contexts as the hands of the craft, and behaviour-based interfaces where the system meets outside forces.

System Overview

flowchart LR
    UI[LiveView UI]
    C[Contexts]
    I[Interfaces]
    X[External Services]
    DB[(PostgreSQL)]

    UI --> C
    C --> I
    C --> DB
    I --> X

Loading

Context Boundaries

Context	Responsibility
Prompts	Templates, prompt versions, and projects
Runs	Prompt execution across one or more providers
Evals	Test suites, assertions, and evaluation orchestration
Providers	Provider configuration and model selection
Stats	Aggregated metrics such as latency, cost, and success rate

Interface Layer

The interface layer keeps provider-specific logic out of the contexts, so new integrations can be introduced like new metals in the crucible, without recasting the rest of the system.

LLM Behaviour

@callback call(config :: map(), prompt :: String.t()) ::
  {:ok, response :: String.t()} | {:error, term()}

Current implementations:

• OpenAI
• Anthropic
• Ollama

Document Converter Behaviour

@callback convert(source :: String.t(), format :: String.t()) ::
  {:ok, path :: String.t()} | {:error, term()}

Current implementation:

• ImageMagick for document-to-image conversion such as PDF to PNG

Primary Flows

Prompt Execution

This is the main path from intent to result: a prompt is shaped in the UI, handed to the run engine, translated through a provider adapter, and returned with enough telemetry to judge its worth.

sequenceDiagram
    participant U as User
    participant LV as LiveView
    participant R as Runs
    participant L as LLM Behaviour
    participant P as Provider API
    participant DB as PostgreSQL

    U->>LV: Submit prompt variables and providers
    LV->>R: execute_run/2
    R->>L: call/2 for each provider
    L->>P: HTTP request
    P-->>L: Model response
    L-->>R: Normalized result
    R->>DB: Persist run and run_results
    R-->>LV: Return execution status and metrics

Loading

Suite Execution

Suite execution repeats that same fire under controlled conditions, so prompts can be tested as instruments rather than admired as artifacts.

flowchart TD
    A[LiveView starts suite run]
    B[Evals.run_suite/2]
    C[Iterate test cases]
    D[Create run]
    E[Execute prompt via Runs]
    F[Validate assertions]
    G[Aggregate results]
    H[Persist suite_run]

    A --> B --> C --> D --> E --> F --> C
    C -->|all test cases processed| G --> H

Loading

Deployment Modes

• Standalone: self-contained Phoenix application
• Embedded: packaged into a host application and mounted in its router while sharing repo and config

Extension Points

• Add an LLM provider by implementing Aludel.Interfaces.LLM.Behaviour
• Add a document converter by implementing Aludel.Interfaces.DocumentConverter.Behaviour

See Data Model for entity relationships and storage details.