dazzle-dsl 0.49.3

DAZZLE — declarative SaaS framework with built-in compliance (SOC 2, ISO 27001), provable RBAC, and graph features

DAZZLE

Model your business. Ship your product. Pass your audit.

Dazzle is a declarative framework for building SaaS applications. You describe your business — its data, its users, its rules, its workflows — in structured .dsl files. Dazzle gives you a working web application with a database, API, UI, authentication, role-based access control, and compliance evidence. No code generation, no build step, no scaffold to maintain.

cd examples/simple_task && dazzle serve
# UI:  http://localhost:3000
# API: http://localhost:8000/docs

---

Why Dazzle

Your business model IS the application

Most frameworks ask you to express your business logic across scattered files — controllers, models, migrations, middleware, templates. When requirements change, you update all of them and hope they stay in sync.

Dazzle inverts this. You write what your business is — entities, roles, permissions, workflows, state machines — and the runtime executes it directly. Change the DSL, refresh the browser. The DSL is the single source of truth for your application, your API spec, your test suite, and your compliance documentation.

Built for the compliance conversation

If you're building SaaS — especially in regulated industries — you will face auditors. They will ask: who can access what? how are changes controlled? where is sensitive data classified?

Most teams answer these questions retroactively, combing through code to produce evidence. Dazzle answers them by construction:

• Access control is declared in the DSL and provably enforced. Every permission is statically verifiable.
• State machines model approval workflows, transitions, and four-eyes authorization.
• Compliance evidence is extracted automatically. Run dazzle compliance compile --framework soc2 and get a structured audit report showing which controls your DSL satisfies.
• Grant-based RBAC supports delegated, time-bounded access with approval workflows — the kind of access governance auditors want to see.

Dazzle currently supports ISO 27001 and SOC 2 Trust Services Criteria out of the box, with automatic evidence mapping from your DSL declarations to specific framework controls.

From idea to running product, fast

module my_app
app todo "Todo Application"

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

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

Save this as app.dsl, run dazzle serve, and you have:

• A PostgreSQL-backed database with correct types and constraints
• CRUD API endpoints with pagination, filtering, and sorting
• A rendered list UI with sortable columns, search, and a create form
• OpenAPI documentation at /docs
• A health endpoint with deployment integrity verification

That's a todo app. But the same language scales to 39-entity accountancy platforms with double-entry ledgers, multi-step onboarding wizards, and role-based dashboards. You add complexity only where your business needs it.

---

What You Can Model

Capability	What it does	Why it matters
Entities	Data models with types, constraints, relationships	Your domain model, declared once
Surfaces	List, detail, create, review views	UI and API from the same declaration
Workspaces	Role-based dashboards with filtered regions	Each persona sees what they need
State Machines	Lifecycle transitions with guards and approval	Business processes enforced, not just documented
Access Control	Cedar-style permit/forbid rules, scope predicates	Provable RBAC — auditors can verify mechanically
Grant Schemas	Delegated, time-bounded access with approval	Four-eyes authorization, SOC 2-ready
Processes	Multi-step workflows with saga patterns	Durable business operations
Experiences	Onboarding wizards, checkout flows	Guided multi-step user journeys
Ledgers	TigerBeetle-backed double-entry accounting	Financial-grade transaction integrity
Graphs	Entity relationships with CTE traversal and algorithms	Network analysis, shortest paths, community detection
Integrations	Declarative API bindings with triggers and mappings	Connect to Stripe, HMRC, Xero, and more
LLM Jobs	Classification, extraction, generation tasks	AI capabilities without prompt engineering sprawl
Compliance	Automated evidence extraction for ISO 27001 and SOC 2	Audit-ready from day one

For the full DSL reference, see docs/reference/index.md.

---

Compliance and Security

Dazzle treats compliance as a first-class concern, not an afterthought.

Automated evidence extraction

Every DSL construct that relates to security — access rules, data classification, state machine transitions, process workflows — is automatically mapped to compliance framework controls. Run:

dazzle compliance compile --framework iso27001   # ISO 27001 audit
dazzle compliance compile --framework soc2       # SOC 2 TSC audit
dazzle compliance gaps --framework soc2          # Show unmet controls

The output is a structured AuditSpec showing which controls are evidenced (your DSL satisfies them), which are gaps (your DSL should cover them but doesn't), and which are excluded (physical security, HR — outside DSL scope).

Provable access control

Scope rules compile to a formal predicate algebra, statically validated against the FK graph at dazzle validate time. The verification framework has three layers:

Layer	What it proves
Static Matrix	Every (role, entity, operation) combination is computed from the DSL
Dynamic Verification	The running app is probed as every role to confirm runtime matches the matrix
Decision Audit Trail	Every access decision is logged with the matched rule and outcome

dazzle rbac matrix    # Generate the access matrix (no server needed)
dazzle rbac verify    # Verify runtime matches the matrix (CI gate)
dazzle rbac report    # Compliance report for auditors

See RBAC Verification and Compliance for details.

---

Quick Start

# Install
brew install manwithacat/tap/dazzle   # macOS/Linux (auto-registers MCP server)
# or: pip install dazzle-dsl

# Run the example
cd examples/simple_task
dazzle serve

# Open http://localhost:3000 for the UI
# Open http://localhost:8000/docs for the API

---

AI-Assisted Development

Dazzle ships as both a runtime and an AI development environment. When used with Claude Code (via MCP), you get access to 26 tools with 170+ operations that span the full lifecycle:

Stage	What the tools do
Spec to DSL	Turn a natural-language idea into validated DSL — entity discovery, lifecycle identification, persona extraction
Test and Verify	Generate stories, design tests, execute at three tiers (API, browser, LLM-guided), seed demo data
Analyze and Audit	Quality pipeline, agent-powered gap discovery, visual composition analysis, RBAC policy verification
Site and Brand	Manage public site structure, copy, theme, and design tokens from spec files
Stakeholder Ops	Launch readiness scores, investor pitch generation, user/session management

The agent framework uses an observe-decide-act-record loop to autonomously explore running applications, discover gaps, and propose DSL fixes. Discovery modes include persona-based exploration, CRUD completeness analysis, workflow coherence checks, and headless DSL/KG analysis.

For the full MCP tool reference, see Architecture: MCP Server.

Claude Code Integration

# Homebrew: MCP server auto-registered during installation
brew install manwithacat/tap/dazzle

# PyPI: Register manually
pip install dazzle-dsl
dazzle mcp-setup

# Verify
dazzle mcp-check

---

Architecture

DSL Files  →  Parser + Linker  →  AppSpec (IR)  →  Runtime (live app)
                                                 →  OpenAPI / AsyncAPI specs
                                                 →  Test generation
                                                 →  Compliance evidence
                                                 →  Fidelity scoring

The DSL is parsed into a typed intermediate representation (AppSpec IR). The runtime executes the IR directly — no code generation step. Every artifact (API specs, tests, compliance reports, demo data) is computed from the same IR.

This architecture is deliberately anti-Turing: the DSL has no arbitrary computation, which means Dazzle can statically validate, lint, measure fidelity, and reason about your application. What you declare is what runs.

The frontend uses server-rendered HTML with HTMX — zero build toolchain, stable technology, and full visibility into what the runtime produces.

For the full architecture, see docs/architecture/overview.md.

---

Examples

Example	Complexity	What it demonstrates
simple_task	Beginner	3 entities, state machine, personas, workspaces, access control
contact_manager	Beginner	CRM with relationships and list/detail surfaces
support_tickets	Intermediate	Ticket lifecycle with state machines and assignments
ops_dashboard	Intermediate	Workspace stages and aggregate metrics
fieldtest_hub	Advanced	Full-featured demo with integrations
pra	Advanced	15 DSL files covering every construct: ledgers, processes, LLM, services

---

IDE Support

Full LSP implementation: real-time diagnostics, hover docs, go-to-definition, auto-completion, document symbols.

dazzle lsp run           # Start the LSP server
dazzle lsp check         # Verify dependencies
dazzle lsp grammar-path  # TextMate grammar for syntax highlighting

Works with VS Code, Neovim, Emacs, and any editor supporting LSP. See docs/reference/index.md for editor setup.

---

Documentation

• DSL Reference — complete guide to all DSL constructs
• Graphs — entity graph relationships, CTE traversal, algorithms
• Compliance — ISO 27001 + SOC 2 evidence pipeline
• RBAC Verification — provable access control
• Architecture — system design, pipeline, MCP server
• Getting Started — installation, quickstart, first app
• Examples — runnable example applications

---

Contributing

All contributions require AI co-authorship. See CONTRIBUTING.md.

License

MIT - see LICENSE