# Concepts [#concepts]

Aventara has four ideas: contracts and layers, Resources and operations, results and typing, and the contract hash.

```text
 schema.prisma + aventara.config.ts
              │  compile
              ▼
   core ─► application      client ─► GET /api/_contract ─► avclient generate ─► typed client
              (server only)  (the only layer served)
```

## Contracts and layers [#contracts-and-layers]

A contract is passive data: which Resources exist, which fields can be read, filtered, ordered or written, and which operations are available. It holds no code, so it can be serialized, hashed and versioned. Aventara compiles four from the same schema:

| Layer       | Used for                                                                                                     | Served over HTTP                            |
| ----------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------- |
| Core        | The baseline everything else starts from.                                                                    | No                                          |
| Application | Your trusted server-side code (`framework.application.*`).                                                   | No                                          |
| Client      | Remote callers: the HTTP protocol and the generated frontend client.                                         | Yes, at `GET <api>/_contract`               |
| Agent       | AI agents, through an MCP server ([the agent layer](/framework/docs/configuration#the-agent-layer-and-mcp)). | No: the MCP server builds its tools from it |

The root of your configuration is the core layer; `application` and `client` are overlays on it that can hide more for their own callers, never less. What each layer exposes is set with `exposed` and `exemptions` ([Exposure](/framework/docs/exposure)). A field hidden from the client layer is absent from the generated client's types. Details: [Contract layers](/framework/docs/contract-layers).

## Resources and operations [#resources-and-operations]

A Resource is one Prisma model, keyed by its name (`User`, `Post`). Every Resource offers operations from five families, each with variants:

| Family   | Variants                                                         |
| -------- | ---------------------------------------------------------------- |
| `find`   | `first`, `unique`, `many`, `count`                               |
| `create` | `one`, `many`, `count`                                           |
| `update` | `first`, `unique`, `many`, `count`                               |
| `delete` | `first`, `unique`, `count` (no `many` with the Prisma 7 adapter) |
| `upsert` | `unique`                                                         |

Their meaning is fixed by the protocol; configuration can only switch them off, or run your own code around them ([Pipelines](/framework/docs/pipelines)). Each variant, with an example, is in [Resources and operations](/framework/docs/resources-and-operations).

## Results and typing [#results-and-typing]

Every operation answers one envelope, `{ data, code, cause }`, on the wire. The generated client and your server-side calls (`framework.application`, `framework.client`, `framework.transaction`) resolve to `data` and throw a typed error for every failure; a `first` miss is `null`, a `count` is a number, and results are `readonly`. The type of a result follows your `select` exactly. Details: [Results and typing](/framework/docs/results-and-typing).

```json
{ "data": { "id": 1, "email": "ada@example.com" }, "code": "A1002", "cause": null }
```

Branch on `code`, never on `cause.message`. The codes are listed in the [HTTP protocol](/framework/docs/http-protocol#codes).

## The contract hash [#the-contract-hash]

The client contract has a hash over everything it advertises, served as the `ETag` of `/_contract` and sent by the generated client on every request. If the server's contract has changed, the request is refused with `A2005` (`CONTRACT_MISMATCH`) and the client throws `AvContractMismatchError`:

```text
Generated client contract does not match the server. Regenerate the client.
```

Details and the regenerate workflow: [Contract hash](/framework/docs/contract-hash).

## Where to go next [#where-to-go-next]

| To learn                               | Read                                                                 |
| -------------------------------------- | -------------------------------------------------------------------- |
| What each layer sees                   | [Contract layers](/framework/docs/contract-layers)                   |
| Hiding fields and operations per layer | [Exposure](/framework/docs/exposure)                                 |
| Every operation, with an example       | [Resources and operations](/framework/docs/resources-and-operations) |
| How results are typed                  | [Results and typing](/framework/docs/results-and-typing)             |
| Identity, ETag and stale clients       | [Contract hash](/framework/docs/contract-hash)                       |
| Changing what each layer exposes       | [Configuration](/framework/docs/configuration)                       |
| The query language                     | [Querying](/framework/docs/querying)                                 |

See also: [Exposure](/framework/docs/exposure), [Exposing and hiding fields](/framework/docs/exposing-and-hiding-fields), [Pipelines](/framework/docs/pipelines), [Limits and safety](/framework/docs/limits-and-safety).