Skip to content

Dazzle Developer Docs

DAZZLE is a DSL-first toolkit for building apps from high-level specifications.

# Get started in seconds
cd examples/simple_task && dazzle serve
# UI: http://localhost:3000 | API: http://localhost:8000/docs

What is Dazzle?

Dazzle transforms domain specifications written in a human-readable DSL into working applications. Define your entities, surfaces, and workspaces once - get a full-stack app with:

  • FastAPI backend with automatic CRUD, validation, and OpenAPI docs
  • HTMX frontend with server-rendered templates and vanilla JS interactions
  • Docker deployment ready out of the box

Quick Navigation

  • Getting Started

    Install Dazzle and build your first app in minutes.

    Installation

  • DSL Reference

    Complete reference for the Dazzle DSL syntax.

    Reference

  • Examples

    Explore complete example applications.

    Examples

  • Architecture

    Understand how Dazzle works internally.

    Architecture

Core Concepts

DSL to App Pipeline

graph LR
    DSL[DSL Files] --> Parser
    Parser --> IR[AppSpec IR]
    IR --> Back[FastAPI Runtime<br/>dazzle/back]
    IR --> UI[Server-rendered UI<br/>dazzle/ui · typed Fragments + HTMX]
    IR --> Derived[Derived artefacts]
    Derived --> OAS[OpenAPI / AsyncAPI specs]
    Derived --> Tests[Generated tests]
    Derived --> Audit[Compliance evidence]
    IR --> MCP[MCP server<br/>dazzle/mcp]
    MCP --> KG[(Knowledge graph<br/>+ counter-prior catalogue)]

The runtime executes the IR directly — no code generation step. Every artefact on the right is computed from the same IR. The MCP path is how agents introspect, query, and propose changes; the counter-prior catalogue at docs/counter-priors/ is the substrate's antipattern-flagging surface, queryable via knowledge counter_prior.

Key Constructs

Construct Purpose
entity Data model with fields, constraints, computed values
surface UI view of an entity (list, detail, create, edit)
workspace Collection of surfaces with layout
service Custom business logic and operations
process Multi-step workflows with state machines
story Behavioural user stories for test generation
experience Multi-step user flows and wizards
persona User roles with goals and permissions
ledger Double-entry accounting (TigerBeetle)
integration External API connections
message / channel Messaging, email, and notifications
schedule Cron and periodic tasks

Example DSL

module my_app
app todo "Todo App"

entity Task "Task":
  id: uuid pk
  title: str(200) required
  completed: bool = false

surface task_list "Tasks":
  uses entity Task
  mode: list
  section main:
    field title "Title"
    field completed "Done"

LLM-Friendly Design

Dazzle is built for the AI era:

  • Deterministic generation - Same input always produces same output
  • Semantic clarity - DSL constructs map directly to implementation
  • MCP server - AI agents can introspect and modify Dazzle projects

See llms.txt for an agent-oriented overview. For the end-to-end authoring loop (spec change → agent edit → validate → tests → human review → deploy), see the Agent Workflow Guide. For watching a running application (health probes, event subsystem, jobs, metrics), see the Observability Guide. For the framework's threat model, the framework-vs-app security responsibility matrix, and the app-developer security checklist, see the Security Guide. For where the runtime is fast, where it degrades with data size, and the reproducible benchmark behind those numbers, see the Performance Envelope.

Getting Help