monl-compiler

Describe your app in one short text file; monl builds the backend — database, API, user accounts and permissions.

app MyProjects
entity Project
    title: String
    description: Text
actor Visitor selfRegister
actor Admin
rule Project.Read public
workflow Browse for Visitor
    Read Project
workflow Manage for Admin
    Create Project
seed Project
    title: "First project", description: "Ready to explore."

→ You get: a running API (routes your website can call) with an interactive /docs page, sign-up and login, a SQLite database with demo data, and manage.py to create admins. This example's public /project route returns First project immediately. The seed block supplies those demo records.

The same file and compiler version always give the same backend code, with no AI and no network. Custom business logic is left as empty stubs for you to implement. The website UI is optional: AI can draw it from the frontend contract, a description of the API routes, fields and permissions it must follow.

To change the app, edit the file and recompile; never edit generated code.

Contents

• Quick start
• Why monl-compiler?
• Architecture
• Commands
• The specification
• The generated backend
• Your files: photos, logo, favicon
• Replace content without opening the spec
• The frontend: contract and specialized AI
• Quality and verification
• Repository structure
• Documentation
• License

Quick start

Allow about 5–10 minutes for installation and your first backend; adding an AI-built interface takes extra time depending on your provider. monl opens a guided dialogue so you can write the spec without knowing its syntax. Its express mode asks for the site type, name and a one-sentence description, then prepares the specification, demo data and a brief (instructions describing the content and intended interface). The dialogue's “Quick creation with AI” label refers to the later interface step: specification and backend generation use no model and no network call. At the end, open http://127.0.0.1:8000/docs to explore the API; if you add an interface, open http://127.0.0.1:8000/site.

pip install monl-compiler
monl
monl frontend MyProject --provider codex
monl run MyProject

From a repository clone, pip install . installs the same thing.

Frontend providers that use an API require the optional extra: pip install 'monl-compiler[ai]'. Local agents and monl import do not need it.

The Detailed customization workflow remains available for choosing every option, role, editorial content item, and visual intention. Without a local agent or API key, open MyProject/docs/FRONTEND_PROMPT.md in the AI of your choice, then install the resulting ZIP or HTML file with monl import.

The full workflow, including the interface, is described in QUICKSTART.md.

Why monl-compiler?

What you write: a one-page specification. What you change afterward: that same page. The generated code is recompiled; it is never a starting point to edit.

These safeguards cover the rules supported by the compiler; they do not guarantee an application's overall security. The suitability of the declared permissions, custom code, the frontend, dependencies, and operations require their own checks. Generated sources are deterministic; secrets created for each project and runtime data are not part of that identity. See the security model and the operations guide.

Architecture

The dialogue produces the specification; the compiler derives both the backend and the frontend contract from it; AI writes the interface against this contract; monl run checks that all three remain consistent before launching the application.

Commands

Each project is compiled in its own directory through --output, so the previous one is not overwritten. Specifications use the .ml extension.

Claude Code plugin

The repository is also a Claude Code plugin marketplace. The monl-compiler plugin teaches Claude to write a spec from examples, compile it, check it against a real server, and then build its interface:

claude plugin marketplace add Bodichane/monl-compiler
claude plugin install monl-compiler@monl-compiler

In a session, use /monl-compiler:monl-spec followed by what the application should do. The skill calls the command line through uvx, without prior installation, using the plugin version. The plugin is published in Anthropic's directory: install it from the directory, or use the two commands above.

Web platform and MCP

The compiler is also available through a web platform: it validates a spec, compiles the backend, exposes its contract, and delivers an archive without secrets:

monl-platform --port 8022

MCP-compatible agents can call the same pipeline with monl-mcp over stdio or the HTTP endpoint /mcp. No second generator is maintained: the CLI, web, and MCP all delegate to compile_project.

See Web platform and MCP server.

In production, compose.platform.yaml launches the application as a non-root user with persistent storage, readiness checks, shared quotas, and isolated compilations. The port remains bound to localhost so it can be published behind an HTTPS reverse proxy. The reproducible procedure (variables, DNS, TLS, backups, and probes) is detailed in the deployment runbook.

The specification

A spec describes entities (tables and fields), actors (roles), and access rules. The compiler derives the schema, CRUD routes, and access control from it. Identifiers are constrained by the grammar, which rules out injection through table or column names.

Access control is expressed at the record level, including reads:

Field constraints are enforced, not merely declared:

Other markers refine fields and behavior: hidden, generated, categorized, derivedFrom / sumOf (amounts calculated by the server), payable (payment collection, below), as well as a seed block (demo records inserted at startup without duplicating them) that pre-populates the database. A rule with no effect is refused at compilation rather than silently ignored — and so is a rule that names a nonexistent field: a constraint that matches nothing gives the impression of protection that does not exist.

Five commented reference specifications in exemples/: a one-page .ml file for each application — portfolio, shop, social network, kanban, ranking — from which monl-compiler derives everything else.

The generated backend

Accounts and roles. POST /register accepts only roles marked selfRegister; any other role is refused (403). Privileged accounts are created with the generated manage.py, on the machine hosting the database: python3 manage.py adduser <username> <role>. The same command manages roles, passwords, the account list, and global session revocation. With B4 TOTP enabled, python3 manage.py totp-reset <identifier> is the operator recovery command: it clears TOTP and revokes all sessions for that account. Email password reset preserves TOTP. TOTP activation requires the current password and a valid code; activation, password reset, and manage.py passwd invalidate existing access and refresh tokens. Every device must log in again.

Authentication. A user registry dedicated to each application (table _monl_users, passwords in PBKDF2-HMAC-SHA256, a unique salt per account, constant-time comparison). Flow: POST /register → POST /login (JWT token, a signed proof of login sent with later requests) → POST /logout (revocation before expiration). The role and identity carried by the token come from the actual account, never from a client declaration.

JWT secret. Generated randomly on the first compilation, stored in .jwt_secret (never versioned). In production, MONL_JWT_SECRET takes precedence and lets you deliver a project without a secret on disk.

Multi-worker. Token revocation and rate limiting (5 attempts / 60 s / IP on /register and /login) are persisted in the database, so they are shared: uvicorn app:app --workers N does not multiply the quotas. Behind a trusted reverse proxy, MONL_TRUST_PROXY=1 makes the app read the real IP from X-Forwarded-For; without this setting the header is ignored to prevent spoofing.

Migrations. Recompiling in the same directory while keeping app.db adds columns with ALTER TABLE ADD COLUMN without touching the data. Destructive changes are not automated, by design — see docs/MIGRATIONS.md.

Served routes. /docs (Swagger, always available) · / (redirects to /docs) · /site (the interface, if frontend/ exists and the app is started with monl run).

Your files: photos, logo, favicon

A broken image is only visible to the eye, once deployed — the worst place to discover a typo. So the files you provide are declared in the spec, and the compiler refuses to compile if they are not there:

assets
    dir: "assets"
    logo: "logo.svg"

entity Produit
    photo: Image          # a LOCAL file, checked for presence

Image designates a project file: a URL is refused, because monl makes no network calls and could not verify anything about a remote address — String remains available for that case, without verification. The directory lives outside frontend/, which is renamed each time the frontend is rebuilt.

To avoid writing these paths by hand:

monl assets add ~/photos/IMG_4821.jpg --for "Halo RS"   # → assets/halo-rs.jpg
monl assets add ~/logo.svg --logo
monl assets list                                        # present, missing, orphaned

The command copies the file, renames it as a slug, writes the declaration — then has the compiler revalidate the resulting spec before saving it. If it is refused, neither the spec nor the directory is modified. It never deletes a file: replacing a photo marks the old one as orphaned; it does not delete it.

Replace content without opening the spec

The demo data lets you see an interface immediately, but it is not meant to become the real catalog. A person can replace text, prices, and photo names with a spreadsheet:

monl content export MyProject
# edit content/Produit.csv and put the photos in assets/
monl content import MyProject
monl update MyProject

Each CSV preserves the order of fields and records. LISEZMOI.txt explains in French the allowed values, required fields, limits, and expected images. An empty cell is omitted: the actual compiler decides whether it was required. Invalid numbers, missing files, suspicious paths, and ambiguous blocks are refused before any writes. Import replaces the entity's entire content; it never silently merges two sources of truth.

The frontend: contract and specialized AI

The interface is written by an AI, from a business contract and a visual direction prepared before coding. Each compilation produces:

• frontend_contract.json — a machine-readable description of the routes intended for the interface, authentication, and field rules, derived from the same spec as the backend;
• in docs/, the material to read before writing the interface:
  • FRONTEND_PROMPT.md — the brief to give an interface AI: structure, roles, content, and declared intent, without visual prescriptions;
  • DESIGN_SYSTEM.md — page pattern, starting tokens, anti-patterns, and UX checklist determined from the contract;
  • DESIGN_SPEC.md — editable visual summary; if the author replaces it, it takes priority and Monl does not overwrite it;
  • ASSET_MANIFEST.json — asset plan and section markers, verifiable after monl frontend or monl import.

The design system also selects a local catalog of Monl patterns — hero, catalog, editorial, reassurance, FAQ, contact, and final CTA — with variants suited to the application type. These patterns are standalone HTML/CSS/JS structures, not React components to install.

The AI writes to frontend/ (entry point index.html), which monl run serves at /site without ever touching the backend. Several paths, the same safeguards:

Any key will do. OpenAI-dialect providers — groq, openai, openrouter, deepseek, mistral, together, xai, ollama — are preconfigured, each reading its own environment variable. For an endpoint not in this list, use --provider openai-compatible with MONL_AI_BASE_URL and MONL_AI_API_KEY. Outside the Anthropic path, --model is required: monl hardcodes no model ID, because catalogs change too quickly for a fixed value to stay accurate. The key is always read from the environment, never passed as an argument — the shell would record it.

Shared safeguards: allowlisted extensions, protection against zip-slip, a standalone frontend without a CDN, design direction injected before generation, and systematic rechecking of routes, assets, and required sections.

No API key, no credit card, no network

The compiler never calls the outside world. monl compile produces app.py, schema.sql, manage.py, the contract, and the brief entirely offline: the parser, validator, and generator contain no network calls. The entire backend — routes, database, JWT, access control, payments, back office — is obtained without an account anywhere. AI is involved only in the frontend step, and this step has a path without any key:

monl compile boutique.ml --output ./Boutique   # offline
# paste the contents of Boutique/docs/FRONTEND_PROMPT.md into any browser-accessible
# assistant, retrieve the result…
monl import interface.zip ./Boutique           # same safeguards, same verification
monl run ./Boutique

monl import is not a backdoor: the source comes from a conversation, so it is treated as untrusted input — extension allowlist, zip-slip refusal, CDN refusal, index.html required, then consistency check and smoke test, exactly like an API response.

What remains, depending on what you have available: --provider ollama for a fully local model, command-line agents that authenticate by subscription rather than by key, and OpenAI-dialect providers, several of which offer a free tier. monl does not favor or resell any of them: it consumes no tokens on its own account.

What has been proven, and what has not. The offline path, the copy-paste path, and the Anthropic path have been tested end to end against a real server. The codex and gemini presets are written and covered at the plumbing level, but have not been tested against the real binaries — using them means being the first to try them out.

Before every launch, monl run runs a behavioral smoke test against a fresh ephemeral server: every contract route is tested over real HTTP and, if Node.js is available, frontend/index.html is executed in jsdom against this server. Any exception or out-of-contract call blocks the launch (--skip-smoke to override with full awareness).

Quality and verification

python3 -m pytest tests/ -rs --cov=src/monl --cov=src/monl_platform --cov-report=term-missing --cov-fail-under=0
python3 -m coverage report --include='src/monl/*' --fail-under=90
python3 -m coverage report --include='src/monl_platform/*' --fail-under=90

A single run of the whole suite, followed by two gates drawn from the same measurements: that is what CI does (a gate measured against a list of test files would forget those not on the list).

ruff check src tests

monl-compiler does not depend on any AI model and makes no network calls: dialogue, specification, and backend generation are entirely deterministic. custom blocks produce safe empty stubs in sandbox_ai.py, whose business logic is written by hand — no code generation is automated.

Repository structure

Documentation

License

FSL-1.1-ALv2 — Functional Source License, with automatic conversion to Apache-2.0 two years after the publication of each version (LICENSE).

You may use monl-compiler freely, including professionally, modify it, redistribute it, and use it to deliver applications to your clients. The only restriction is competitive use: making it into a commercial product or service that substitutes for monl-compiler. Applications produced from your own specifications belong to you.

Details in French: LICENSE-FAQ.md.

Bug reports and feedback are welcome in the issues.

monl-compiler 1.0.0-rc.1