Canva Production Reference Architecture
Overview
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.
Prerequisites
- Operations, tenants, traffic, data classes, and recovery objectives
- Scopes, capabilities, preview dependencies, and public-review posture
- Secret/token store, operation ledger, queue, observability, and rollback platform
Instructions
Step 1: Draw trust boundaries
Map browser, callback, backend, policy service, token vault, Canva adapter, job ledger, worker queue, data store, telemetry, and provider edges.
Step 2: Own authorization centrally
Resolve authenticated tenant, application role, resource ownership, explicit scope, capability, feature status, and data purpose before the adapter.
Step 3: Own tokens separately
Keep client secret and tokens backend-only, encrypt access and refresh tokens separately, serialize per-user refresh, and atomically replace single-use refresh tokens.
Step 4: Own mutation identity
Create a durable operation record before provider dispatch, attach returned resource/job identity, and reconcile terminal state across retries and restarts.
Step 5: Own data lifecycle
Store minimum approved metadata/content, authorize every read, expire temporary references, implement consent/account deletion, and keep protected values out of telemetry.
Step 6: Own failure recovery
Use endpoint-scoped admission, bounded retries, dead letters with reconciliation state, feature flags, immutable deploys, and exercised rollback.
Step 7: Record the blueprint
Use Write or Edit to document responsibilities, interfaces, schemas, threat decisions, SLOs, failure modes, and verification evidence.
Authentication
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.
Tool Discipline
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.
Output
- Scoped decision or implementation artifact
- Redacted operation and validation receipt
- Failure, rollback, and follow-up ownership record
Examples
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.
Error Handling
| 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 |