Adobe Architecture Variants
Overview
Three validated architecture blueprints for Adobe integrations: (A) direct SDK integration in existing app, (B) Adobe App Builder with Runtime actions, and (C) dedicated microservice with event-driven pipelines.
Prerequisites
- Understanding of team size and throughput requirements
- Decision on which Adobe APIs to use (Firefly, PDF, Photoshop, Events)
- Knowledge of deployment infrastructure
- Growth projections for API usage
Instructions
Variant A: Direct SDK Integration (Simple)
Best for: MVPs, small teams (1-5), < 100 API calls/day, single Adobe API
my-app/
โโโ src/
โ โโโ adobe/
โ โ โโโ auth.ts # OAuth token management
โ โ โโโ firefly.ts # or pdf-services.ts โ one API client
โ โ โโโ types.ts
โ โโโ routes/
โ โ โโโ api/
โ โ โโโ generate.ts # Direct API call in route handler
โ โโโ index.ts
โโโ .env # ADOBE_CLIENT_ID, ADOBE_CLIENT_SECRET
โโโ package.json # @adobe/firefly-apis or @adobe/pdfservices-node-sdk
app.post('/api/generate', async (req, res) => {
try {
const token = await getCachedToken();
const result = await fetch('https://firefly-api.adobe.io/v3/images/generate', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'x-api-key': process.env.ADOBE_CLIENT_ID!,
'Content-Type': 'application/json',
},
body: JSON.stringify({ prompt: req.body.prompt, n: 1, size: { width: 1024, height: 1024 } }),
});
res.json(await result.json());
} catch (error: any) {
res.status(500).json({ error: error.message });
}
});
Pros: Fastest to build, simplest deployment, no extra infrastructure
Cons: No background processing, route handler blocks for 5-30s on Firefly calls
Variant B: Adobe App Builder (Native Adobe)
Best for: Adobe-centric workflows, teams using Adobe ecosystem, event-driven CC Library automation
my-adobe-app/
โโโ actions/ # Runtime actions (serverless functions)
โ โโโ generate-image/
โ โ โโโ index.js # Firefly image generation action
โ โโโ extract-pdf/
โ โ โโโ index.js # PDF extraction action
โ โโโ webhook-handler/
โ โโโ index.js # I/O Events webhook processor
โโโ web-src/ # Optional frontend (React/SPA)
โ โโโ src/
โโโ app.config.yaml # App Builder configuration
โโโ .aio # AIO CLI configuration
โโโ package.json
application:
actions: actions
web: web-src
runtimeManifest:
packages:
adobe-integration:
actions:
generate-image:
function: actions/generate-image/index.js
runtime: nodejs:20
web: yes
inputs:
ADOBE_CLIENT_ID: $ADOBE_CLIENT_ID
ADOBE_CLIENT_SECRET: $ADOBE_CLIENT_SECRET
limits:
timeout: 60000
memory: 256
annotations:
require-adobe-auth: true
webhook-handler:
function: actions/webhook-handler/index.js
runtime: nodejs:20
web: yes
annotations:
require-adobe-auth: false
const { Core } = require('@adobe/aio-sdk');
async function main(params) {
const logger = Core.Logger('generate-image');
try {
const token = params.__ow_headers?.authorization?.split(' ')[1]
|| await getServiceToken(params);
const response = await fetch('https://firefly-api.adobe.io/v3/images/generate', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'x-api-key': params.ADOBE_CLIENT_ID,
'Content-Type': 'application/json',
},
body: JSON.stringify({
prompt: params.prompt,
n: 1,
size: { width: params.width || 1024, height: params.height || },
}),
});
result = response.();
{ : , : result };
} (error) {
logger.(error);
{ : , : { : error. } };
}
}
. = main;
Pros: Native Adobe hosting, built-in auth, I/O Events integration, no infra management
Cons: Vendor lock-in, cold start latency, limited runtime options
Variant C: Dedicated Microservice (Enterprise)
Best for: High throughput (1000+ calls/day), multi-API workflows, strict SLAs
adobe-service/ # Dedicated microservice
โโโ src/
โ โโโ adobe/ # Client layer
โ โ โโโ auth.ts
โ โ โโโ firefly-client.ts
โ โ โโโ pdf-client.ts
โ โ โโโ photoshop-client.ts
โ โ โโโ events-client.ts
โ โโโ pipelines/ # Workflow orchestration
โ โ โโโ image-pipeline.ts # Firefly โ Photoshop โ Storage
โ โ โโโ document-pipeline.ts # PDF Extract โ Transform โ Store
โ โโโ workers/ # Background job processors
โ โ โโโ firefly-worker.ts
โ โ โโโ pdf-worker.ts
โ โโโ api/
โ โ โโโ grpc/adobe.proto # Internal API (gRPC)
โ โ โโโ rest/routes.ts # External API + webhooks
โ โโโ index.ts
โโโ k8s/
โ โโโ deployment.yaml
โ โโโ service.yaml
โ โโโ hpa.yaml # Auto-scale on pending jobs
โ โโโ configmap.yaml
โโโ package.json
other-services/
โโโ web-api/ # Calls adobe-service via gRPC
โโโ marketing-automation/ # Calls adobe-service for assets
โโโ document-processor/ # Calls adobe-service for PDFs
export async function imageProductionPipeline(request: {
prompt: string;
removeBackground: boolean;
outputBucket: string;
}) {
const generated = await fireflyClient.generate({
prompt: request.prompt,
size: { width: 2048, height: 2048 },
});
let imageUrl = generated.outputs[0].image.url;
if (request.removeBackground) {
const presignedInput = await uploadToStorage(imageUrl);
const presignedOutput = await getPresignedUploadUrl(request.outputBucket);
await photoshopClient.removeBackground({
input: { href: presignedInput, storage: 'external' },
output: { href: presignedOutput, storage: 'external', type: 'image/png' },
});
imageUrl = presignedOutput;
}
{ : imageUrl, : };
}
Pros: Full control, independent scaling, multi-API orchestration, strict isolation
Cons: Complex ops, needs K8s/container platform, higher development cost
Decision Matrix
| Factor | A: Direct SDK | B: App Builder | C: Microservice |
|---|
| Team Size | 1-5 | 3-10 | 10+ |
| API Calls/Day | < 100 | 100-1000 | 1000+ |
| Adobe APIs Used | 1 | 1-3 | 2+ |
| I/O Events | No | Yes (native) | Yes (custom) |
| Deployment | Any platform | Adobe hosting | K8s/containers |
| Time to Market | Days | 1-2 weeks | 3-8 weeks |
| Vendor Lock-in | Low | High (Adobe) | Low |
| Operational Cost | Lowest | Low (managed) | Highest |
Migration Path
A (Direct) โ B (App Builder):
Move route handlers to Runtime actions
Add I/O Events registration
Deploy with `aio app deploy`
A (Direct) โ C (Microservice):
Extract Adobe code to dedicated service
Add background job queue (BullMQ)
Define gRPC API contract
Deploy to Kubernetes
B (App Builder) โ C (Microservice):
Port Runtime actions to Express/Fastify
Replace I/O Events with custom webhook handling
Add HPA and monitoring
Output
- Architecture variant selected based on decision matrix
- Project structure matching chosen pattern
- Migration path documented for future scaling
Resources
Next Steps
For common anti-patterns, see adobe-known-pitfalls.
