platform-marketing-content/docs/ARCHITECTURE.md

id	title	type	project	version	updated_date
ARCHITECTURE	Architecture	Documentation	platform_marketing_content	1.0.0	2026-01-04

Architecture

Overview

Platform Marketing Content (PMC) es una plataforma de generación y gestión de contenido de marketing asistida por inteligencia artificial. Integra ComfyUI para generación de imágenes AI y modelos LLM para contenido textual, ofreciendo un CMS completo para equipos de marketing.

La arquitectura sigue un patrón de aplicación web full-stack con NestJS en backend y React en frontend, con integraciones a servicios de IA para automatización de contenido.

Tech Stack

• Backend: NestJS 10+ + TypeScript 5.3+
• Frontend: React + TypeScript + Tailwind CSS + Vite
• Database: PostgreSQL 16 (pmc_dev)
• Cache: Redis 7
• Storage: MinIO (S3-compatible)
• AI Art: ComfyUI (Stable Diffusion, FLUX)
• LLM: Integration with OpenAI, Claude, local models
• Auth: JWT + Passport.js
• Real-time: Socket.IO (Bull queues for async jobs)

Module Structure

platform_marketing_content/
├── apps/
│   ├── backend/                    # NestJS API
│   │   └── src/
│   │       ├── modules/            # Feature modules
│   │       │   ├── auth/           # Authentication (JWT, local, OAuth)
│   │       │   ├── tenants/        # Multi-tenant management
│   │       │   ├── projects/       # Marketing projects
│   │       │   ├── assets/         # Digital assets (images, videos)
│   │       │   ├── generation/     # AI content generation
│   │       │   ├── automation/     # Workflow automation
│   │       │   ├── crm/            # CRM integration
│   │       │   └── analytics/      # Analytics & reporting
│   │       ├── common/             # Shared code
│   │       │   ├── decorators/     # Custom decorators
│   │       │   ├── filters/        # Exception filters
│   │       │   ├── guards/         # Auth guards
│   │       │   ├── interceptors/   # HTTP interceptors
│   │       │   └── pipes/          # Validation pipes
│   │       ├── config/             # Configuration
│   │       ├── app.module.ts       # Root module
│   │       └── main.ts             # Bootstrap
│   │
│   └── frontend/                   # React SPA
│       └── src/
│           ├── modules/            # Feature modules
│           │   ├── auth/           # Login, register
│           │   ├── dashboard/      # Main dashboard
│           │   ├── projects/       # Project management
│           │   ├── assets/         # Asset library
│           │   ├── generation/     # AI generation UI
│           │   ├── campaigns/      # Marketing campaigns
│           │   └── analytics/      # Analytics dashboard
│           ├── shared/             # Shared components
│           │   ├── components/     # UI components
│           │   ├── hooks/          # Custom hooks
│           │   └── utils/          # Utilities
│           └── lib/                # Libraries
│
├── database/                       # Database
│   ├── schemas/                    # Schema definitions
│   └── migrations/                 # Database migrations
│
├── docs/                           # Documentation
└── orchestration/                  # Agent orchestration

Database Schemas

Core Schemas (6 schemas)

Schema	Purpose	Key Tables
auth	Authentication & users	users, sessions, oauth_accounts
tenants	Multi-tenant management	tenants, tenant_settings
projects	Marketing projects	projects, campaigns, schedules
assets	Digital asset management	assets, tags, collections
generation	AI generation	generation_jobs, templates, workflows
analytics	Metrics & reporting	events, conversions, performance

Data Flow Architecture

┌──────────────┐
│   Frontend   │ (React SPA - Port 3110)
│  (Browser)   │
└──────┬───────┘
       │ HTTP/WebSocket
       ▼
┌─────────────────────────────────────────────┐
│      Backend API (NestJS - Port 3111)       │
│  ┌─────────────────────────────────────┐   │
│  │  Controllers (REST Endpoints)       │   │
│  └────────┬────────────────────────────┘   │
│           ▼                                  │
│  ┌─────────────────────────────────────┐   │
│  │  Services (Business Logic)          │   │
│  └────────┬──────────────┬─────────────┘   │
│           │              │                  │
│           ▼              ▼                  │
│  ┌──────────────┐  ┌──────────────┐        │
│  │ Repositories │  │  Bull Queue  │        │
│  │  (TypeORM)   │  │  (Redis)     │        │
│  └──────┬───────┘  └──────┬───────┘        │
└─────────┼──────────────────┼────────────────┘
          │                  │
          ▼                  ▼
┌─────────────────┐  ┌──────────────┐
│   PostgreSQL    │  │    Redis     │
│   (Database)    │  │   (Cache)    │
└─────────────────┘  └──────────────┘

┌──────────────────────────────────────────┐
│      AI Services (External)              │
│  ┌──────────────┐  ┌──────────────┐     │
│  │   ComfyUI    │  │   LLM API    │     │
│  │  (Port 8188) │  │  (OpenAI)    │     │
│  └──────────────┘  └──────────────┘     │
└──────────────────────────────────────────┘

┌──────────────┐
│    MinIO     │ (S3-compatible storage)
│  (Port 9000) │
└──────────────┘

AI Content Generation Flow

User requests content generation
    ↓
Frontend → POST /api/generation/create
    ↓
Backend validates request
    ↓
Create generation_job (status: pending)
    ↓
Add to Bull queue (async processing)
    ↓
Worker picks up job
    ↓
    ├─→ Text generation: Call LLM API (GPT-4, Claude)
    │   ↓
    │   Save to database
    │
    └─→ Image generation: Call ComfyUI API
        ↓
        Upload to MinIO
        ↓
        Save metadata to database
    ↓
Update job status (completed/failed)
    ↓
WebSocket notification to frontend
    ↓
User sees generated content

Key Design Decisions

1. NestJS Framework

Decision: Usar NestJS en lugar de Express.js básico.

Rationale:

• Arquitectura modular out-of-the-box
• Dependency injection incorporado
• TypeScript first-class support
• Decorators para routing y validation
• Integración nativa con TypeORM, Bull, WebSockets

Trade-off: Curva de aprendizaje mayor, pero mejor estructura para proyectos grandes

2. Bull Queue for Async Processing

Decision: Procesar generaciones de IA en background con Bull.

Rationale:

• Generaciones pueden tardar minutos (especialmente imágenes)
• No bloquear requests HTTP
• Retry automático si falla
• Priorización de jobs
• Dashboard de monitoreo

Implementation:

// generation.processor.ts
@Processor('generation')
export class GenerationProcessor {
  @Process('generate-image')
  async handleImageGeneration(job: Job) {
    const { prompt, settings } = job.data;

    // Call ComfyUI
    const result = await this.comfyUIService.generate(prompt, settings);

    // Upload to MinIO
    const url = await this.storageService.upload(result.image);

    // Save to database
    await this.generationRepository.update(job.data.id, {
      status: 'completed',
      resultUrl: url
    });
  }
}

3. MinIO for Object Storage

Decision: MinIO como almacenamiento S3-compatible en lugar de filesystem.

Rationale:

• Compatible con S3 (fácil migración a AWS S3 en producción)
• Versioning de assets
• Metadata y tags
• Pre-signed URLs para acceso controlado
• Replicación y backup

4. ComfyUI Integration

Decision: Integrar ComfyUI para generación de imágenes AI.

Rationale:

• Workflow visual poderoso
• Múltiples modelos (Stable Diffusion, FLUX, etc.)
• Control fino sobre generación
• Open-source y self-hosted
• API REST para integración

Alternative: Usar APIs directas (Replicate, Stability AI) - más simple pero menos flexible

5. Multi-Tenant Architecture

Decision: Soporte multi-tenant a nivel de aplicación.

Rationale:

• SaaS-ready desde el inicio
• Aislamiento de datos por tenant
• Diferentes planes y límites por tenant
• Escalable para múltiples clientes

Implementation: Similar a ERP-Suite (tenant_id en cada tabla, RLS opcional)

6. Repository Pattern with TypeORM

Decision: Usar Repository Pattern en lugar de Active Record.

Rationale:

• Mejor separación de concerns
• Facilita testing (mock repositories)
• Migrations automáticas (development)
• Type-safe queries

Dependencies

Critical Dependencies

Dependency	Purpose	Criticality
NestJS	Backend framework	CRITICAL
TypeORM	ORM	CRITICAL
PostgreSQL	Database	CRITICAL
Redis	Cache, queues	HIGH
Bull	Job queues	HIGH
MinIO	Object storage	MEDIUM
ComfyUI	Image generation	MEDIUM

External Services

• ComfyUI: Image generation (local or cloud)
• OpenAI/Claude: Text generation
• MinIO: Object storage (S3-compatible)
• Redis: Caching and job queues

Security Considerations

• Authentication: JWT with refresh tokens
• Authorization: Role-based (admin, user, viewer)
• Multi-tenancy: tenant_id isolation
• File Upload: Validation (type, size, malware scan)
• API Rate Limiting: Per tenant
• CORS: Configured for frontend origin
• Input Validation: Class-validator on DTOs
• SQL Injection: TypeORM parameterized queries

Performance Optimizations

Caching Strategy

• Redis: Cache generation results, frequently accessed assets
• TTL: Configurable per resource type
• Invalidation: Event-based

Database

• Indexes on frequently queried columns
• Connection pooling
• Pagination on all list endpoints
• Lazy loading of relations

Asset Delivery

• CDN for static assets (future)
• Image optimization (resize, compress)
• Pre-signed URLs with expiration

Deployment Strategy

Current: Development environment

Ports:

• Frontend: 3110
• Backend: 3111
• MinIO API: 9000
• MinIO Console: 9001
• ComfyUI: 8188

Future Production:

• Docker containers
• Kubernetes orchestration
• AWS S3 for storage
• CloudFront CDN
• Managed PostgreSQL (RDS)
• Managed Redis (ElastiCache)

Monitoring & Observability

Planned:

• NestJS Logger
• Error tracking (Sentry)
• Performance monitoring (Datadog/New Relic)
• Bull Board for queue monitoring
• Database monitoring

Feature Modules

Auth Module

• JWT authentication
• OAuth2 (Google, GitHub)
• Password reset
• Email verification
• Role-based access control

Tenants Module

• Tenant management
• Settings & configuration
• Usage tracking
• Plan limits enforcement

Projects Module

• Marketing projects
• Campaigns
• Schedules
• Team collaboration

Assets Module

• Digital asset library
• Tags and collections
• Search and filtering
• Version control
• Sharing and permissions

Generation Module

• AI text generation (GPT-4, Claude)
• AI image generation (ComfyUI)
• Template management
• Workflow automation
• Generation history

Automation Module

• Scheduled generation
• Batch operations
• Webhooks
• API integrations

CRM Module

• Contact management
• Segment creation
• Campaign targeting
• Email integration

Analytics Module

• Performance metrics
• Conversion tracking
• Custom reports
• Dashboards

Integration Points

ComfyUI

API Endpoints:

• POST /prompt - Submit generation job
• GET /history - Get job status
• GET /view - Retrieve generated image

Workflow:

1. Build workflow JSON
2. Submit to ComfyUI
3. Poll for completion
4. Download result
5. Upload to MinIO

LLM APIs

OpenAI:

const completion = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [
    { role: 'system', content: 'You are a marketing content writer' },
    { role: 'user', content: prompt }
  ]
});

Claude:

const message = await anthropic.messages.create({
  model: 'claude-3-opus-20240229',
  max_tokens: 1024,
  messages: [{ role: 'user', content: prompt }]
});

MinIO

// Upload file
await minioClient.putObject(
  'pmc-assets',
  fileName,
  fileBuffer,
  fileSize,
  { 'Content-Type': mimeType }
);

// Get pre-signed URL
const url = await minioClient.presignedGetObject(
  'pmc-assets',
  fileName,
  24 * 60 * 60  // 24 hours
);

Future Improvements

Short-term

• Implement real-time collaboration
• Add more AI models
• Improve asset search (full-text)
• Mobile responsive UI

Medium-term

• Video generation support
• Social media scheduling
• A/B testing for content
• Brand kit management

Long-term

• Marketplace for templates
• White-label solution
• Multi-language support
• Advanced analytics & ML insights

References

• CMS Guide
• API Documentation
• Contributing Guide
• NestJS Documentation
• ComfyUI API