{"protocol":"clank-doc/1","frameworkVersion":"0.8.0","slug":"blueprints","title":"AI application blueprints","description":"An application blueprint is the reviewable contract between a human request, an AI planner, generated source, and deployment resources.","group":{"id":"agents","title":"Agents and generation"},"url":"https://docs.clank.run/docs/blueprints","source":"docs/blueprints.md","headings":["Commands","Static safety","Contract surface"],"tableOfContents":[{"id":"commands","title":"Commands","level":2},{"id":"static-safety","title":"Static safety","level":2},{"id":"contract-surface","title":"Contract surface","level":2}],"markdown":"# AI application blueprints\n\nAn application blueprint is the reviewable contract between a human request, an AI planner, generated source, and deployment resources.\n\nThe default file is `clank.app.ts`. It must export one data literal:\n\n```ts\nexport default {\n  name: \"Orbit Tasks\",\n  description: \"A live, authenticated task planner.\",\n  auth: {\n    required: true,\n    organizations: true,\n    roles: {\n      owner: {\n        description: \"Workspace administrator.\",\n        permissions: [\"tasks.*\", \"members.*\"],\n      },\n      member: {\n        description: \"Workspace member.\",\n        permissions: [\"tasks.read\", \"tasks.write\"],\n      },\n    },\n  },\n  entities: {\n    tasks: {\n      description: \"Actionable work.\",\n      ownership: \"workspace\",\n      realtime: true,\n      displayField: \"title\",\n      completionField: \"done\",\n      fields: {\n        title: { type: \"string\", min: 1, max: 200 },\n        done: { type: \"boolean\", default: false },\n      },\n    },\n  },\n  routes: [\n    { path: \"/\", view: \"TaskList\", entity: \"tasks\" },\n  ],\n  services: {\n    reminders: {\n      kind: \"jobs\",\n      description: \"Schedule durable reminders.\",\n      required: true,\n    },\n  },\n  deployment: {\n    database: \"sqlite\",\n    scale: \"single\",\n    isolation: \"container\",\n  },\n} satisfies import(\"@clank.run/framework/blueprint\").AppBlueprintInput;\n```\n\n## Commands\n\n```sh\nclank explain\nclank plan\nclank plan --output .clank/reviewed-plan.json\nclank generate .\nclank generate ./new-app --blueprint ./clank.app.ts\nclank generate ./new-app --blueprint ./clank.app.ts --framework=local\n```\n\n`explain` summarizes identity, data, routes, operations, services, and unresolved production requirements.\n\n`plan` normalizes the contract and prints `clank-plan/1`, including every generated path, byte length, SHA-256 checksum, aggregate digest, and warning. Identical blueprints on the same Clank version produce identical plans.\n\n`generate` writes the authenticated full-stack application, human and agent operating guides, and `.clank/plan.json`. It refuses to replace a changed file unless `--force` is supplied. The source blueprint is preserved when generating into its own directory. `--framework=local` makes a generated app install directly from the current Clank checkout without requiring a published registry version.\n\n## Static safety\n\nClank does not import or execute `clank.app.ts`. A dedicated parser accepts an exported JSON-like literal with comments, trailing commas, and an optional `satisfies` or `as const` clause. Function calls, computed properties, template expressions, environment reads, imports with runtime behavior, and arbitrary statements are rejected.\n\nThis means an AI can prepare a TypeScript-assisted contract without gaining implicit local-code execution during review or generation. Generated application source is still code and must pass normal review, authorization, conformance, and deployment controls.\n\n## Contract surface\n\nA blueprint declares:\n\n- entities, field constraints, ownership, indexes, display/completion semantics, and live behavior;\n- relationships and deletion expectations;\n- authentication, organizations, roles, and permissions;\n- routes, views, access requirements, and user-visible actions;\n- immutable SQL migrations;\n- files, images, email, jobs, cron, search, and webhook service requirements; and\n- database, scaling, isolation, health, region, custom-domain, and public environment requirements.\n\nGenerated applications currently include built-in authentication by construction. `auth.required` may be omitted or set to `true`; unauthenticated generation is rejected rather than silently producing a client/backend mismatch.\n\nThe generator creates a deterministic baseline, not domain truth. Payment, legal, medical, tax, retention, or other domain-specific behavior still needs explicit contracts and review.\n\nSee [`examples/blueprint-todo/clank.app.ts`](../examples/blueprint-todo/clank.app.ts) for a Todoist-style specification.\n"}