# Docs

- [PurrOS documentation](/docs): PurrOS is an open-source, self-hosted operations platform (ERP) for businesses with 20–500 people. Every feature is optional, and other systems connect through a REST API.
- Platform: Install, configure and run PurrOS
  - [Platform overview](/docs/platform): Install, configure and operate PurrOS on your own server, and administer its organization, accounts, roles and features.
  - Getting started
    - [Installation](/docs/platform/getting-started/installation): Run PurrOS on your own server with Docker Compose: requirements, configuration, first start, reverse proxy and scaling.
    - [Deploying on Dokploy](/docs/platform/getting-started/dokploy): Deploy PurrOS on Dokploy with its dedicated Compose file, environment, domain and first-time setup.
    - [Configuration](/docs/platform/getting-started/configuration): Every environment variable, and the config and state directories.
    - [Email (SMTP) & file storage (S3)](/docs/platform/getting-started/email-and-storage): Send email through any SMTP server, and store files on local disk or in any S3-compatible object storage.
    - [First-run setup](/docs/platform/getting-started/first-run-setup): Set up your company after installing: with the CLI today, and with the setup wizard once the web app ships.
    - [Key concepts](/docs/platform/getting-started/concepts): The terms used throughout PurrOS and its documentation.
  - Administration
    - [Organization & locations](/docs/platform/administration/organization-and-locations): The hierarchy of regions, districts and locations, location profiles, departments, and who can change them.
    - [Users, roles & permissions](/docs/platform/administration/users-and-roles): Accounts, custom roles, reach, system and starter roles, and the safeguards against privilege escalation.
    - [Permissions reference](/docs/platform/administration/permissions-reference): Every permission PurrOS defines, grouped by feature.
    - [Authentication](/docs/platform/administration/authentication): Sign-in methods, single sign-on, two-factor authentication, sessions, attack protection, API keys and recovering access.
    - [Feature switches](/docs/platform/administration/feature-switches): Every feature is optional. What switching one off means, the full feature list, dependencies, and what happens to your data.
  - Operations
    - [Backups & upgrades](/docs/platform/operations/backups-and-upgrades): Built-in consistent backups, off-site copies, restoring, and upgrading safely.
    - [Monitoring & troubleshooting](/docs/platform/operations/monitoring): Health checks, logs, metrics, purros status and doctor, and fixes for common problems.
    - [Security](/docs/platform/operations/security): How PurrOS protects sensitive data, what you are responsible for as the operator, and how to report a vulnerability.
    - [CLI reference](/docs/platform/operations/cli): Every purros command: server, setup, configuration, accounts and recovery, backups, and managing integrations, webhooks and features.
  - [Development guide](/docs/platform/contributing): Work on PurrOS itself: local setup, repository layout, the rules every endpoint follows, and adding a feature module.
- ERP Guides: Using every feature, day to day
  - [ERP guides](/docs/guides): How each part of PurrOS works day to day, written for the people who use it. Every feature is optional; switch on only what your business needs.

  - **People & time**
  - [People & HR](/docs/guides/people-and-hr): People & HR is the source of truth for **who works for you**: their details, role in the business, pay rates, skills and documents.
  - [Time & attendance](/docs/guides/time-and-attendance): Record hours accurately, apply your labor rules, get timesheets approved, and hand clean hours to payroll.
  - [Scheduling & forecasting](/docs/guides/scheduling-and-forecasting): Build schedules that match expected demand, respect everyone's availability and your labor rules, and stay on budget.
  - [Employee Area](/docs/guides/employee-area): The Employee Area is every employee's own space in PurrOS. It shows everything the company holds about them and lets them handle everyday requests themselves. It's written for employees, so you can share this page with your staff.

  - **Money & stock**
  - [Sales](/docs/guides/sales): Sales has two parts. You can use either one, or both.
  - [Cash management](/docs/guides/cash-management): Follow every cash and card payment from the register to the bank, spot shortages the same day, and keep a full audit trail.
  - [Inventory](/docs/guides/inventory): Know what you have, where it is, what it's worth, and where you're losing money, in real time.
  - [Purchasing & ordering](/docs/guides/purchasing-and-ordering): Order the right amount at the right time, receive it accurately, and pay only for what arrived at the agreed price.

  - **Operations**
  - [Forms, checklists & compliance](/docs/guides/forms-and-checklists): Replace paper checklists, logs and inspection sheets with digital forms that get done on time, alert people when something is wrong, and prove it was handled.
  - [Equipment & assets](/docs/guides/equipment-and-assets): Keep track of your equipment, maintain it before it breaks, and get repairs done quickly.
  - [Communication](/docs/guides/communication): Reach the right people, at the right locations, without sharing personal phone numbers or relying on outside group chats.
  - [Team displays](/docs/guides/team-displays): Turn any screen in the workplace into a live team board that shows goals and progress, recognizes good work and reminds people about shifts.
  - [Reports & insights](/docs/guides/reports-and-insights): See how every location is doing, catch problems early, and know what to fix first.
- API: REST API, ingestion and webhooks
  - [API overview](/docs/api): The PurrOS REST API gives other systems access to everything the web interface can do. Its main job is bringing data in; webhooks send changes back out.

  - **Fundamentals**
  - [Authentication & scopes](/docs/api/authentication): The three ways to call the API, how people's permissions and reach are checked, and every integration scope.
  - [Conventions](/docs/api/conventions): Naming, IDs, dates, decimal money, the standard operations, pagination, filtering and the versioning promise.
  - [Errors & limits](/docs/api/errors): RFC 9457 Problem Details with stable error codes, idempotency keys for safe retries, and rate limits.

  - **Guides**
  - [Data ingestion](/docs/api/data-ingestion): Send sales, tenders, punches, orders and other data from the systems a business already uses, reliably and idempotently.
  - [Webhooks](/docs/api/webhooks): Get told about changes made in PurrOS: subscribing, payloads, signature verification, retries, replay and the event catalog.
  - [Attachments](/docs/api/attachments): Upload files that go with records (proof, photos, receipts, signed forms, payslips) and control who can see them.

  - **Reference**
  - Endpoint reference
    - [Endpoint reference](/docs/api/reference): Every PurrOS API endpoint, with the scope and permission it needs and the feature it belongs to. Search, filter, or browse by area.

    - **Platform**
    - [Authentication](/docs/api/reference/authentication): Sign-in, sessions, two-factor authentication, password resets and personal API keys.
    - [Users & Roles](/docs/api/reference/users-and-roles): Inviting and managing accounts, custom roles, and company sign-in settings.
    - [Platform](/docs/api/reference/platform): Discovery endpoints: enabled features, the calling key, the permission catalog and the OpenAPI document.
    - [Organization](/docs/api/reference/organization): Org units, locations and departments, plus read-only roles and users for integrations.
    - [Attachments](/docs/api/reference/attachments): Uploading, listing, downloading and deleting files.
    - [Integrations](/docs/api/reference/integrations): Registering and managing integrations: manifests, config, keys, logs and ingestion batches.
    - [Integration self-service](/docs/api/reference/integration-self-service): What an integration can call about itself: its registration, config, heartbeat and log.
    - [Webhooks](/docs/api/reference/webhooks): Webhook endpoints and their delivery log: add, test, rotate secrets, and replay deliveries.

    - **Features**
    - [People & HR](/docs/api/reference/people): Employees, transfers and terminations, documents, skills, pay rates and payslips.
    - [Time & Attendance](/docs/api/reference/time): Punches and corrections, timesheets, labor rules, pay periods, payroll export and time off.
    - [Scheduling & Forecasting](/docs/api/reference/scheduling): Demand drivers, forecasts, staffing rules and needs, shifts, publishing, swaps and availability.
    - [Cash Management](/docs/api/reference/cash): Tenders, settlements, bank transactions, drawer counts, deposits and business-day close.
    - [Inventory](/docs/api/reference/inventory): Items, stock levels and the stock ledger, adjustments, waste, counts, transfers and usage recipes.
    - [Purchasing & Ordering](/docs/api/reference/purchasing): Suppliers and catalogs, suggested orders, purchase orders, receiving and supplier invoices.
    - [Sales](/docs/api/reference/sales): Sales feeds and unmapped items, customers, sales orders and invoices.
    - [Forms, Checklists & Compliance](/docs/api/reference/operations): Forms and submissions, scored audits, corrective actions, sensors and readings.
    - [Equipment & Assets](/docs/api/reference/equipment): The asset register, meter readings, preventive maintenance and work orders.
    - [Communication](/docs/api/reference/communication): Announcements with acknowledgments, and the company calendar.
    - [Team Displays](/docs/api/reference/displays): Live display metrics and recognition shout-outs for team displays.
    - [Reports & Insights](/docs/api/reference/insights): Headline KPIs, built-in reports, recommendations and KPI alert rules.
    - [Employee Area](/docs/api/reference/employee-area): Everything under /me: an employee's own profile, time, shifts, time off, pay, documents and data export.
- Integrations: Connect POS, stores, HR, payroll and more
  - [Integrations](/docs/integrations): Every connection to another system is an integration: a small program that talks to PurrOS through its API and webhooks.
  - [Build an integration](/docs/integrations/building-an-integration): A step-by-step TypeScript tutorial: sync sales from a POS into PurrOS and react to webhooks.
  - [Integration recipes](/docs/integrations/recipes): Patterns for connecting POS systems, online stores, timeclocks, HR, payroll, accounting, banks, suppliers, sensors and more.