Documentation / The project

Vision and goals

{% raw %}

Why Crabster?🔗

A "batteries included" application generator turns a domain model into a complete application — persistence, API, security, tests, containerization, CI — instead of a blank page or a bare-bones skeleton. Several ecosystems have one; Rust does not.

Rust developers who want to start a production web service today have to manually assemble: web framework, ORM, migrations, authentication, validation, OpenAPI documentation, observability, containerization — repetitive, error-prone work that diverges from project to project.

Crabster aims to fill that gap: a generator that produces idiomatic, compilable, tested, production-ready Rust code from a high-level description of the business domain.

Guiding principles🔗

1. Generated code is owned code. Generated code fully belongs to the developer: no runtime dependency on a proprietary "magic" framework. The output is standard, readable, modifiable Rust that does not need Crabster to compile or run once generated.
2. Idiomatic first. We do not mechanically copy Java/Spring patterns (annotations, reflection, runtime dependency injection). We pick the Rust patterns that fit: traits, procedural macros (sparingly), explicit composition, Result-based error handling.
3. Convention over configuration, without black magic. Sensible, documented defaults, with customization available through templates (the blueprint mechanism, see Technical architecture).
4. Production-ready on generation. A generated project must start, have passing tests, a working Dockerfile, a CI pipeline, and health checks — not a half-finished skeleton.
5. Evolvable and incremental. Crabster must let you add or change records on an existing project without full regeneration, via a merge mechanism (see Phase 11, in V2).
6. API-first, frontend deferred. V1 focuses exclusively on backend generation (REST API + persistence + security + docs). This is a deliberate choice: ship a solid, well-tested generator core before opening the frontend front, rather than spreading effort thin. See ADR-0001 below.
7. Community and extensibility. Long-term value comes from the blueprint ecosystem (NoSQL support, Kubernetes, specific cloud providers…), not just the core.

What Crabster is not🔗

• Not a runtime framework. Crabster is a generation-time tool: once code is generated, the dependency on crabster disappears (except possibly a minimal shared utility crate, to be evaluated).
• Not (in V1) a frontend generator. No Angular/React/Vue nor Rust/WASM generation in V1. The generated API is documented via OpenAPI, which allows plugging in any frontend, or generating a client from the OpenAPI contract with third-party tools.
• Not a low-code platform. Crabster does not replace writing business logic; it generates infrastructure and baseline CRUD, and the developer writes the domain-specific logic.

Target audience🔗

• Rust backend teams starting a new microservice or API who want to avoid rebuilding standard infrastructure every time.
• Teams coming from ecosystems where such a tool already exists (Java, .NET, Node), looking for the same mental model in Rust: model the domain, then generate.
• Solo developers / small teams who want a solid, opinionated starting point rather than a paralyzing choice among dozens of Rust frameworks.

Measurable goals (V1)🔗

• From a CDL file describing N records and their references, generate a Rust project that compiles without manual intervention.
• The generated project exposes a full CRUD REST API (pagination, filtering, sorting) for each record, documented in OpenAPI 3.
• The generated project includes: JWT authentication, versioned database migrations, runnable integration tests (cargo test), a working Dockerfile and CI pipeline (GitHub Actions).
• Time between crabster new and a locally responding API: under 5 minutes, excluding initial Cargo ecosystem compile time.

ADR-0001 — API-only in V1🔗

• Status: accepted (2026-09-03).
• Context: covering backend and frontend at once means maintaining several JS frameworks in parallel, through their breaking-change cycles. For Crabster, two frontend options exist (reuse React/Vue/Angular, or generate Rust/WASM via Leptos/Yew), each with a significant investment and maintenance cost.
• Decision: Crabster V1 generates no frontend at all. It focuses on a robust API-only backend, with high-quality OpenAPI documentation enabling any client to be plugged in.
• Consequences: the frontend effort is explicitly deferred to Phase 16 of V2; the choice between "reuse the JS ecosystem" and "native Rust/WASM frontend" will be settled at that point, informed by learnings from the API-only V1. {% endraw %}