canva-reference-architecture

name	canva-reference-architecture
description	Implement Canva Connect API reference architecture with best-practice project layout. Use when designing new Canva integrations, reviewing project structure, or establishing architecture standards for Canva applications. Trigger with phrases like "canva architecture", "canva project structure", "how to organize canva", "canva layout", "canva reference".
allowed-tools	Read, Grep
version	1.5.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","design","canva"]
compatibility	Designed for Claude Code

Canva Reference Architecture

Overview

Production-ready architecture for Canva Connect API integrations. All interactions use the REST API at api.canva.com/rest/v1/* with OAuth 2.0 PKCE authentication.

Project Structure

my-canva-integration/
├── src/
│   ├── canva/
│   │   ├── client.ts           # REST client wrapper with auto-refresh
│   │   ├── auth.ts             # OAuth 2.0 PKCE flow
│   │   ├── types.ts            # API request/response TypeScript types
│   │   └── errors.ts           # CanvaAPIError class
│   ├── services/
│   │   ├── design.service.ts   # Design creation, export, listing
│   │   ├── asset.service.ts    # Asset upload and management
│   │   ├── template.service.ts # Brand template autofill (Enterprise)
│   │   └── folder.service.ts   # Folder management
│   ├── routes/
│   │   ├── auth.ts             # OAuth callback endpoints
│   │   ├── designs.ts          # Design CRUD routes
│   │   ├── exports.ts          # Export trigger/download routes
│   │   └── webhooks.ts         # Webhook receiver
│   ├── middleware/
│   │   ├── auth.ts             # Verify user has valid Canva token
│   │   └── rate-limit.ts       # Client-side rate limit guard
│   ├── store/
│   │   └── tokens.ts           # Encrypted token storage (DB)
│   └── index.ts
├── tests/
│   ├── mocks/
│   │   └── canva-server.ts     # MSW mock server
│   ├── unit/
│   │   └── design.service.test.ts
│   └── integration/
│       └── canva-api.test.ts
├── .env.example
└── package.json

Layer Architecture

┌─────────────────────────────────────────┐
│             Routes Layer                │
│   (Express/Next.js — HTTP in/out)       │
├─────────────────────────────────────────┤
│           Service Layer                 │
│  (Business logic, caching, validation)  │
├─────────────────────────────────────────┤
│          Canva Client Layer             │
│   (REST calls, token refresh, retry)    │
├─────────────────────────────────────────┤
│         Infrastructure Layer            │
│    (Token store, cache, queue)          │
└─────────────────────────────────────────┘

Service Layer Pattern

// src/services/design.service.ts
import { CanvaClient } from '../canva/client';
import { LRUCache } from 'lru-cache';

export class DesignService {
  private cache =  <, >({ : , :  });

  () {}

   () {
     designType = opts. === 
      ? { :   , : opts.! }
      : { :   , : opts.!, : opts.! };

     ..(, {
      : ,
      : .({
        : designType,
        : opts.,
        ...(opts. && { : opts. }),
      }),
    });
  }

   () {
     cached = ..(id);
     (cached)  cached;

     result =  ..();
    ..(id, result);
     result;
  }

   (: , : ): <[]> {
    
     { job } =  ..(, {
      : ,
      : .({ : designId, format }),
    });

    
     .(job.);
  }

    (: , timeoutMs = ): <[]> {
     start = .();
     (.() - start < timeoutMs) {
       { job } =  ..();
       (job. === )  job.;
       (job. === )   ();
        ( (r, ));
    }
      ();
  }
}