| name | adobe-reference-architecture |
| description | Implement Adobe reference architecture for production integrations covering
Firefly Services, PDF Services, I/O Events, and App Builder with layered
project layout, error boundaries, and health monitoring.
Trigger with phrases like "adobe architecture", "adobe project structure",
"how to organize adobe", "adobe layout", "adobe best practices".
|
| allowed-tools | Read, Grep |
| version | 1.7.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","design","adobe"] |
| compatibility | Designed for Claude Code |
Adobe Reference Architecture
Overview
Production-ready architecture patterns for Adobe API integrations, designed around the three main API families: Firefly Services (creative AI), PDF Services (document automation), and I/O Events (event-driven).
Prerequisites
- Understanding of layered architecture
- TypeScript project setup
- Decision on which Adobe APIs to integrate
Instructions
Step 1: Project Structure
my-adobe-project/
├── src/
│ ├── adobe/ # Adobe client layer
│ │ ├── auth.ts # OAuth Server-to-Server token management
│ │ ├── firefly-client.ts # Firefly API wrapper (generate, fill, expand)
│ │ ├── pdf-client.ts # PDF Services wrapper (create, extract, merge)
│ │ ├── photoshop-client.ts # Photoshop API wrapper (cutout, actions)
│ │ ├── events-client.ts # I/O Events registration and verification
│ │ ├── types.ts # Shared Adobe types
│ │ └── errors.ts # Error classification (retryable vs permanent)
│ ├── services/ # Business logic layer
│ │ ├── image-generation.ts # Orchestrates Firefly + Photoshop workflows
│ │ ├── document-pipeline.ts # Orchestrates PDF create/extract/merge
│ │ └── event-processor.ts # Routes and processes I/O Events
│ ├── api/ # API layer (routes, controllers)
│ │ ├── health.ts # Health check including Adobe IMS
│ │ ├── webhooks/adobe.ts # I/O Events webhook endpoint
│ │ └── routes/
│ │ ├── images.ts # Image generation endpoints
│ │ └── documents.ts # Document processing endpoints
│ ├── jobs/ # Background job layer
│ │ ├── firefly-batch.ts # Batch image generation queue
│ │ └── pdf-extraction.ts # Async PDF extraction worker
│ └── index.ts
├── tests/
│ ├── unit/
│ │ ├── adobe/auth.test.ts
│ │ └── services/
│ └── integration/
│ └── adobe/
│ ├── firefly.test.ts
│ └── pdf-services.test.ts
├── config/
│ ├── adobe.development.json
│ ├── adobe.staging.json
│ └── adobe.production.json
└── package.json
Step 2: Layer Architecture
┌─────────────────────────────────────────────────────┐
│ API Layer │
│ Routes, Controllers, Webhook Endpoints │
├─────────────────────────────────────────────────────┤
│ Service Layer │
│ Business Logic, Workflow Orchestration │
│ (image-generation.ts, document-pipeline.ts) │
├─────────────────────────────────────────────────────┤
│ Adobe Client Layer │
│ auth.ts, firefly-client.ts, pdf-client.ts │
│ Token caching, retry, error classification │
├─────────────────────────────────────────────────────┤
│ Infrastructure Layer │
│ Cache (LRU/Redis), Queue (BullMQ), Monitoring │
└─────────────────────────────────────────────────────┘
