Skip to main content

​
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: 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 › Shopify Ecosystem › TeamCopilot › Developer