> ## Documentation Index
> Fetch the complete documentation index at: https://demo-travel.webbinghub.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# The layers of Omnibeds and how a request moves through them

> Omnibeds is split into screens, a typed client, routes, commands, domain services, supplier adapters and data. Follow one request through every layer.

Omnibeds has seven layers, and each one only calls the layer below it. Knowing which layer a change belongs to is the first decision you make on any piece of work.

| Layer | Its job | Where it lives |
| - | - | - |
| Screens | Show data and collect the agent's choices. No business rules. | `app/(app)`, `components/` |
| Typed client | Call any command by name, with typed input and answer. | `lib/client/api.ts` |
| Routes | Turn an HTTP request into a command call, in one line. | `app/api/**/route.ts`, `lib/app/http.ts` |
| Commands | Name, risk, input schema and checks for every action. | `lib/app/commands/` |
| Domain services | The work: search, pricing, booking, quotes, trips. | `lib/orchestrator`, `lib/booking`, `lib/quotes`, `lib/trips`, `lib/pricing` |
| Supplier adapters | One contract, implemented once per supplier. | `lib/suppliers/` |
| Data | Postgres, migrations, transactions, agency scope. | `lib/db`, `lib/tenancy` |

## Follow one request

This is what happens when an agent cancels a booking. Step through it to see which layer does what.

Back
Next

The same path serves every action. Only the command and the service change.

## Which layer does my change belong to

> [accordion] A new button or a change to how something looks
>
> Screens only. If the screen needs data it can't get yet, add or extend a command; never fetch a URL by hand.

> [accordion] A new action, or a new rule about who may do it
>
> A command in `lib/app/commands/`, plus a one-line route and its entry in the typed client's `ROUTES`. See [Commands](https://demo-travel.webbinghub.io/docs/architecture/commands.md).

> [accordion] A change to how prices, bookings or quotes behave
>
> The domain service. Commands stay thin and call it.

> [accordion] A supplier sends or expects something different
>
> That supplier's adapter in `lib/suppliers/<supplier>/`. Nothing above the adapter knows a supplier's format. See [Adapters](https://demo-travel.webbinghub.io/docs/suppliers/adapters.md).

> [accordion] A new table or column
>
> A new migration. See [Data](https://demo-travel.webbinghub.io/docs/architecture/data.md).

## Boundaries the tests enforce

These rules are checked on every test run by `tests/boundaries.test.ts` and `tests/app-layer.test.ts`, so breaking one fails the build:

* Every command has a route, and that route file exists and serves the right HTTP method.
* Every route that isn't infrastructure is a one-line command route.
* Code in `lib/` never imports from `components/`.
* A screen never imports server code. Only types cross into the browser.
* A screen never writes a command's URL by hand; it calls `api()`.

> [!NOTE]
>
> A few routes sit outside the command layer on purpose because they aren't actions on travel data: the session switcher, presenter unlock, the search stream and its sentence parser, the access gate, the guided tour, health, and the scheduled jobs.

| Step | Layer | What happens when an agent cancels a booking |
| - | - | - |
| 1 | Screen | The bookings page calls `api("cancel", { reference, mode }, "Cancelling the booking")`. |
| 2 | Typed client | Looks up `ROUTES.cancel` (POST `/api/cancel`) and sends the input as JSON. |
| 3 | Route | `export const POST = commandRoute(cancel)` reads the body and runs the command. |
| 4 | Command | `execute()` checks the module, the permission, the input schema and presenter mode for confidential suppliers. |
| 5 | Service | `cancelBooking()` works out the cancellation fee from the booking's policy. |
| 6 | Adapter | The supplier's adapter sends its own cancel request. |
| 7 | Data and answer | The booking is saved, and the answer (or one error format) goes back to the screen. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.