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

# TeamCopilot architecture

> Runtime, product data flow, embedded app structure, POS extension, and data model for TeamCopilot.

# TeamCopilot architecture

## Runtime

TeamCopilot is a Shopify embedded app served from a Cloudflare Worker, with a PostgreSQL database for merchant data. It consists of the embedded admin app and a Shopify POS extension.

The Worker exposes these public route groups:

| Group | Path | Purpose |
| - | - | - |
| OAuth | `/auth/*` | Shopify OAuth install flow |
| Webhooks | `/webhooks/*` | Shopify app, billing, and privacy webhooks |
| Billing | `/billing/*` | Subscription management |
| API | `/api/*` | Team-operations REST endpoints used by the embedded admin and POS extension |
| Static | `/health`, `/support` | Health endpoint and support page |

Every other path serves the embedded admin shell. The `/privacy`, `/legal/privacy`, and `/settings/privacy` routes redirect to `https://docs.pcnaid.com/teamcopilot/privacy`; `/terms`, `/legal/terms`, and `/settings/terms` redirect to `https://docs.pcnaid.com/teamcopilot/terms`.

## Product data flow

The embedded admin uses Shopify App Bridge and Polaris web components. API requests are authenticated with App Bridge session tokens. Access is role-based: team members, team managers, and team admins see different actions.

### Key features

* **Team member directory**: name, email, phone, role, PIN, default location, availability, and active or inactive status. PINs are stored only as salted hashes.
* **Shift builder**: create, publish, and notify. Published shifts send email and SMS notifications; a partial delivery returns HTTP 207.
* **Time clock**: PIN-verified clock-in and clock-out with geofence and integrity checks (late arrival, location mismatch, open entry conflict, device change). Integrity levels are clean, review, and blocked.
* **Checklists**: templates with ordered items, runs with due dates, and item completion tracking.
* **Exceptions**: integrity events, missed checklists, and unresolved time entries, with a manager clock-out action. An entry is flagged as a missed clock-out when it is open more than 120 minutes past shift end, or more than 16 hours with no linked shift.
* **Commission rules**: fixed-percent, fixed-amount, and goal-bonus (weekly sales threshold) types with weekly rollups. Paid-order attribution uses verified Shopify webhooks.
* **AI schedule suggestions**: generated suggestions are validated against scheduling rules (overlaps, shift boundaries) before they are shown.

## POS extension

The `pos-time-clock` extension adds a **Team Clock** tile to Shopify POS (`pos.home.tile.render`) and a clock-in/clock-out modal (`pos.home.modal.render`) that takes a team member ID and PIN. It uses `@shopify/ui-extensions` API 2026-04 and stops waiting on a request after 15 seconds.

## Billing

* **TeamCopilot Standard**: up to 10 active team members, 14-day trial
* **TeamCopilot Growth**: up to 50 active team members, 14-day trial

Plan state comes from Shopify app subscription webhooks. A shop receives one trial. Shopify development stores get Growth access for testing.

## Tenant isolation and privacy

Each merchant's data is isolated per shop at the database level. The mandatory Shopify privacy webhooks (`customers/data_request`, `customers/redact`, `shop/redact`) trigger data export and erasure.

[Pcnaid Documentation](https://docs.pcnaid.com/namespace/index.md) › [Shopify Ecosystem](https://docs.pcnaid.com/hubs/shopify-ecosystem/index.md) › [TeamCopilot](https://docs.pcnaid.com/nodes/shopify/teamcopilot/index.md) › [Developer](https://docs.pcnaid.com/nodes/shopify/teamcopilot/developer/index)


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