{
  "markdown": "# BackendGen\n\n**BackendGen is a deterministic backend compiler for AI coding agents.** Give an\nagent a compact, versioned YAML or JSON specification and it can generate a\nstructured, tested backend instead of inventing database models, permissions,\nAPI routes, and migrations from scratch.\n\nIt currently generates **NestJS 11 + Prisma 6 + PostgreSQL** repositories,\nincluding a typed TypeScript client and a small `frontend-contract.json` for\nthe frontend agent to consume. Generated projects have no BackendGen runtime\ndependency.\n\n> **Alpha status:** BackendGen is ready for design-partner trials and local\n> projects. Review generated applications before production use; it has not yet\n> completed independent security review or three design-partner trials.\n\n[npm CLI](https://www.npmjs.com/package/@2hemi/backendgen) ·\n[npm MCP server](https://www.npmjs.com/package/@2hemi/backendgen-mcp) ·\n[Report an issue](https://github.com/SiTouhemi/Backendgen/issues) ·\n[Design-partner program](docs/DESIGN_PARTNERS.md)\n\n## What it is for\n\nBackendGen is useful when an AI agent needs a real backend behind a frontend:\n\n- model entities, relations, filters, sorting, and pagination;\n- add authentication, roles, row ownership, organizations, and tenant isolation;\n- generate reservations, notifications, webhooks, durable jobs, and uploads;\n- preserve a clean boundary between compiler-owned code and application-owned\n  custom code;\n- safely regenerate after a specification changes, with incremental migrations\n  and explicit review gates for destructive changes.\n\nBackendGen is **not** a hosted backend service, deployment platform, or\nfrontend builder. It runs locally and produces code that a developer or coding\nagent can review, customize, test, deploy, and connect to a frontend.\n\n## Requirements\n\n- Node.js 22 or newer\n- npm 10 or newer\n- PostgreSQL only when you want to run a generated project's integration tests\n\n## Try it in five minutes\n\nYou do not need an npm account or this repository to try BackendGen.\n\n```sh\nmkdir backendgen-try\ncd backendgen-try\n\nnpx -y @2hemi/backendgen init backend.yaml --name team-api\nnpx -y @2hemi/backendgen validate backend.yaml\nnpx -y @2hemi/backendgen generate backend.yaml --output ./team-api\n\ncd team-api\nnpm install\nnpm test\n```\n\nThe generated project runs `prisma generate` during installation, so this\nfirst-run path does not require a separate Prisma command. From the parent\ndirectory, use\n`npx -y @2hemi/backendgen test-generated --output ./team-api --install` when an\nagent should perform installation, validation, build, and unit tests through\none bounded compiler command.\n\n`init` creates a valid starter specification. Edit `backend.yaml`, then run\n`validate` and `generate` again. Before regenerating an existing project, use\n`diff` to preview what would change:\n\n```sh\nnpx -y @2hemi/backendgen diff backend.yaml --output ./team-api\n```\n\n## Test a complete SaaS example\n\nThe repository includes working specifications from basic CRUD to a\nfull-featured backend. This multi-tenant task example is a good first test:\n\n```sh\ngit clone https://github.com/SiTouhemi/Backendgen.git\ncd Backendgen\n\nnpx -y @2hemi/backendgen validate examples/saas-tasks/backend.yaml\nnpx -y @2hemi/backendgen generate examples/saas-tasks/backend.yaml --output ./generated/saas-tasks\n\ncd generated/saas-tasks\nnpm install\nnpm test\n```\n\nBrowse every example and what it demonstrates in [examples/README.md](examples/README.md):\n\n| Example | Demonstrates |\n|---|---|\n| [notes API](examples/notes-api/backend.yaml) | CRUD, filtering, pagination, and sorting |\n| [auth notes](examples/auth-notes/backend.yaml) | Accounts, roles, ownership, and authentication |\n| [SaaS tasks](examples/saas-tasks/backend.yaml) | Organizations and enforced tenant isolation |\n| [hotel booking](examples/hotel-booking/backend.yaml) | Reservations, overlap prevention, and notifications |\n| [all features](examples/all-features/backend.yaml) | CRUD, auth, organizations, reservations, notifications, webhooks, jobs, and uploads |\n\n## Use it with an AI coding agent (MCP)\n\nThe MCP package lets an AI agent discover supported backend features, validate\na spec, preview changes, generate a backend, run generated tests, return the\nfrontend handoff contract and customization guidance. It can also explain\ncustomization points. It runs locally over stdio—no BackendGen account or\nnetwork listener is required.\n\nMigration SQL is returned only when the agent explicitly requests it for\nreview; generated source remains omitted from normal responses.\n\nAdd this server to an MCP-capable client, giving it only a directory you trust:\n\n```json\n{\n  \"mcpServers\": {\n    \"backendgen\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@2hemi/backendgen-mcp\"],\n      \"env\": {\n        \"BACKENDGEN_ALLOWED_ROOTS\": \"/absolute/path/to/projects\"\n      }\n    }\n  }\n}\n```\n\nFor Codex, Claude Code, Cursor, ChatGPT desktop, Windows, Lovable Desktop, and\nthe correct v0 handoff, follow the client-specific commands in\n[docs/AI_BUILDERS.md](docs/AI_BUILDERS.md). The complete MCP security and tool\nreference is in [docs/MCP.md](docs/MCP.md).\n\nOnce connected, give your agent a request such as:\n\n> Create a multi-tenant task-management backend. First inspect BackendGen's\n> capabilities and relevant features. Write a spec, validate it, preview the\n> generation, generate it inside this project, and run the generated tests.\n> Keep custom behavior in the documented customization points.\n\n## What is generated\n\nFor a valid specification, BackendGen produces a standalone repository with:\n\n- a NestJS API, Prisma schema, PostgreSQL migrations, OpenAPI setup, and tests;\n- generated endpoints and permission rules derived from the normalized spec;\n- `src/generated/` for compiler-owned code and `src/custom/` for code you own;\n- a `.backendgen/manifest.json` that records ownership and hashes;\n- `frontend-contract.json` and a typed TypeScript client for frontend agents.\n\nOn regeneration, BackendGen preserves custom files, refuses to overwrite edited\ngenerated files unless you explicitly use `--force`, and requires explicit\nreview for destructive or data-dependent schema changes. Read\n[docs/MIGRATIONS.md](docs/MIGRATIONS.md) before changing a live schema.\n\n## Verification and limits\n\nThe repository's CI verifies compiler, CLI, MCP, security-contract fuzzing,\npackage-installation, and generated-project scenarios. Generated projects are\nalso built and tested against PostgreSQL in the release test matrix. See the\n[local verification record](docs/LOCAL_VERIFICATION.md) and\n[security contract](docs/FUZZ_SECURITY_CONTRACT.md) for the exact evidence.\n\nThat evidence does **not** prove that every generated application is safe for\nproduction. You remain responsible for reviewing the specification, generated\ncode, secrets, infrastructure, and deployment configuration.\n\nCurrent boundaries:\n\n- one production target: NestJS + Prisma + PostgreSQL;\n- FastAPI and other backend targets are intentionally out of scope;\n- no hosted BackendGen SaaS or direct browser-v0 MCP integration yet;\n- do not make token-savings claims until the paired benchmark has real results.\n\n## Documentation\n\n| If you need to… | Read |\n|---|---|\n| Write a specification | [Specification reference](docs/SPECIFICATION.md) |\n| Understand each supported feature | [Feature packs](docs/FEATURE_PACKS.md) |\n| Connect an AI agent or MCP client | [AI builder integration](docs/AI_BUILDERS.md) |\n| Customize a generated project | [Customization guide](docs/CUSTOMIZATION.md) |\n| Safely regenerate or change a schema | [Migrations guide](docs/MIGRATIONS.md) |\n| Run tests locally | [Local testing](docs/LOCAL_TESTING.md) |\n| Understand security boundaries | [Threat model](docs/THREAT_MODEL.md) |\n| Contribute | [Contributing](CONTRIBUTING.md) |\n\n## Feedback and support\n\nWe are looking for developers and AI builders who will test BackendGen on a\nreal, non-production project. Please open an issue with:\n\n1. what you were trying to build;\n2. your sanitized `backend.yaml` specification;\n3. the command or MCP client you used;\n4. what worked, what was confusing, and what you expected instead.\n\nNever include API keys, `.env` files, private customer code, or production\ndatabase data. For security vulnerabilities, follow [SECURITY.md](SECURITY.md)\ninstead of opening a public issue. Full support details are in [SUPPORT.md](SUPPORT.md).\n\n## Development\n\nTo work on BackendGen itself:\n\n```sh\nnpm ci\nnpm test\nnpm run test:fuzz:ci\nnpm run test:e2e\nnpm run test:distribution\n```\n\nMaintainers preparing a release can run the same non-publishing gate through\n`npm run verify:release`. PostgreSQL-backed execution remains the separate\n`npm run verify:local:postgres` workflow described in\n[local testing](docs/LOCAL_TESTING.md).\n\nBackendGen is licensed under [Apache-2.0](LICENSE). Generated projects belong\nto their users.\n",
  "bytes": 8861,
  "sha": "f6df755ad27543a511fa349dcf987983f3a1308f7454211d484c914f42a2103c",
  "repo_slug": "sitouhemi/backendgen",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sitouhemi_backendgen_a209dfee/readme"
}