> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shodai.network/llms.txt
> Use this file to discover all available pages before exploring further.
# Architecture overview
> Orient around agreement definitions, deployed agreement instances, onchain execution, SDKs, and supporting API layers.
export const SystemArchitectureDiagram = () =>
Derived from execution.states and execution.transitions
{stateIds.length} states
;
};
For the complete documentation index, see [llms.txt](https://docs.shodai.network/llms.txt).
## Architecture at a glance
Shodai turns agreements into living, verifiable infrastructure: programmable commitments with explicit state, signatures, transitions, and history.
The agreement definition is the center of the system. It is produced from the data standard, rendered as human-readable agreement content, and deployed to the onchain engine to create a deployed agreement instance. Outside the protocol core, SDKs, APIs, and applications use definitions and instances to create user experiences around agreement creation, submission, inspection, and monitoring.
| Layer | Role |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Data standard | Defines the common agreement language and schema semantics. |
| Agreement definition | Describes prose, variables, participant-backed address variables, inputs, states, transitions, actions, and references. |
| Deployed agreement instance | Records live initialization values, participant address mappings, current state, accepted inputs, emitted events, and transition history. |
| Onchain execution engine | Deploys agreement instances and enforces valid inputs, issuers, states, transitions, and recorded history. |
| SDK and client libraries | Help applications validate, prepare, sign, deploy, submit inputs, and read agreement state. |
| Supporting API / application layer | Creates, deploys, indexes, monitors, notifies, and integrates agreements into products. |
| Pluggable modules | Add specialized capabilities such as payment integrations, roles, attestations, dispute flows, and domain-specific execution. |
## Native vs composed behavior
Shodai's core engine focuses on agreement structure, authorization, valid inputs, state progression, and verifiable history.
Domain-specific behavior such as escrow, payment execution, dispute resolution, compliance checks, notifications, or private-data verification can be composed through modular actions, external modules, or application-layer integrations.
This keeps the core agreement model generic while allowing richer behavior to be added around it.
## Data standard in practice
The data standard gives every agreement the same shape: metadata, typed variables, human-readable content, expected inputs, lifecycle states, and transitions. In a Memorandum of Understanding template, the diagram below is derived from the `execution` section of the agreement definition.
The following visual example shows an MOU agreement definition and a derived state machine. The execution path is: PENDING\_PARTY\_A\_SIGNATURE --partyAData--> PENDING\_PARTY\_B\_SIGNATURE --partyBData--> PENDING\_ACCEPTANCE; PENDING\_ACCEPTANCE --accepted--> ACCEPTED; PENDING\_ACCEPTANCE --rejected--> REJECTED.
## Definition vs instance
An agreement definition describes the agreement's terms and valid execution path. It is authored from the agreement data standard and can be rendered, validated, inspected, and prepared for deployment.
A deployed agreement instance is the runtime form of that definition. It has live initialization values, participant address mappings, current state, accepted inputs, emitted events, and execution history.
## How the parts fit together
1. Author an agreement definition from the [agreement data standard](/system-architecture/data-standard).
2. Render the same definition for human review and application workflows.
3. Use SDKs or the Agreements API to validate, prepare, sign, and deploy the agreement.
4. Deploy the definition to the [onchain execution engine](/system-architecture/on-chain), creating a deployed agreement instance.
5. Participants submit defined inputs to the deployed instance as the agreement progresses.
6. The engine validates issuer constraints, schemas, states, and transitions, then records state and history.
7. Applications can read deployed instance state directly or use the [Agreements API](/system-architecture/putting-it-together) for indexing, monitoring, notifications, and product integrations.
## API-assisted and direct onchain operation
The documented happy path uses the Shodai API and SDK to simplify validation, signing, deployment, indexing, and application integration.
The onchain execution layer is the verifiable substrate. Developers who need stronger trust-minimization or resilience can inspect the relevant contracts, typed data, chain configuration, addresses, and events directly in [`CNSLabs/agreements-protocol-evm`](https://github.com/CNSLabs/agreements-protocol-evm).
The API-assisted path and the direct onchain path are complementary:
* the API helps applications deploy and operate agreements more easily
* the onchain engine provides the verifiable agreement runtime
* EIP-712 typed data connects user authorization to onchain execution
## Protocol boundary
The protocol is defined by the agreement data standard and agreement definitions. The EVM engine is the first concrete execution engine for those semantics.
The API does not define what an agreement means. It helps applications work with agreement definitions and deployed agreement instances by creating, deploying, indexing, monitoring, notifying, and integrating agreements into products.
| Boundary | Includes |
| ---------------------- | --------------------------------------------------------------------------------------------------------- |
| Protocol semantics | Agreement data standard and agreement definition. |
| Runtime implementation | Onchain execution engine that interprets agreement definitions and enforces deployed agreement instances. |
| Developer tooling | SDKs and client libraries for validation, signing, deployment, input submission, and reads. |
| Application layer | API services, indexing, monitoring, notifications, integrations, and user experiences. |
## What becomes verifiable
Agreements Protocol makes agreement progression constrained, inspectable, and verifiable. Once an agreement definition is deployed, participants and agents can inspect the current state, accepted inputs, and transition history without relying only on an application, API, or private database.
| Verifiable property | What it means |
| ------------------------- | ---------------------------------------------------------------------------------- |
| Constrained inputs | Only defined inputs can move the agreement. |
| Authorized issuers | Inputs can be bound to specific parties or addresses. |
| Deterministic progression | Valid inputs produce defined state transitions. |
| Auditable sequence | Accepted inputs and state changes are preserved. |
| Inspectable state | Current state and history can be read by applications, parties, and agents. |
| Reduced ambiguity | The agreement's operational path is explicit, not hidden in prose or private code. |
## What this enables
As a developer, you get a reusable way to model agreements, deterministic multi-party execution, verifiable outcomes across participants, and a consistent interface across different agreement types.
That matters because the agreement definition becomes the shared object that humans read, applications render, agents inspect, and execution engines enforce.
## Choose your path
Understand the JSON structure that describes agreement prose, variables, inputs, states, transitions, and valid execution paths.
See how agreement definitions become verifiable onchain agreement instances.
Understand why the API is the product integration layer around agreement creation, deployment, monitoring, and participant workflows.
Learn which repositories own the data standard, EVM execution engine, and TypeScript API client.
## Summary
The data standard defines the common language. The agreement definition describes the prose, variables, inputs, states, transitions, and valid execution path. A deployed agreement instance records current state, accepted inputs, events, and transition history. SDKs, APIs, and application workflows make it easier to create, deploy, monitor, and integrate agreements into real products.
The result is a protocol for agreement progression: not just what parties accepted, but how the agreement can move, who can move it, and how that movement can be inspected.