Application Modeling
The buildable implementation, in layers. The domain layer models the business — aggregates, value objects, invariants, events. The application layer acts on it — commands, queries, sagas, subscriptions, policies. (The presentation and infrastructure layers follow.) Every example is a real construct from the Chowk marketplace.
Domain layer
- Aggregates & entitiesAn entity is a persisted thing your business keeps — a product, an order, a shipment. Every entity in Vishwakarma is an aggregate root: an identity-bearing object that owns a consistency boundary. You…
- Identity & fieldsEvery entity needs an identity and a set of fields. Identity is a field carrying the pk flag; fields are a name, a type, and a small closed set of modifiers. The modifiers are declarative — they…
- Value objectsSome domain concepts have no identity of their own. A price of ₹500 is the same as any other ₹500 — you compare it by its contents, not by a key. Vishwakarma calls these value objects, declared with…
- EnumerationsAn enum is a closed set of named states — an order's lifecycle, a product's status, a currency. You list the real states; the platform handles the wire encoding, the database type, and a safety rule…
- Field specsA spec is a named, reusable validation rule for a single field or value — a shape a value must satisfy. You write the rule once, give it a typed error, and attach it wherever that shape is needed with…
- InvariantsAn invariant is a consistency rule that must always hold for an aggregate — reserved stock never exceeds available stock, a line is only added while its order is open. You declare the rule once, name…
- Domain eventsAn event is a fact an aggregate emits when something happens to it — an order was placed, an order was paid. Events are how one part of the system announces a change without knowing who reacts to it:…
- Sub-domains & isolationA model is divided into sub-domains — the bounded contexts your domain splits into — and each aggregate declares how its rows are isolated. Isolation is where single-tenant and multi-tenant…
Application layer
- The application layerThe domain model gives you the nouns and the facts — aggregates, value objects, the events they emit. The application layer gives you the verbs: the operations a caller actually invokes to act on that…
- CommandsA command is a write: it mutates exactly one aggregate. Validate the caller's inputs, apply the change, persist the row — that is the whole shape of a command. It names the aggregate it acts on and…
- QueriesA query is a read: it returns data and never mutates anything. Where a command names the aggregate it writes, a query names the entity it returns and the method it reads by — either a single record…
- Use cases & sagasA command mutates exactly one aggregate. But some business actions must change several aggregates together, atomically — all of them or none. That is a usecase: a short saga expressed as a state…
- SubscriptionsA subscription is an event reaction: it listens for a domain event and, when one arrives, dispatches a command. Where a usecase orchestrates several writes synchronously in one transaction, a…
- SchedulesA schedule is work triggered by time rather than by anybody acting. Declaring it in the model rather than as a cron entry in a deployment manifest is the whole point: a cron entry is the same job with…
- GatewaysA gateway is egress: a declared HTTP call to something outside your application. You state the address, the shapes, the authentication, the timeout and the retry policy, and the client is generated.…
- Service virtualizationA gateway calls something outside your application. Service virtualization generates a stand-in for it, so the whole flow runs with nothing installed and no credentials.
- PoliciesA policy gates who may run a command or query. Where a spec shapes a value and an invariant keeps an aggregate consistent, a policy answers a different question: is this caller allowed to perform this…
Presentation layer
Infrastructure layer
- The project manifestEvery layer so far describes the application. The infrastructure layer describes what the application is built and run against — and it lives in one file: project.vishwakarma, the project manifest. It…
- Plugin slots & the process treeBeyond the database, an application plugs into runtime substrate — an event bus, a cache, an observability pipeline. The manifest wires each through a plugin slot: name the plugin and its connection,…
The ORM: Chitragupt
- Declarative migrationsChitragupt is the ORM and migration engine — the orm chitragupt line in the project manifest selects it. Its defining idea is that you never write a migration. You describe the schema you want —…
- Repositories: ports & adaptersChitragupt does more than manage the schema — it generates the persistence code your application runs on, and it generates it in a ports-and-adapters (hexagonal) shape. The result: your domain and…
- The repository at runtimeChitragupt is a migration engine and a runtime ORM. The generated repository adapter isn't a thin SQL wrapper — it carries the behaviors that make persistence correct: the transaction boundary, tenant…
- Row-Level Security & rolesCreating tables is only half of persistence; the other half is making sure a caller can only ever touch the rows they're allowed to. Chitragupt emits that enforcement in the database itself — as…
- The migration workflowChitragupt is a CLI, and its subcommands are the lifecycle of a schema — from seeing what would change, to applying it, to auditing what's been applied. Its own summary: