canva-reference-architectureImplement a Canva Connect backend reference architecture with policy, OAuth, job reconciliation, and privacy-safe operations. Use when establishing service boundaries, ownership, storage, and recovery for production. Trigger with: "Canva reference architecture", "design Canva backend", "Canva service layout".
Independent GitHub snapshot · Automated classification · Original documentation governs
name: canva-reference-architecture description: 'Implement a Canva Connect backend reference architecture with policy, OAuth, job reconciliation, and privacy-safe operations. Use when establishing service boundaries, ownership, storage, and recovery for production. Trigger with: "Canva reference architecture", "design Canva backend", "Canva service layout".' allowed-tools: Read, Grep, Write, Edit version: 2.0.0 argument-hint: '[requirements-and-data-classification]' model: inherit effort: high license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:
Separate browser experience, backend OAuth/policy, provider adapter, durable operation ledger, workers, and controlled data stores. The architecture must prevent cross-tenant access and duplicate mutation by construction.
Map browser, callback, backend, policy service, token vault, Canva adapter, job ledger, worker queue, data store, telemetry, and provider edges.
Resolve authenticated tenant, application role, resource ownership, explicit scope, capability, feature status, and data purpose before the adapter.
Keep client secret and tokens backend-only, encrypt access and refresh tokens separately, serialize per-user refresh, and atomically replace single-use refresh tokens.
Create a durable operation record before provider dispatch, attach returned resource/job identity, and reconcile terminal state across retries and restarts.
Store minimum approved metadata/content, authorize every read, expire temporary references, implement consent/account deletion, and keep protected values out of telemetry.
Use endpoint-scoped admission, bounded retries, dead letters with reconciliation state, feature flags, immutable deploys, and exercised rollback.
Use Write or Edit to document responsibilities, interfaces, schemas, threat decisions, SLOs, failure modes, and verification evidence.
Canva Connect calls use Bearer access tokens obtained by a backend through OAuth 2.0 Authorization Code with SHA-256 PKCE. Request explicit least-privilege scopes, keep client secrets and tokens out of browser-visible state, and serialize refresh so the replacement single-use refresh token is stored atomically.
Use Read and Grep for discovery and evidence. Use Write or Edit only for the approved artifact, code, configuration, test, or receipt described by this workflow; do not make an unapproved Canva-side change.
The browser never receives a client secret or refresh token. The backend policy service authorizes an export, the ledger preserves identity, a worker polls the same job, and the application mediates result delivery.
| Failure | Response |
|---|---|
| Business roles leak into generic client | Move authorization before the adapter |
| Refresh can run concurrently | Add a per-user lock and atomic replacement |
| Queue lacks operation identity | Stop writes until the ledger exists |
| Telemetry contains resource identifiers | Redesign dimensions and redact |