---

name: canva-architecture-variants description: 'Choose a Canva Connect integration architecture from explicit trust, workload, and recovery constraints. Use when deciding between a backend monolith, service plus workers, or isolated multi-tenant services. Trigger with: "design Canva architecture", "scale Canva integration", "choose Canva topology".' allowed-tools: Read, Grep, Write, Edit version: 2.0.0 argument-hint: '[constraints-and-scale-profile]' model: inherit effort: high license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:

• saas
• canva
• architecture
• operations compatibility: 'Architecture choices require a backend web application because Canva Connect secrets cannot be secured in browser-only clients.'

---

Canva Architecture Decision

Overview

Select the smallest topology that preserves backend OAuth, per-user token isolation, asynchronous job reconciliation, and policy-controlled data handling. Treat scale thresholds as measured local evidence, not Canva product limits.

Prerequisites

• Expected operations, traffic shape, tenants, and recovery objectives
• Data classification, retention policy, and secret backend
• Current scopes, capabilities, preview dependencies, and deployment constraints

Instructions

Step 1: Map trust boundaries

Identify browser, backend, token store, job ledger, worker, data store, and Canva API boundaries. Mark every place customer content or credentials could cross.

Step 2: Choose the base shape

Use a backend monolith for one bounded service, a service plus worker when asynchronous jobs must outlive requests, or isolated services only when ownership and failure domains justify them.

Step 3: Design token rotation

Serialize refresh per Canva user, atomically replace the single-use refresh token, and separate access-token and refresh-token storage.

Step 4: Design job reconciliation

Persist opaque job identity before dispatch, poll with bounded backoff, and reconcile terminal state before repeating a mutating operation.

Step 5: Design policy enforcement

Resolve tenant, resource, explicit scope, capability, preview status, and data policy before dispatch rather than inside a generic HTTP client.

Step 6: Record the decision

Use Write or Edit to capture selected shape, rejected alternatives, assumptions, failure modes, rollback, and validation 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

A service exports designs asynchronously for multiple tenants. A backend owns OAuth and policy, a durable ledger owns job identity, and workers are partitioned by tenant without embedding user IDs in metrics.

Error Handling

Failure	Response
Browser-only design proposed	Reject it because client secrets and token exchange require a backend
Workers can double-submit	Add durable identity and reconciliation before scaling
Topology chosen by guessed volume	Measure queue and failure behavior first
Preview dependency blocks review	Separate or disable that feature for the public release

Resources

• First-party source notes
• Connect security
• Authentication