Concept

What is an AppSpec?

The AppSpec is the idea Chromoly is built around: your software, defined as structured data instead of code. Everything else - deterministic generation, safe changes, portability - follows from this one decision. Here's the full picture.

The definition

An AppSpec is the complete, structured definition of a software system: its entities and their fields and relations, its workflows with triggers and steps (including AI steps and approval gates), its screens, and its rules. It is stored as versioned data, and a deterministic compiler turns it into the running application - same AppSpec, same system, every time.

When you describe a tool to Chromoly in plain language, the AI's entire job is producing this artifact. The AppSpec is what gets reviewed, what gets compiled, what gets diffed when you request a change, and what you export if you ever leave.

What it looks like

An illustrative excerpt - one entity and one workflow from a CRM's AppSpec:

{
  "entity": "Lead",
  "fields": [
    { "name": "company",     "type": "text",     "required": true },
    { "name": "contact",     "type": "text" },
    { "name": "source",      "type": "select",   "options": ["Website form", "Email", "Referral"] },
    { "name": "stage",       "type": "select",   "options": ["New", "Qualified", "Proposal", "Won", "Lost"] },
    { "name": "score",       "type": "number",   "range": [0, 100] },
    { "name": "owner",       "type": "relation", "to": "TeamMember" }
  ],
  "workflow": {
    "name": "Score and route new leads",
    "trigger": { "type": "record_created", "entity": "Lead" },
    "steps": [
      { "type": "ai_step", "action": "score",
        "against": "ideal customer profile",
        "writes": "score",
        "on_low_confidence": "review_queue" },
      { "type": "condition", "if": "score >= 70",
        "then": [ { "type": "slack_message", "to": "#sales", "template": "hot_lead_alert" } ] },
      { "type": "wait", "days": 3, "until": "record_updated" },
      { "type": "email", "to": "owner", "template": "untouched_lead_reminder" }
    ]
  }
}

Notice what's readable here without any programming knowledge: leads have a score from 0 to 100, hot leads alert Slack, untouched leads trigger a reminder after 3 days, and low-confidence AI scores go to a human review queue instead of acting. That reviewability is the point - the AI's output is something you can verify, not thousands of lines nobody reads.

Why define software as data?

Versus prompts: a prompt is a wish; the AppSpec is a contract. Prompts are ambiguous by nature - that's fine for input, fatal for a system of record. The AppSpec makes every assumption explicit and inspectable before anything runs.

Versus source code: code describes how a system executes. The AppSpec describes what the system is. That difference unlocks everything:

• Diffable - a change request becomes a precise diff between two versions, not a patch to opaque code.
• Dependency-mapped - because the structure is data, the platform derives the full map of what uses what, and computes the blast radius of any change automatically.
• Reproducible - the compiler regenerates the identical system from the same AppSpec. Rebuilds can't silently change behavior.
• Portable - the definition exports as structured JSON. Your system's design is never locked away.

The AppSpec lifecycle

1. Generated - AI interprets your plain-language description (and any attached spreadsheet) into the first AppSpec version.
2. Compiled - the deterministic build engine produces the database schema, API, screens, and workflow definitions from it.
3. Versioned - every approved change creates a new version. The deploy history is the version history.
4. Diffed - each change request becomes a proposed diff, checked against the dependency manifest, previewed, and approved before production.
5. Rolled back, if needed - restoring a previous version restores the previous system definition. Your records stay put.

The full pipeline around it - understanding, compiler, runtime - is documented on the architecture page.

Questions

What is an AppSpec in one sentence?

An AppSpec is the complete, structured definition of a software system - its entities, fields, relations, workflows, AI steps, screens, and rules - stored as versioned data that a deterministic compiler turns into the running application.

How is an AppSpec different from a prompt?

A prompt is the input; the AppSpec is the contract. Your plain-language description gets interpreted by AI into the AppSpec, which you can read and verify before anything is built. The prompt can be vague; the AppSpec never is - every entity, workflow, and rule is explicit.

How is an AppSpec different from source code?

Source code describes how a system executes; an AppSpec describes what the system is. Code can only be safely changed by someone who reads code. An AppSpec is structured data: a machine can diff two versions, compute what a change affects, and regenerate the system identically - and a founder can read it without knowing any programming language.

Can I edit the AppSpec directly?

You change it by describing changes in plain language - Chromoly turns your request into a diff against the AppSpec, shows the blast radius, and applies it through preview. You can always inspect the current definition, and the full AppSpec exports at any time.

What format does an AppSpec export in?

Structured JSON containing the complete system definition. Together with your records (CSV/JSON export), it means an Chromoly system is portable by design - the definition of what you built is never locked away.