---
title: Tarn & Timber documentation
description: What Tarn & Timber is, and how to read these docs.
sidebar:
  order: 1
  label: Welcome
---

Tarn & Timber is the fictional company behind this reference shop. Use the project to build a storefront secured
by Auth0 and learn how personal agents can use it through Poppy and MCP. These docs explain how to run a local
checkout, adapt the deployment, and follow requests from a shopper or agent to the shop's data.

:::note[What these pages describe]
The pages describe the code on `main`. They do not record what is deployed: a deployed instance can lag behind, and
the checkout's acceptance checklist (`docs/manual-acceptance.md`) is how a deployment is checked. The committed
settings describe a personal instance, not neutral defaults; [replace its domains and provider values](/getting-started#configure-your-own-deployment).
:::

## How to read these docs

**[Build your own shop](/getting-started)**

Run the local demo, connect real providers, and choose your deployment settings.

**[Understand Poppy](/poppy)**

Personal agents, account grants, Sessions and the first sign-in.

**[System map](/architecture)**

The architecture in one diagram, and the two boundaries that must always hold.

**[Components](/architecture/components)**

What each part does: storefront, API, MCP server, Auth0 proxy, backoffice, Auth0 and storage.

**[Callers and tokens](/architecture/callers-and-tokens)**

Who can call the API, how each caller is recognized, and what authority it gets.

**[Request flows](/architecture/request-flows/signed-in-checkout)**

Sequence diagrams for checkout, guests, MCP clients, the backoffice and Poppy agents.

## The idea in brief

The **Shop API** owns the shared capabilities, the database schema, the Durable Objects and all scheduled work. The
**storefront** runs the capabilities only it performs against the same database and calls the API for the shared
ones; the MCP server, the backoffice and personal agents are clients of the API. Each client proves who it is with an
access token, and the API decides what that token is allowed to do.