Imported from jeremylongshore/tons-of-skills-marketplace (plugins/saas-packs/canva-pack/skills/canva-architecture-variants/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill canva-architecture-variants. Copyright stays with the author (MIT).

Canva Architecture Variants

Overview

Three validated architecture patterns for Canva Connect API integrations. All use the REST API at api.canva.com/rest/v1/* with OAuth 2.0 PKCE tokens. The key architectural decision is how to handle token storage, async operations (exports, autofills), and rate limit management.

Prerequisites

• A reviewed OAuth/asset authorization model, protected secrets/data stores, current provider constraints, and a named operations owner.
• Mocked tests and a synthetic-asset integration environment for evaluating variants without using customer designs.

Instructions

1. Select a variant based on declared tenant isolation, data classification, operational SLOs, and expected export/async workload—not only implementation convenience.
2. Place authorization, input validation, idempotency, rate/cost limits, and redacted audit logging in front of the Canva adapter in every variant.
3. Test the chosen variant with synthetic assets, verify failure/rollback behavior, and record the approved scope before production rollout.

Variant A: Monolith (Simple)

Best for: MVPs, small teams, < 100 Canva users

my-app/
├── src/
│   ├── canva/
│   │   ├── client.ts          # REST client with auto-refresh
│   │   ├── auth.ts            # OAuth PKCE flow
│   │   └── types.ts
│   ├── routes/
│   │   ├── auth.ts            # OAuth callback
│   │   └── designs.ts         # Design CRUD
│   ├── store/
│   │   └── tokens.ts          # SQLite/file token store
│   └── index.ts

// Direct API calls in route handlers
app.post('/api/designs', async (req, res) => {
  const canva = getClientForUser(req.user.id);

  const { design } = await canva.request('/designs', {
    method: 'POST',
    body: JSON.stringify({
      design_type: { type: 'custom', width: 1080, height: 1080 },
      title: req.body.title,
    }),
  });

  res.json({ designId: design.id, editUrl: design.urls.edit_url });
});

Pros: Fast to build, simple token management, easy to debug. Cons: Synchronous exports block requests, no job queue for autofills.

Variant B: Service Layer (Moderate)

Best for: Growing apps, 100-1,000 users, multiple Canva features

my-app/
├── src/
│   ├── canva/
│   │   ├── client.ts
│   │   └── auth.ts
│   ├── services/
│   │   ├── design.service.ts   # Business logic + caching
│   │   ├── export.service.ts   # Async export with polling
│   │   ├── asset.service.ts    # Upload management
│   │   └── template.service.ts # Autofill orchestration
│   ├── queue/
│   │   └── export-worker.ts    # Background export processing
│   ├── routes/
│   └── store/
│       └── tokens.ts           # PostgreSQL encrypted tokens

// Service layer handles caching, retry, and async operations
class ExportService {
  constructor(
    private canva: CanvaClient,
    private cache: Redis,
    private queue: Bull.Queue
  ) {}

  async exportDesign(designId: string, format: object): Promise<string> {
    // Check cache for recent export
    const cached = await this.cache.get(`export:${designId}:${JSON.stringify(format)}`);
    if (cached) return cached;

    // Queue export job — don't block the request
    const job = await this.queue.add('canva-export', { designId, format });
    return job.id;
  }
}

// Background worker polls Canva export API
exportQueue.process('canva-export', async (job) => {
  const { designId, format } = job.data;
  const canva = await getServiceClient();

  const { job: exportJob } = await canva.request('/exports', {
    method: 'POST',
    body: JSON.stringify({ design_id: designId, format }),
  });

  // Poll for completion
  let result = exportJob;
  while (result.status === 'in_progress') {
    await new Promise(r => setTimeout(r, 2000));
    const poll = await canva.request(`/exports/${result.id}`);
    result = poll.job;
  }

  return result.status === 'success' ? result.urls : null;
});

Pros: Non-blocking exports, caching, separation of concerns. Cons: More infrastructure (Redis, job queue), more complex deployment.

Variant C: Microservice (Enterprise)

Best for: 1,000+ users, multi-team, strict SLAs, Canva Enterprise with autofill

canva-service/                # Dedicated microservice
├── src/
│   ├── api/
│   │   └── grpc/             # Internal gRPC API
│   ├── canva/
│   │   ├── client.ts
│   │   └── auth.ts
│   ├── services/
│   ├── workers/
│   │   ├── export.worker.ts
│   │   ├── autofill.worker.ts
│   │   └── webhook.worker.ts
│   └── store/
│       └── tokens.ts         # Vault-backed token storage
├── k8s/
│   ├── deployment.yaml
│   ├── service.yaml
│   └── hpa.yaml              # Scale based on queue depth

Key differences:

• Dedicated service owns all Canva API interaction
• gRPC for internal services, REST for external
• Separate workers for exports, autofills, webhooks
• Circuit breaker per operation type
• Token storage in HashiCorp Vault or KMS
• HPA scales based on export queue depth

Decision Matrix

Migration Path

Monolith → Service Layer:
1. Extract canva/ to services/
2. Add Redis for caching
3. Add BullMQ for async exports
4. Move token store to PostgreSQL

Service Layer → Microservice:
1. Create canva-service repository
2. Define gRPC contract
3. Add per-operation workers
4. Deploy to Kubernetes
5. Migrate token store to Vault

Output

The architecture decision records the chosen variant, scope, authorization/data boundaries, resilience controls, test evidence, and rollback path. It excludes tokens, design contents, signed URLs, and tenant-identifying configuration values.

Examples

For a multi-tenant export product, choose the variant that isolates tenant credentials and queues, validate a synthetic export with a policy-resolved asset, and document its rate/cost and recovery behavior. Reject a variant that requires exposing a token or sharing customer design data to meet its operational goal.

Error Handling

Resources

• Canva Starter Kit
• Canva API Reference
• Monolith First

Next Steps

For common anti-patterns, see canva-known-pitfalls.