# How Panlytics is organised

> Companies, shops, categories, products and suppliers, and how a person's role decides which of them a key can reach.

Markdown twin of https://panlytics.net/developers/concepts/how-panlytics-is-organised (last updated 2026-10-25). Every page of the Panlytics developer docs is listed at https://panlytics.net/developers/llms.txt, and all of them are in one file at https://panlytics.net/developers/llms-full.txt. The site guide is https://panlytics.net/llms.txt.

## From company to product

Everything in Panlytics sits inside one tree. Every endpoint reads or changes one part of it, and every id you send names one node of it.

| Level | What it is | Example |
| --- | --- | --- |
| Company | The business that signs up. It has one CEO and the people who work there. | Example Foods |
| Shop | One place that sells: a store, a branch or a web shop. A company has one or many. | Harbour, Old Town |
| Category | One part of a shop's range, built from a sales report the shop uploads. | Soft drinks at Harbour |
| Product | One line of the report, with its sales, its stock and the figures Panlytics works out. | Cola 0.5 l |

A category belongs to exactly one shop, and a product to exactly one category. The same drink sold at two shops is two products, one in each shop's category, because each shop sells it at its own pace.

## Reports make categories

A category starts life as a report: the sales export the shop's own till or ERP already makes. Uploading a report to a shop either starts a new category or brings the next period into one that exists. Panlytics reads the rows, repairs what it can, and flags what it cannot, without inventing a number.

Through the API, a report is uploaded to a shop with `POST /v1/shops/{id}/reports`; see [Upload a report](https://panlytics.net/developers/guides/upload-a-report). `GET /v1/shops/{id}/categories` lists a shop's categories, each with its newest report.

## Suppliers own categories

A supplier is a company that delivers to a shop. Each supplier is given the categories it delivers, and it carries the number of days a delivery takes. Panlytics uses those days when it works out when to order, so a category with no supplier uses the delivery days you gave Panlytics yourself, and the app says so on the category's page.

Suppliers are read per shop with `GET /v1/shops/{id}/suppliers`, added with `POST /v1/shops/{id}/suppliers`, changed with `PATCH /v1/suppliers/{id}`, given their categories with `PUT /v1/suppliers/{id}/categories`, and removed with `DELETE /v1/suppliers/{id}`. A role limited to chosen categories sees no suppliers, as in the app.

## Roles decide what a key can reach

Every person in a company holds a role. A role has three parts:

1. **A tier**: Manager or Operator. Some abilities are for Managers only.
2. **Abilities**: what the person may do, such as see the figures, upload a report or manage suppliers.
3. **A scope**: every shop (including shops opened later), chosen shops, or chosen categories inside one shop.

The CEO is not a role. The CEO holds every ability over every shop.

A key acts as its maker, so it reaches exactly what its maker's role reaches, minus the fence. `GET /v1/me` answers with that reach: `reach.allShops`, the list in `reach.shops`, and `reach.categories` when the role covers chosen categories only. A shop or a category outside the reach answers `404`, exactly as if it did not exist, so a key cannot even learn the names of shops it may not open.

## Abilities a key keeps

These are the abilities a key may use, when its maker's role holds them. The words are the ones the role editor uses, except where a key gets less than a person.

| Ability | What a key may do with it |
| --- | --- |
| `figures` | See the figures |
| `sheet` | Edit the sheet and upload a report |
| `export` | Take the figures out as a spreadsheet |
| `exceptions` | Manage exceptions |
| `agents` | Ask the agents. Approving what they propose stays with a person in the app |
| `suppliers` | Manage suppliers |
| `brain` | Read and correct the brain |
| `shops` | Open, rename and archive shops, and connect their systems |

The abilities a key never gets, whatever its maker holds, are on [What an AI can never do](https://panlytics.net/developers/security/what-an-ai-can-never-do).