Acquia Source Integration - Development Guide

Purpose: Complete guide for building Acquia Source products Audience: Agents working on Tier 1-3 products Strategic Value: $6.2M ARR Year 1, $155-310M Acquisition Target

🎯 Overview

The Opportunity

Acquia Source is Acquia's new headless CMS (launched 2025). We have:

First-mover advantage: Just launched, minimal competition
Personal connections: 23 years Drupal experience, 10 years Acquia, daughter works at Acquia
Platform ready: compliance-engine, agent-mesh, 54 agents deployed
GitLab employment: Co-marketing opportunity

The Strategy

3-Tier Product Approach:

Tier 1 ($642k ARR): Foundation products (Compliance Shield, DevOps Accelerator, AI Agents)
Tier 2 ($2.5M ARR): Advanced products (API Gateway, Multi-Tenant, DAM Intelligence)
Tier 3 ($3.1M ARR): Strategic assets (Edge Network, Marketplace, Intelligence Platform)

Exit Strategy: Build to $155-310M acquisition value (or profitable standalone business)

📁 Repository Structure

api-schema-registry

Location: /Users/flux423/Library/Mobile Documents/com~apple~CloudDocs/AgentPlatform/_REPOSITORIES/api-schema-registry

Acquia Source Files:

api-schema-registry/
├── openapi/acquia-cms/
│   ├── openapi-converted.yaml          # 141 endpoints, 409 operations
│   └── schemas/
│       └── common.yaml                 # 8 JSON:API schemas
├── src/
│   ├── generated/acquia-cms/
│   │   └── types.ts                    # Auto-generated types (1.6MB)
│   └── types/
│       └── acquia-cms.ts               # Organized exports
└── scripts/
    ├── finalize-spec.ts                # HTML cleanup, response codes
    └── fix-validation-errors.ts        # Duplicate consolidation

⚠️ WARNING: As of 2026-02-06, these files MAY NOT EXIST (audit found empty directories)

api_normalization

Location: /Users/flux423/Library/Mobile Documents/com~apple~CloudDocs/AgentPlatform/_REPOSITORIES/api_normalization

Acquia Source Files:

api_normalization/
├── examples/
│   └── acquia_source_jsonapi.json      # Original JSON:API spec
└── openapi.yml                         # Module's own OpenAPI spec

🚀 Phase 1: OpenAPI Spec Conversion (Week 1-2)

Status Check

BEFORE starting Phase 2+, verify Phase 1 is deployed:

# Check MR status
glab mr view 33 --repo blueflyio/agent-platform/api-schema-registry

# Check if files exist
cd "/Users/flux423/Library/Mobile Documents/com~apple~CloudDocs/AgentPlatform/_REPOSITORIES/api-schema-registry"
ls -la openapi/acquia-cms/

# Check worktree (if not merged)
find ~/.worktrees -name "*acquia*" -o -name "*77*"

# If files missing, check git history
git log --all --oneline --grep="acquia" -i

If Phase 1 NOT Deployed

Option A: Merge existing MR #33

# Check MR details
glab mr view 33 --repo blueflyio/agent-platform/api-schema-registry

# If approved, merge
glab mr merge 33 --repo blueflyio/agent-platform/api-schema-registry

# Pull latest
cd "/Users/flux423/Library/Mobile Documents/com~apple~CloudDocs/AgentPlatform/_REPOSITORIES/api-schema-registry"
git pull origin release/v0.1.x

Option B: Recreate work from original spec

# Source: api_normalization/examples/acquia_source_jsonapi.json
# Follow tasks 3-7 from COMPLETED-ACQUIA-SOURCE.md:
# 1. Clean HTML descriptions to Markdown (use turndown library)
# 2. Add missing response codes (201, 204, 400, 401, 403, 404, 422, 500)
# 3. Extract common JSON:API schemas
# 4. Generate types with openapi-typescript
# 5. Fix duplicate paths and parameter mismatches

🛡️ Product 1.1: Source Compliance Shield (Week 3-4)

Architecture

┌─────────────────────────────────────────────────────┐
│                   Client Request                     │
│    (e.g., GET /api/node/article?include=category)  │
└──────────────────┬──────────────────────────────────┘
                   │
                   v
┌─────────────────────────────────────────────────────┐
│              compliance-engine                       │
│  • Load Cedar policies                              │
│  • Evaluate request against policies                │
│  • Allow/Deny based on rules                        │
└──────────────────┬──────────────────────────────────┘
                   │ (if allowed)
                   v
┌─────────────────────────────────────────────────────┐
│            Acquia Source API                         │
│  • Process request                                  │
│  • Return JSON:API response                         │
└─────────────────────────────────────────────────────┘

Implementation Steps

Design Cedar Policies

// Example: Content Type Restrictions
permit(
  principal in Group::"content-editors",
  action == Action::"read",
  resource in ContentType::"article"
);

forbid(
  principal in Group::"anonymous",
  action == Action::"write",
  resource
);

Configure compliance-engine

// compliance-engine/src/acquia-source-config.ts
import { ComplianceEngine } from '@bluefly/compliance-engine';

const engine = new ComplianceEngine({
  policies: './policies/acquia-source.cedar',
  openapi: './openapi/acquia-cms/openapi-converted.yaml',
  upstream: 'https://[instance].source.acquia.com/api'
});

Deploy as Reverse Proxy

# Using agent-docker
cd agent-docker/deployments/nas/
docker-compose up compliance-shield

Test with Source Sandbox

# Get Source sandbox credentials from Acquia
export SOURCE_API_URL="https://sandbox.source.acquia.com/api"
export SOURCE_API_KEY="your-api-key"

# Test request through compliance-engine
curl -H "Authorization: Bearer $SOURCE_API_KEY" \
     http://localhost:3010/api/node/article

Deliverables

Cedar policy templates (5 policies)
Compliance Shield Docker image
Customer onboarding runbook
Pitch deck (10 slides)
Partnership proposal

Revenue Target: $300k ARR

🚀 Product 1.2: Source DevOps Accelerator (Week 5-6)

Architecture

┌─────────────────────────────────────────────────────┐
│           @bluefly/source-sdk (TypeScript)          │
│  • Auto-generated from OpenAPI spec                 │
│  • Zod validation for runtime safety                │
│  • Type-safe client (no any types)                  │
└──────────────────┬──────────────────────────────────┘
                   │
                   v
┌─────────────────────────────────────────────────────┐
│             GitLab CI/CD Pipeline                    │
│  • Fetch content from Source                        │
│  • Transform to code (Markdown, JSON)               │
│  • Run tests (Playwright)                           │
│  • Deploy to production                             │
└─────────────────────────────────────────────────────┘

Implementation Steps

Generate TypeScript SDK

# Use @hey-api/openapi-ts (NOT openapi-typescript-codegen)
cd api-schema-registry
npx @hey-api/openapi-ts \
  --input openapi/acquia-cms/openapi-converted.yaml \
  --output packages/source-sdk/src \
  --client axios

Add Zod Validation Layer

// packages/source-sdk/src/validation.ts
import { z } from 'zod';

export const ArticleSchema = z.object({
  type: z.literal('node--article'),
  id: z.string().uuid(),
  attributes: z.object({
    title: z.string(),
    body: z.string().optional()
  })
});

// Runtime validation
export function validateArticle(data: unknown) {
  return ArticleSchema.parse(data);
}

Create GitLab CI Templates

# gitlab_components/templates/acquia-source-ci.yml
include:
  - component: blueflyio/gitlab_components/acquia-source-deploy@1.0.0

stages:
  - fetch
  - transform
  - test
  - deploy

fetch-content:
  stage: fetch
  script:
    - npx @bluefly/source-sdk fetch --type article --output content/

test-content:
  stage: test
  script:
    - npx playwright test

Build Example Projects
- Content migration (Source → Git)
- CI/CD integration (auto-deploy on content change)
- Testing examples (Playwright + Source SDK)

Deliverables

@bluefly/source-sdk npm package
GitLab CI component
3 example projects
Documentation site (docs/)

Revenue Target: $270k ARR

🤖 Product 1.3: Source AI Content Agents (Week 7-8)

Architecture

┌─────────────────────────────────────────────────────┐
│                  agent-mesh                          │
│  • Coordinates 4 Acquia Source agents               │
│  • Routes requests to appropriate agent             │
│  • Aggregates results                               │
└──────────────────┬──────────────────────────────────┘
                   │
        ┌──────────┴──────────┬──────────┬──────────┐
        v                     v          v          v
┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│   Content    │  │     SEO      │  │  Taxonomy    │  │     DAM      │
│   Auditor    │  │  Optimizer   │  │   Manager    │  │  Coordinator │
└──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘

4 OSSA Agents

1. Content Auditor

Purpose: Analyze content quality, readability, accessibility

OSSA Manifest:

{
  "id": "acquia-source-content-auditor",
  "name": "Acquia Source Content Auditor",
  "version": "0.4.9",
  "agent_type": "analyzer",
  "access_tier": "tier_1_read",
  "inputs": [
    {
      "name": "content",
      "type": "node--article",
      "required": true
    }
  ],
  "outputs": [
    {
      "name": "audit_report",
      "type": "ContentAuditReport"
    }
  ]
}

2. SEO Optimizer

Purpose: Improve SEO scores (meta descriptions, keywords, structure)

Tasks:

Analyze meta descriptions (length, keywords)
Check heading structure (H1, H2, H3 hierarchy)
Suggest keyword improvements
Generate SEO-friendly slugs

3. Taxonomy Manager

Purpose: Organize tags, categories, auto-tag content

Tasks:

Analyze existing taxonomy structure
Suggest new tags/categories
Auto-tag content based on NLP analysis
Detect duplicate/similar terms

4. DAM Coordinator

Purpose: Sync Acquia DAM with Source content

Tasks:

Detect missing DAM assets
Suggest alt text for images
Optimize image formats (WebP, AVIF)
Track asset usage across content

Implementation Steps

Create OSSA Manifests

cd platform-agents/packages/@ossa/
mkdir acquia-source-agents
cd acquia-source-agents

# Create 4 manifests
touch content-auditor.json
touch seo-optimizer.json
touch taxonomy-manager.json
touch dam-coordinator.json

Implement Agents

// platform-agents/packages/@ossa/acquia-source-agents/src/content-auditor.ts
import { OSSAAgent } from '@bluefly/agentic-flows';
import { SourceSDK } from '@bluefly/source-sdk';

export class ContentAuditor extends OSSAAgent {
  async execute(input: ContentInput): Promise<AuditReport> {
    const sdk = new SourceSDK();
    const article = await sdk.getArticle(input.articleId);

    // Analyze content
    const readability = this.analyzeReadability(article.body);
    const accessibility = this.checkAccessibility(article);

    return {
      score: readability.score,
      issues: accessibility.issues,
      recommendations: this.generateRecommendations(readability, accessibility)
    };
  }
}

Deploy to agent-mesh

# Using agent-buildkit
buildkit agents deploy \
  --agent acquia-source-content-auditor \
  --target agent-mesh \
  --mesh-url http://localhost:3005

Test Agent Coordination

# Send request to agent-mesh
curl -X POST http://localhost:3005/api/agents/execute \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "acquia-source-content-auditor",
    "input": {
      "articleId": "uuid-here"
    }
  }'

Deliverables

4 OSSA agent manifests
4 agent implementations
Agent deployment guide
Marketplace listings
Pilot results report

Revenue Target: $72k ARR

📊 Success Metrics

Technical Metrics

Zero validation errors
100% type coverage (no any)
>90% test coverage
<100ms p95 response time (Compliance Shield)
Zero runtime errors (SDK)

Business Metrics

3 pilot customers (30 days)
$50k MRR committed (30 days)
15 paying customers (90 days)
$200k MRR (90 days)
Acquia partnership agreement (90 days)

🔧 Tools & Libraries

Required

@hey-api/openapi-ts - SDK generation
zod - Runtime validation
cedar-policy - Authorization policies
@bluefly/compliance-engine - Policy enforcement
@bluefly/agent-mesh - Agent orchestration
@bluefly/agentic-flows - OSSA agent framework

Optional

turndown - HTML to Markdown conversion
@playwright/test - E2E testing
vitest - Unit testing
@redocly/cli - OpenAPI validation

🎯 Elite Standards Checklist

Standard	Product 1.1	Product 1.2	Product 1.3
Use existing libraries	✅ cedar-policy	✅ @hey-api	✅ agentic-flows
Schema-first	✅ Cedar	✅ OpenAPI	✅ OSSA manifests
DRY principle	✅ Policies	✅ SDK	✅ Base agent class
SOLID principles	✅	✅	✅
Feature-based structure	✅	✅	✅
Zod validation	N/A (Cedar)	✅ REQUIRED	✅
Zero `any` types	✅	✅	✅
TDD	✅	✅	✅

Target Grade: A+ (all products)

Planning:

TODO/TODO-ACQUIA-SOURCE.md - Future work items
TODO/ARCHITECTURE.md - Strategic initiative
TODO/AGENTS.md - AI Content Agents
TODO/SECURITY.md - Compliance Shield

Completed:

COMPLETED/2026-02-05-acquia-source-phase1.md - Phase 1 report
COMPLETED/COMPLETED-ACQUIA-SOURCE.md - Detailed summary

Progress:

INPROGRESS/INPROGRESS-ACQUIA-SOURCE.md - Active work (currently empty)

📞 Support & Resources

GitLab Repos:

api-schema-registry: https://gitlab.com/blueflyio/agent-platform/api-schema-registry
compliance-engine: https://gitlab.com/blueflyio/agent-platform/compliance-engine
platform-agents: https://gitlab.com/blueflyio/platform-agents

Documentation:

Acquia Source: https://docs.acquia.com/source
Cedar Policy: https://www.cedarpolicy.com/
OSSA Spec: https://gitlab.com/blueflyio/openstandardagents

Partnership:

Acquia Partnership Team: partnerships@acquia.com
BlueFly Contact: tscola@bluefly.io

Created: 2026-02-06 Owner: All agents working on Acquia Source products Status: ACTIVE - Reference guide for all 3 products Next Update: After each product launch

Acquia Source Integration - Development Guide

Acquia Source Integration - Development Guide

🎯 Overview

The Opportunity

The Strategy

📁 Repository Structure

api-schema-registry

api_normalization

🚀 Phase 1: OpenAPI Spec Conversion (Week 1-2)

Status Check

If Phase 1 NOT Deployed

🛡️ Product 1.1: Source Compliance Shield (Week 3-4)

Architecture

Implementation Steps

Deliverables

🚀 Product 1.2: Source DevOps Accelerator (Week 5-6)

Architecture

Implementation Steps

Deliverables

🤖 Product 1.3: Source AI Content Agents (Week 7-8)

Architecture

4 OSSA Agents

1. Content Auditor

2. SEO Optimizer

3. Taxonomy Manager

4. DAM Coordinator

Implementation Steps

Deliverables

📊 Success Metrics

Technical Metrics

Business Metrics

🔧 Tools & Libraries

Required

Optional

🎯 Elite Standards Checklist

🔗 Related Documents

📞 Support & Resources