CDN-arium

CDN-arium is a high-concurrency image origin shield designed for Lazy Transformation. It serves as an intelligent gateway that generates image variations (resize, crop, filter) on-demand, reducing storage costs and simplifying the media pipeline.

🚀 Key Features

• On-Demand Processing: Variations are generated only when first requested (Read-Through pattern).
• Control Plane Architecture: Uses 307 Redirects to offload byte-delivery to S3/CloudFront.
• Microservice Design: Decouples API (Uploader), Shield (Gateway), and Worker (Processor).
• Atomic Locking: Prevents thundering herd problems for new variation requests.
• Cloud Native: Built for AWS (S3, DynamoDB, SQS) with easy local simulation via Docker.

🛠 Tech Stack

• Language: Go
• Framework: Gin (HTTP)
• Infrastructure: AWS S3 (Storage), DynamoDB (State), SQS (Queue), Terraform (IaC).
• Image Processing: ImageMagick (simulated/exec).

📖 Core Concepts

The system operates as a Control Plane. Instead of proxying images, it directs clients to the final content location.

• Lazy Loading: If a variation doesn't exist, the Shield triggers an async job and redirects the user to a placeholder.
• State Machine: Tracks image status across PENDING, READY, and FAILED states.

For a deep dive into the system design, see docs/ARCHITECTURE.md and the Visual Workflows (Mermaid).

🚦 Getting Started

1. Prerequisites

• Go 1.20+
• Docker & Docker Compose

2. Quick Start (Docker)

The entire stack can be launched with one command:

docker compose up --build

• Back-office Portal (BOP) API: http://localhost:8081 (Write Path)
• Origin Shield: http://localhost:8080 (Read Path)

3. AWS Infrastructure

For production deployment, see AWS Setup Guide and Terraform Instructions.

💻 API Usage

Upload an Image

curl -X POST http://localhost:8081/api/v1/upload -F "image=@photo.jpg"

Request a Variation (Dynamic Resize)

# Shield will trigger worker and redirect to S3 (or spinner)
curl -L -O http://localhost:8080/img/101/resize:w=200,h=200

Supported Ops: resize, crop, rotate, blur, grayscale. See Flexible Variations Docs.

🏗 Project Structure

.
├── cmd/                # Entry points (api, worker, shield)
├── internal/
│   ├── infrastructure/ # AWS Adapters (S3, DynamoDB, SQS)
│   ├── interfaces/     # Domain Ports
│   └── services/       # Core Business Logic
├── pkg/models/         # Shared Schema
└── docs/               # Manuals & Architecture

✅ TODO

• CI/CD: GitHub Actions pipeline.
• Testing: Integration tests with testcontainers-go.
• Security: Implement JWT Auth for BOP API.
• Observability: Add Structured Logging & OpenTelemetry.