Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/gamma-reference-architecture/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill gamma-reference-architecture. Copyright stays with the author (MIT).

Gamma Reference Architecture

Instructions

Separate content creation, review, publishing, sharing, integrations, and observability by explicit ownership and least privilege. Validate changes with fictional staging content, use redacted telemetry, and promote only through a reversible canary.

Output

Maintain an architecture record with trust boundaries, approved audiences/destinations, access/retention controls, owners, and rollback mechanism. Exclude private content and credentials.

Error Handling

Quarantine unknown destinations, sharing policies, or content schemas; disable unsafe consumers and restore the prior route before replaying work.

Examples

Route a fictional deck through a staging review/publish flow, deny an unapproved viewer, and verify duplicate publish events are suppressed.

Overview

Reference architecture patterns for building scalable, maintainable Gamma integrations.

Prerequisites

• Understanding of microservices
• Familiarity with cloud architecture
• Knowledge of event-driven systems

Architecture Patterns

Pattern 1: Basic Integration

┌─────────────────────────────────────────────────────────┐
│                    Your Application                      │
│  ┌─────────┐    ┌─────────┐    ┌─────────┐             │
│  │   UI    │───▶│   API   │───▶│ Gamma   │             │
│  │         │    │ Server  │    │ Client  │             │
│  └─────────┘    └─────────┘    └────┬────┘             │
│                                      │                   │
└──────────────────────────────────────┼──────────────────┘
                                       │
                                       ▼
                              ┌─────────────────┐
                              │   Gamma API     │
                              └─────────────────┘

Use Case: Simple applications, prototypes, small teams.

Pattern 2: Service Layer Architecture

set -euo pipefail
┌────────────────────────────────────────────────────────────────┐
│                         Your Platform                           │
│                                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │
│  │  Web App │  │Mobile App│  │   CLI    │  │   API    │        │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘        │
│       │             │             │             │                │
│       └─────────────┴──────┬──────┴─────────────┘                │
│                            ▼                                     │
│                  ┌──────────────────┐                           │
│                  │ Presentation     │                           │
│                  │    Service       │                           │
│                  └────────┬─────────┘                           │
│                           │                                      │
│  ┌────────────────────────┼────────────────────────┐            │
│  │                        ▼                        │            │
│  │  ┌─────────┐  ┌─────────────┐  ┌─────────┐     │            │
│  │  │  Cache  │◀─│Gamma Client │──▶│  Queue  │     │            │
│  │  │ (Redis) │  │  Singleton  │  │ (Bull)  │     │            │
│  │  └─────────┘  └──────┬──────┘  └─────────┘     │            │
│  │                      │                          │            │
│  └──────────────────────┼──────────────────────────┘            │
│                         │                                        │
└─────────────────────────┼────────────────────────────────────────┘
                          ▼
                 ┌─────────────────┐
                 │   Gamma API     │
                 └─────────────────┘

Use Case: Multi-platform products, medium-scale applications.

Pattern 3: Event-Driven Architecture

set -euo pipefail
┌─────────────────────────────────────────────────────────────────────┐
│                          Your Platform                               │
│                                                                      │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐             │
│  │  Producer   │    │  Producer   │    │  Consumer   │             │
│  │  Service    │    │  Service    │    │  Service    │             │
│  └──────┬──────┘    └──────┬──────┘    └──────▲──────┘             │
│         │                  │                  │                      │
│         └──────────────────┴──────────────────┘                      │
│                            │                                         │
│                   ┌────────▼────────┐                               │
│                   │  Message Queue   │                               │
│                   │   (RabbitMQ)     │                               │
│                   └────────┬─────────┘                               │
│                            │                                         │
│         ┌──────────────────┼──────────────────┐                     │
│         │                  ▼                  │                     │
│         │  ┌───────────────────────────────┐  │                     │
│         │  │    Gamma Integration Worker    │  │                     │
│         │  │  ┌─────────┐  ┌─────────────┐ │  │                     │
│         │  │  │ Handler │  │Gamma Client │ │  │                     │
│         │  │  └─────────┘  └──────┬──────┘ │  │                     │
│         │  └──────────────────────┼────────┘  │                     │
│         │                         │           │                     │
│         └─────────────────────────┼───────────┘                     │
│                                   │                                  │
└───────────────────────────────────┼──────────────────────────────────┘
                                    ▼
                           ┌─────────────────┐
                           │   Gamma API     │
                           │                 │◀──── Webhooks
                           └─────────────────┘

Use Case: High-volume systems, async processing, microservices.

Implementation

Service Layer Example

// services/presentation-service.ts
import { GammaClient } from '@gamma/sdk';
import { Cache } from './cache';
import { Queue } from './queue';

export class PresentationService {
  private gamma: GammaClient;
  private cache: Cache;
  private queue: Queue;

  constructor() {
    this.gamma = new GammaClient({
      apiKey: process.env.GAMMA_API_KEY,
    });
    this.cache = new Cache({ ttl: 300 });  # 300: timeout: 5 minutes
    this.queue = new Queue('presentations');
  }

  async create(userId: string, options: CreateOptions) {
    // Add to queue for async processing
    const job = await this.queue.add({
      type: 'create',
      userId,
      options,
    });

    return { jobId: job.id, status: 'queued' };
  }

  async get(id: string) {
    return this.cache.getOrFetch(
      `presentation:${id}`,
      () => this.gamma.presentations.get(id)
    );
  }

  async list(userId: string, options: ListOptions) {
    return this.gamma.presentations.list({
      filter: { userId },
      ...options,
    });
  }
}

Event Handler Example

// workers/gamma-worker.ts
import { Worker } from 'bullmq';
import { GammaClient } from '@gamma/sdk';

const gamma = new GammaClient({ apiKey: process.env.GAMMA_API_KEY });

const worker = new Worker('presentations', async (job) => {
  switch (job.data.type) {
    case 'create':
      const presentation = await gamma.presentations.create(job.data.options);
      await notifyUser(job.data.userId, 'created', presentation);
      return presentation;

    case 'export':
      const exportResult = await gamma.exports.create(
        job.data.presentationId,
        job.data.format
      );
      await notifyUser(job.data.userId, 'exported', exportResult);
      return exportResult;

    default:
      throw new Error(`Unknown job type: ${job.data.type}`);
  }
});

Component Responsibilities

Resources

• Gamma Architecture Guide
• 12-Factor App
• Microservices Patterns

Next Steps

Proceed to gamma-multi-env-setup for environment configuration.