miro-reference-architecture

name	miro-reference-architecture
description	Implement a production-ready reference architecture for Miro REST API v2 integrations with layered design, caching, and event processing. Trigger with phrases like "miro architecture", "miro project structure", "how to organize miro integration", "miro design patterns".
allowed-tools	Read, Grep
version	1.7.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","miro","architecture","design"]
compatibility	Designed for Claude Code

Miro Reference Architecture

Overview

Production-ready architecture for Miro REST API v2 integrations. Layered design with a board service, item factory, webhook event processor, and caching layer.

Prerequisites

Before applying this guide, confirm you have a Miro app or workspace appropriate to the task, a dedicated non-production board where changes can be tested safely, and only the OAuth scopes or administrative access the procedure requires.

Architecture Diagram

┌──────────────────────────────────────────────────────────┐
│                    API / UI Layer                         │
│   Express routes, Next.js API routes, CLI commands       │
├──────────────────────────────────────────────────────────┤
│                   Service Layer                          │
│   BoardService, ItemService, SyncService                 │
│   (business logic, orchestration, validation)            │
├──────────────────────────────────────────────────────────┤
│                  Miro Client Layer                        │
│   MiroApiClient (REST v2), TokenManager (OAuth 2.0)      │
│   ItemFactory (typed creation), ConnectorBuilder          │
├──────────────────────────────────────────────────────────┤
│                Infrastructure Layer                       │
│   Cache (LRU/Redis), Queue (PQueue), Monitor (metrics)   │
│   WebhookProcessor (signature + idempotency)             │
└──────────────────────────────────────────────────────────┘
                         │
                         ▼
            https://api.miro.com/v2/

Project Structure

src/
├── miro/
│   ├── client.ts              # MiroApiClient — wraps fetch with auth, retries, monitoring
│   ├── token-manager.ts       # OAuth 2.0 token lifecycle (refresh, storage)
│   ├── item-factory.ts        # Typed item creation (sticky notes, shapes, cards, etc.)
│   ├── connector-builder.ts   # Fluent API for creating connectors
│   ├── types.ts               # TypeScript types for all Miro v2 responses
│   └── errors.ts              # MiroApiError, MiroAuthError, MiroRateLimitError
├── services/
│   ├── board-service.ts       # Board CRUD + member management
│   ├── item-service.ts        # Item CRUD + tag operations
│   ├── sync-service.ts        # Two-way sync between Miro and your database
│   └── search-service.ts      # Find items by content, type, or tag
├── webhooks/
│   ├── handler.ts             # Express/serverless webhook endpoint
│   ├── processor.ts           # Event routing and processing
│   └── idempotency.ts         # Duplicate event prevention
├── cache/
│   ├── board-cache.ts         # Board metadata cache
│   └── item-cache.ts          # Item data cache with webhook invalidation
├── config/
│   ├── miro.ts                # Environment-based Miro configuration
│   └── index.ts               # Config loader
└── monitoring/
    ├── metrics.ts             # Prometheus counters/histograms for Miro API
    └── health.ts              # Health check endpoint

Core Components

MiroApiClient

// src/miro/client.ts
export class MiroApiClient {
  constructor(
    private tokenManager: TokenManager,
    private cache: ItemCache,
    private monitor: MiroMetrics,
  ) {}

  async fetch<T>(path: string, method = 'GET', body?: unknown): Promise<T> {
    const token = await this.tokenManager.getValidToken();
    const start = performance.now();

    const response = await fetch(`https://api.miro.com${path}`, {
      method,
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json',
      },
      ...(body ? { body: JSON.stringify(body) } : {}),
    });

    const duration = performance.now() - start;
    this.monitor.recordRequest(method, path, response.status, duration);
    ..(response);

     (response. === ) {
       retryAfter = (response..() ?? , );
        (retryAfter);
    }

     (!response.) {
       error =  response.().( ({}));
        (response., error., error.);
    }

     (response. === )    T;
     response.()  T;
  }

  
   fetchAll<T>(: , limit = ): <T[]> {
     : T[] = [];
     :  | ;

     {
       params =  ({ : (limit) });
       (cursor) params.(, cursor);

       result =  .<<T>>(
        
      );
      items.(...result.);
      cursor = result.;
    }  (cursor);

     items;
  }
}

Board Service

// src/services/board-service.ts
export class BoardService {
  constructor(
    private api: MiroApiClient,
    private cache: BoardCache,
  ) {}

  async getBoard(boardId: string): Promise<MiroBoard> {
    const cached = await this.cache.get(boardId);
    if (cached) return cached;

    const board = await this.api.fetch<MiroBoard>(`/v2/boards/${boardId}`);
    await this.cache.set(boardId, board, 120);  // 2 min TTL
    return board;
  }

  async createBoard(params: CreateBoardParams): Promise<MiroBoard> {
    return this.api.fetch<MiroBoard>('/v2/boards', , {
      : params.,
      : params.,
      : params.,
      : {
        : { : params. ??  },
        : { :  },
      },
    });
  }

   (: , : [], : ): <> {
     ..(, , {
      emails,
      role,  
    });
  }

   (: ): <[]> {
     ..();
  }
}

Webhook Processor

// src/webhooks/processor.ts
export class WebhookProcessor {
  private handlers = new Map<string, EventHandler[]>();

  on(eventType: string, handler: EventHandler): void {
    const existing = this.handlers.get(eventType) ?? [];
    existing.push(handler);
    this.handlers.set(eventType, existing);
  }

  async process(event: MiroBoardEvent): Promise<void> {
    // Type-based routing
    const key = `${event.item.type}:${event.type}`;  // e.g., 'sticky_note:create'
    const handlers = [
      ...(this.handlers.get(key) ?? []),
      ...(this.handlers.get(`*:${event.type}`) ?? []),  // Wildcard item type
      ...(this.handlers.() ?? []),               
    ];

     ( handler  handlers) {
       (event);
    }
  }
}


 processor =  ();

processor.(,  (event) => {
  .();
   syncService.(event., event..);
});

processor.(,  (event) => {
  .();
   database.(event..);
});

Connector Builder (Fluent API)

// src/miro/connector-builder.ts
export class ConnectorBuilder {
  private config: any = { style: {} };

  constructor(private api: MiroApiClient, private boardId: string) {}

  from(itemId: string, snapTo?: SnapPosition): this {
    this.config.startItem = { id: itemId, ...(snapTo ? { snapTo } : {}) };
    return this;
  }

  to(itemId: string, snapTo?: SnapPosition): this {
    this.config.endItem = { id: itemId, ...(snapTo ? { snapTo } : {}) };
    return this;
  }

  caption(text: string, position = 0.5): this {
    this.config.captions = [{ content: text, position }];
    return this;
  }

  ():  { ... = ;  ; }
  ():  { .. = ;  ; }
  ():  { ... = ;  ; }

   (): <> {
     ..(, , .);
  }
}


 connector =   (api, boardId)
  .(taskId, )
  .(dependencyId, )
  .()
  .()
  .()
  .();

Data Flow

User Action (or cron job)
     │
     ▼
┌─────────────┐
│   Service   │  ←── Business logic
│   Layer     │
└──────┬──────┘
       │
  ┌────┴────┐
  │         │
  ▼         ▼
┌──────┐ ┌──────┐
│Cache │ │ Miro │  ←── api.miro.com/v2
│Layer │ │Client│
└──────┘ └──────┘

Miro Board Change
     │
     ▼
┌─────────────┐
│  Webhook    │  ←── Signature verification
│  Handler    │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Processor   │  ←── Idempotency + routing
└──────┬──────┘
       │
  ┌────┴────┐
  │         │
  ▼         ▼
┌──────┐ ┌──────┐
│Cache │ │  DB  │  ←── Sync + invalidation
│Inval │ │Sync  │
└──────┘ └──────┘

Configuration

// src/config/miro.ts
export interface MiroConfig {
  clientId: string;
  clientSecret: string;
  accessToken?: string;
  environment: 'development' | 'staging' | 'production';
  cache: { enabled: boolean; ttlSeconds: number };
  rateLimit: { maxConcurrency: number; requestsPerSecond: number };
  webhook: { secret: string; callbackUrl: string };
}

export function loadMiroConfig(): MiroConfig {
  return {
    clientId: requireEnv('MIRO_CLIENT_ID'),
    clientSecret: requireEnv('MIRO_CLIENT_SECRET'),
    accessToken: process.env.MIRO_ACCESS_TOKEN,
    environment: (process.env.NODE_ENV ?? 'development') as MiroConfig['environment'],
    cache: {
      enabled: process.. !== ,
      : (process.. ?? ),
    },
    : {
      : (process.. ?? ),
      : (process.. ?? ),
    },
    : {
      : process.. ?? ,
      : process.. ?? ,
    },
  };
}

Instructions

Use the ordered procedures and code samples in this guide as a sequence: begin with the prerequisites, apply the configuration or operational step for the target environment, then perform the documented validation or cleanup before proceeding. Keep credentials in the documented secret store; never hard-code them in source.

Output

Following this guide produces the Miro integration outcome for its topic—configuration, validation evidence, operational recovery, or a documented migration result. Record command output and relevant identifiers so a failed step is traceable.

Examples

Start with the smallest applicable command or code example in the relevant section, using a dedicated test board and non-production credentials. Confirm the expected response or validation result before applying the pattern to production.

Error Handling

Layer	Error Type	Handling
Client	429 Rate Limited	Exponential backoff with Retry-After
Client	401 Token Expired	Auto-refresh via TokenManager
Service	Item Not Found	Return null, log, continue
Webhook	Invalid Signature	Return 401, do not process
Webhook	Duplicate Event	Skip via idempotency check
Cache	Redis Down	Fall through to API directly

Resources

• Miro REST API Reference
• Miro Node.js Client
• Miro App Examples (GitHub)

Next Steps

For multi-environment setup, see miro-multi-env-setup.