How Vadyl actually works.
A product-native backend architecture: canonical model first, capability graph underneath, RuntimeSubstrate realization for scaling and placement, and every protocol and developer surface projected from the same contract.
One descriptor model across 7 families
Contract fan-out into APIs, SDKs, CLI, MCP, UI
Each bounded, observable, and scalable
Every channel from the same contract
Nine invariants that do not bend.
Vadyl's architecture is enforced through descriptors, graph compilation, capability gates, generated projections, and runtime policy checks.
Product-first
The product model is canonical. Entities, workflows, policies, events, connectors, agents, APIs, observability, deployments, and operations derive from the same source of truth.
Unified Capability Surface
37 surface kinds across 7 families. One router, one registry, one descriptor, and one capability contract for native, declarative, and Wasm-authored implementations.
Project-scope parity
The same capability planes Vadyl uses internally can be authored, published, installed, governed, observed, and exposed by projects through UCSA, PCG, exposure bindings, SDK, CLI, MCP, and dashboard projections.
Plane Capability Graph
A typed, content-hashed graph compiled from domain facets. Every plane resolves authority, dependency, projection, and invalidation through the graph.
Seven execution surfaces
CoreHandler, DurableWorkflow, EventConsumer, ScheduledJob, WebhookHandler, EdgeHandler, ManagementHandler. Runtime Fabric can scale, expose, and resource each surface independently.
Branchable everything
Schema, code, connections, federation, scheduling, agents, policies, projections, and releases participate in one branch DAG with review, merge, rollback, and sandbox isolation.
Fail-closed by default
Capability mismatches, missing grants, invalid signatures, unresolved envelopes, quota violations, policy denials, and stale bindings produce explicit failures, not permissive fallbacks.
Observable and explainable
Observability records what happened. Explainability projects why it happened. Both are first-class planes sourced from canonical authorities.
AI as a peer plane
Agents use typed plan IR, immutable memory, MCP projection, branch context, approvals, policies, and the same product model used by every other runtime surface.
From product model to running backend
Vadyl starts with the product. Customers, orders, subscriptions, workflows, permissions, integrations, events, teams, agents, sandboxes, and deployments are authored as typed product state. The product model is not a diagram beside the backend. It is the backend's canonical input.
The backend is derived. REST routes, GraphQL fields, gRPC services, OpenAPI documents, SDKs, CLI commands, MCP tools, webhooks, realtime events, dashboards, analytics, schemas, migrations, policies, validation, observability, and explainability are projections of the same contract.
Infrastructure is execution detail. Databases, caches, queues, identity providers, CDN, object storage, runtime fabric, model providers, edge hosts, and connector substrates can move independently of product semantics. Vadyl absorbs the provider differences through capability descriptors and host bridges.
Capabilities are the boundary primitive. Each provider and authored module declares what it can do. Vadyl chooses native delegation, runtime supplementation, orchestration, or compensation from capabilities. Product code branches on intent, not vendors.
Projects can become providers. A project can publish the same capability shapes Vadyl uses: entities, operations, CLI commands, workflows, agent skills, analytics, events, webhooks, runtime handlers, auth schemes, and substrate policies. Consumers install them through versioned manifests, narrowed grants, usage evidence, and PCG edges.
Agents need an operating substrate. Prompts, memory, and tool calls can suggest what an agent should try, but they do not give it a reliable map of what exists, what is allowed, what depends on what, what needs approval, what can be rolled back, or what actually happened after execution. Vadyl gives agents that map through canonical graphs, capability descriptors, typed plans, governance envelopes, publications, rollouts, observability, and explainability. The agent becomes a governed actor inside the backend's own plane, not an assistant orbiting it through brittle tools.
One contract, every developer surface.
The final platform exposes a broad surface, but the architecture keeps the meaning centralized.
1. Authoring
Entities, schemas, policies, source assets, connector manifests, schedules, agents, automations, and runtime settings are authored as typed product state.
2. Facet contribution
Domain contributors emit projection facets: persistence, validation, REST, OpenAPI, GraphQL, gRPC, SDK, CLI, MCP, webhooks, realtime, observability, explainability, and operational controls.
3. Graph compilation
The Plane Capability Graph binds facets, capabilities, grants, dependencies, limits, routes, schema versions, runtime hosts, and invalidation edges into a typed graph.
4. Exposure binding
Operation descriptors fan out into stable external surfaces: REST controllers, Swagger/OpenAPI, GraphQL schema, gRPC services, SDK namespaces, CLI commands, MCP tools, dashboard actions, and webhooks.
5. Runtime enforcement
Execution surfaces resolve branch context, capability grants, auth, quota, scaling policy, runtime topology, idempotency, observability correlation, and compensating actions before performing work.
Resource-shaped JSON routes compiled from entity, platform, and operation contracts.
OpenAPI 3.1 projection of every REST operation, schema, auth scheme, response set, and error envelope.
Compiled SDL, query parser, executor, mutations, and subscriptions aligned with REST and SDK operations.
Proto projection and request handler for unary and streaming canonical operations.
WebSocket and SSE subscriptions over canonical change events. Events carry field names only.
Outbound signed deliveries plus inbound signed receivers, receipts, retry, replay, rotation, and diagnostics.
Event exposure bindings for canonical event producers and consumers. Entity mutation events flow through the outbox, not through private publish paths.
Model Context Protocol JSON-RPC transport. Tools dispatch through IApiOperationDispatcher.
Typed language clients generated from the same exposure binding and contract projection facets.
Descriptor-driven CLI. Bootstrap commands ship locally; all platform commands come from the Cli facet.
Dashboard actions are protocol bindings over the same canonical operations. The dashboard has no private mutation authority.
37 capability surfaces across 7 families.
The Unified Capability Surface Architecture keeps APIs, operations, authoring, runtime, governance, and AI extensions under one descriptor model.
Substrate
9 surfacesFoundational provider-facing substrates for data, runtime, delivery, storage, cache, models, and secrets. Provider SDKs stay behind the capability boundary while project intent declares scale, resources, ingress, and routing canonically.
Projection
6 surfacesExternal projections of the canonical contract graph: wire protocols, SDKs, CLI, MCP, and UI.
Operational
12 surfacesRuntime traffic planes and durable operational records.
Governance
4 surfacesAuthority planes that shape every other decision.
Execution
2 surfacesAuthored runtime and sandbox execution envelopes.
Cross-cutting
2 surfacesDerived planes every other family contributes to and consumes.
Execution surfaces, coding workspace, connectors, and fabric.
Custom code, declarative connectors, authored Wasm, and generated protocol handlers all run through bounded execution surfaces.
Execution surfaces
CoreHandler
Synchronous authored logic with host-owned transaction participation.
DurableWorkflow
Journaled workflow with worker-executed steps, signals, compensation, and replay.
EventConsumer
Publication-aware event consumer with outbox-backed delivery and at-least-once semantics.
ScheduledJob
Cron, interval, or one-shot scheduled job body under scheduler kernel authority.
WebhookHandler
Handler invoked after signature verification, idempotency receipt, and receiver policy checks.
EdgeHandler
Reduced-authority low-latency stateless handler with build-time and runtime import gates.
ManagementHandler
Privileged authored surface for schema, branching, publication, and platform mutation authority.
Coding environment
Workspace IDE
Browser-native file tree, Monaco projection, extraLibs from ContractProjection, run/test/deploy actions.
Source assets
Folders, files, modules, blobs, content-addressed storage, branchable metadata.
Runtime SDK
Language-neutral bridge projected into TypeScript first, then Python, Go, Rust, C#, and future languages.
Build pipeline
Language adapter, diagnostics, unit artifact builder, signatures, publication finalization, rollback.
Local development
Dev descriptors, local worker, CLI parity, sandbox publish/invoke, contract projection invalidation.
Custom connectors
WIT world, Wasm component, host imports, conformance, memory, publication, binding.
Testing
Unit tests, live tests, sandbox tests, runtime invocation E2E, contract drift tests.
Developer observability
Build logs, invocation traces, bridge errors, source maps, operational trails, explainers.
Runtime fabric vocabulary
Project topology distinguishes authored execution, API ingress, realtime gateway, substrates, platform-owned operators, scale targets, named groups, resource policy, and runtime origins.
10 project execution surface kinds
8 runtime substrate kinds
24 platform operator kinds
Connector model
Connectors are first-class capability providers. Each connector is defined by a manifest, contracts, implementation source, WIT host imports, conformance suites, binding policy, observability streams, secret scopes, and invocation envelopes.
Built-in: platform-owned providers with native capabilities.
Declarative: manifest and policy driven connectors.
Authored Wasm: sandboxed implementations with explicit host imports.
81 controller surfaces, 640 mapped endpoints.
The website reference now mirrors the backend controller breadth and links each family back to the complete surface atlas.
/api/Branch64 endpointsAnalyticsCatalog, query, models, metrics, perspectives, reports, dashboards, materializations, lineage./api/Analytics45 endpointsRuntimeFabricProject and platform fabric topology, scaling, resources, ingress, realization, health, binding, deployment plan/apply/reconcile/rollback/drain./api/RuntimeFabric and /api/PlatformRuntimeFabric35 endpointsSchemaEntity schema management, preview, diff, snapshots, migration history, hydrate, metadata, batch, validation, journal, migration apply/rollback./api/Schema22 endpointsAutomationDefinitions, compiler, runs, approvals, attempts, signals, compensation./api/Automation18 endpointsDistributionDistribution bindings, policy, asset policies, realization, delivery, invalidation, replica policies, topology./api/Distribution17 endpointsDynamicEntityTestDynamic entity integration diagnostics for create/delete/update, table and column checks, AST query/mutation, and cleanup./api/DynamicEntityTest17 endpointsEntityDynamic entity CRUD/query/count/exists/alternate-key/batch/restore operations./api/Entity16 endpointsWhat stays true as the platform grows
Projection facets
The complete reference documents 26 canonical facets, including persistence, validation, policy, lifecycle, operations, REST, OpenAPI, GraphQL, gRPC, SDK, CLI, MCP, webhooks, realtime, analytics, observability, explainability, audit, quotas, and search.
Open the full projection atlasRead the complete platform reference.
Every protocol, operation family, error envelope, auth mode, SDK namespace, CLI command model, MCP tool, webhook, connector, and coding surface is documented from the same architectural map.