Product-first design

Most backend frameworks are database-first — you pick a database, then write code that talks to it through an ORM or driver. Some are framework-first — you pick a framework, then bend your application around its conventions. Backend-as-a-serviceproducts are vendor-first — you write code against their proprietary APIs, then live with whatever they expose.

Vadyl is product-first. The unit of truth is your product model: customers, orders, invoices, teams, subscriptions, permissions, workflows, events, actions, agents, and the rules that describe what they mean. Data, APIs, logic, migrations, integrations, observability, operations, and runtime scaling are derived from that model. Infrastructure — databases, caches, CDN, runtime substrates, identity providers, model providers, cloud regions — is substrate behind it.

Above the line / below the line

Vadyl draws a hard line through your backend.

Above the line — your product model — is canonical:

• Entities: the things your product is built around, with fields, relationships, validation, and constraints.
• Policies: who can read, write, share, and act on what.
• Workflows: the long-running product processes and sagas.
• Actions: authored handlers, event consumers, scheduled jobs, edge handlers, webhook handlers, and management handlers.
• Agents: AI participants that read, plan, and act through the same product model as humans.
• Surfaces: typed product projections (REST, GraphQL, gRPC, SDK, MCP, CLI) — generated, never hand-written.

Below the line — infrastructure — is interchangeable:

• Databases (Postgres, MongoDB, MySQL, Redis, Cassandra, Neo4j, …)
• Caches and storage
• CDN and edge runtime
• Identity providers and KMS
• Model providers and inference substrates
• Email / SMS / payment / messaging connectors
• Cloud regions, runtime fabric, and scale targets

Two independent axes of change

Product intent evolves through the canonical lifecycle — branches, commits, sandboxes, proposals, deployments, publications, progressive rollouts, observability. Branching is the substrate for this axis.

Infrastructure evolves through providers and configuration — switching from Postgres to MongoDB on a project, adding a CDN, moving to a different cloud region, changing your auth provider, or choosing a different RuntimeSubstrate for scale and placement. Capability surfaces is the substrate for this axis.

Each axis evolves independently. Adding a Customer field, tightening an Order permission, or changing a billing workflow does not force an infrastructure change. A provider swap does not require a single line of product logic to change.

Why entities aren't the whole product model

Entities are the noun part of the product model — alongside policies, workflows, agents, surfaces, and authored logic. Vadyl is not entity-only. The other concerns are equal participants in the same model: a workflow can be branched and sandboxed exactly like an entity; a policy can be diffed and approved like a schema change; an agent ships under the same publication versioning as a handler.

How product-first differs

• vs database-first. A database-first stack lets you model arbitrary SQL and trusts you to keep migrations safe. Vadyl owns the product model and canonical contract; the database is a substrate the contract compiles down to. Schema changes are typed, classified, and reversible.
• vs framework-first. Frameworks impose conventions on your code (controllers, models, middleware). Vadyl imposes conventions on your product model — entities, policies, workflows, actions, agents, and surfaces — and leaves authored code free of framework syntax.
• vs BaaS. A BaaS owns your data and exposes a proprietary API. Vadyl owns the platform contract; you own your data, your code, and your product model, and the surfaces are compiled from that model.
• vs ORM. An ORM maps objects to a database you chose. Vadyl picks the right database (or lets you pick), then compiles canonical entity operations to it through capability-aware execution.

The canonical promise

If your product model is correct above the line — entities make sense, policies are sound, workflows handle their cases, agents have the right grants, surfaces project what consumers need — then no infrastructure choice below the line breaks correctness. Vadyl preserves product semantics across provider boundaries through capability-aware execution and compensation. You move providers to optimize cost, latency, compliance, or reliability — not because your product logic stopped working.