Architecture Guide

This document describes the architecture and design of the Celebration Marketing Buyer Intent Platform.

System overview

The platform is a multi-tenant SaaS application built on a three-tier integration architecture:

Core Application (Astro + PostgreSQL) — Multi-tenant lead management and campaign automation platform
n8n Automation Layer — Workflow automation for data ingestion, processing, and notifications
Directus CMS — Headless CMS for content management, AI prompts, and configuration

This integrated system provides a centralized solution for lead intelligence, segmentation, campaign automation, and real-time analytics with extensive workflow automation capabilities.

Integration architecture

Core Application (Astro + PostgreSQL)

Technology: Astro 5.x with SSR, PostgreSQL with Drizzle ORM

Primary responsibilities:

Multi-tenant SaaS platform with team-based access control
User authentication (JWT with HTTP-only cookies)
Lead management and deduplication
Campaign creation and QR code tracking
Real-time dashboard and analytics
Payment processing with Stripe
API endpoints for external integrations

Key features:

Server-side rendering for performance
HTMX for dynamic UI updates without page reloads
Type-safe database queries with Drizzle ORM
Role-based access control (RBAC)
Activity logging and audit trails

n8n Automation Layer

Technology: n8n workflow automation platform

Primary responsibilities:

Lead Ingestion — Automated data fetching from external sources (LeadPost API, SFTP, Email, Webhooks)
Lead Processing — Deduplication, enrichment, validation, and scoring
Segmentation — Automated segment calculation and monitoring
Campaign Automation — QR code generation, deployment, and follow-up sequences
Notifications — Alerts, daily summaries, and performance reports
Integration Monitoring — Health checks, rate limit monitoring, and error alerts

Workflow categories (23 total workflows):

Lead Ingestion (5 workflows) — API sync, SFTP sync, email processing, webhook receivers
Lead Processing (4 workflows) — Deduplication, enrichment, validation, scoring
Segmentation (4 workflows) — Automated calculation, size monitoring, geographic auto-creation
Campaign Automation (4 workflows) — QR generation, performance monitoring, follow-ups
Notifications (4 workflows) — Daily reports, real-time alerts, weekly digests
Integration Monitoring (3 workflows) — Health checks, API monitoring, data quality

Integration points:

Consumes platform REST API endpoints (/api/leads/import, /api/segments/recalculate, etc.)
Triggered via webhooks from platform (/webhook/lead-created, /webhook/alert-event)
Stores workflow results back to PostgreSQL via API
Sends notifications via email (SMTP), Slack, and SMS (Twilio)

Configuration:

// Environment variables in core platform (src/db/schema.ts)
n8nUrl: varchar('n8n_url', { length: 255 }),
n8nApiKey: varchar('n8n_api_key', { length: 255 }),

Helper functions (src/lib/n8n.server.ts):

trigger8n(endpoint: string, data: any)   // Generic webhook trigger
triggerAlert(data: any)                   // Alert notifications
triggerLeadCreated({ state, teamId })     // New lead events

Directus CMS

Technology: Directus headless CMS with Data Studio UI

Primary responsibilities:

Content Management — AI prompts, templates, and dynamic content
Configuration Storage — Global settings and API credentials
Media Management — Documents, images, and campaign assets
AI Prompt Library — Versioned prompt templates with placeholders
Settings Management — Feature flags and key-value configuration
Real-time Updates — WebSocket support for live data synchronization

Collections:

ai_prompts — AI prompt templates with system prompts and message examples
globals — Platform-wide credentials (Twilio, OpenAI, n8n URLs)
settings — Key-value configuration pairs
directus_files — Media library for documents and assets
directus_folders — Organizational structure for files

Integration points:

Platform consumes Directus REST API for configuration and content
Real-time WebSocket connection for live updates
Static token authentication for server-side requests
Rate-limited request queue (10 requests per 500ms)

Configuration:

// Environment variables (astro:env)
DIRECTUS_URL: process.env.DIRECTUS_URL
DIRECTUS_STATIC_TOKEN: process.env.DIRECTUS_STATIC_TOKEN
PUBLIC_DIRECTUS_URL: process.env.PUBLIC_DIRECTUS_URL

// Database storage (src/db/schema.ts)
directusUrl: varchar('directus_url', { length: 255 }),
directusToken: varchar('directus_token', { length: 255 }),

Client functions (src/lib/directus.ts):

getDirectusClient(token)          // Get authenticated client
getDirectusRealtimeClient()       // WebSocket client
getPrompts(tag)                   // Fetch AI prompts
executeFlow(flow, data, method)   // Trigger Directus flow
getGlobals()                      // Fetch global settings

Real-time features (src/components/shared/realtime/):

RealtimeManager.astro — WebSocket connection management
Live data updates without polling
Automatic reconnection on disconnect
Event-driven state synchronization

Data flow between systems

┌─────────────────────────────────────────────────────────────────┐
│                     EXTERNAL DATA SOURCES                         │
│  LeadPost API │ SFTP │ Email │ Webhooks │ CSV Upload │ Forms      │
└────────────────────────┬────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                     n8n AUTOMATION LAYER                          │
│  ┌──────────────────────────────────────────────────────────┐    │
│  │ Lead Ingestion → Processing → Enrichment → Validation     │    │
│  └──────────────────────────────────────────────────────────┘    │
└─────────────┬───────────────────────────────────┬───────────────┘
              │                                     │
              │ POST /api/leads/import              │ Notifications
              │ POST /api/segments/recalculate      │ Alerts & Reports
              │ POST /api/campaigns/*               │
              ▼                                     ▼
┌─────────────────────────────────────────────────────────────────┐
│                CORE APPLICATION (Astro + PostgreSQL)              │
│  ┌──────────────────────────────────────────────────────────┐    │
│  │ API Layer → Business Logic → Database (PostgreSQL)        │    │
│  │ Auth → Segmentation → Campaigns → QR Tracking             │    │
│  └──────────────────────────────────────────────────────────┘    │
└─────────────┬───────────────────────────────────────────────────┘
              │
              │ GET  /api configurations
              │ POST /api metrics
              │ WebSocket connection
              ▼
┌─────────────────────────────────────────────────────────────────┐
│                          DIRECTUS CMS                             │
│  ┌──────────────────────────────────────────────────────────┐    │
│  │ AI Prompts │ Settings │ Globals │ Media │ Content         │    │
│  │ Configuration │ Real-time Sync │ File Management          │    │
│  └──────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

Communication patterns

Platform → n8n:

Webhook triggers for events: /webhook/lead-created, /webhook/alert-event
Scheduled workflows run independently
Manual workflow triggers from platform UI (future)

n8n → Platform:

REST API calls: POST /api/leads/import, POST /api/segments/recalculate
Bearer token authentication via PLATFORM_API_KEY
Bulk operations with batch processing

Platform → Directus:

REST API: Read prompts, settings, globals, and files
Real-time WebSocket: Subscribe to live updates
GraphQL: Complex queries with relationships
Static token authentication

Directus → Platform:

Webhook triggers for content changes (optional)
Flow executions for automation (optional)

Security architecture

Authentication:

Platform: JWT tokens in HTTP-only cookies
n8n: Bearer token via N8N_API_KEY environment variable
Directus: Static token via DIRECTUS_STATIC_TOKEN

Data isolation:

Multi-tenant by teamId in all database queries
n8n workflows respect team boundaries via API
Directus content scoped by roles and permissions

API security:

All external API calls use HTTPS
API keys stored in environment variables
Rate limiting on Directus requests (10/500ms)
Request validation with Zod schemas
CORS configuration for allowed origins

Architecture layers

1. Presentation layer

Technology: Astro with HTMX and Alpine.js

Components:

Pages — Server-rendered pages in src/pages/
Components — Reusable UI components in src/components/
Layouts — Page layouts and templates in src/layouts/
Starwind UI — Custom component library similar to shadcn/ui

Key features:

Server-side rendering (SSR) for SEO and performance
HTMX for dynamic updates without full page reloads
Alpine.js for client-side interactivity
Responsive design with TailwindCSS

2. Application layer

Technology: Astro Server Actions and API Routes

Components:

Actions — Server actions in src/actions/ for form handling
API Routes — REST API endpoints in src/pages/api/
Workers — Background processing in workers/

Key features:

Type-safe server actions with Zod validation
RESTful API design
Background job processing
Error handling and logging

3. Business logic layer

Components:

Deduplication Engine — src/lib/deduplication.ts
Segmentation Engine — src/lib/segmentation.ts
Assignment Logic — src/lib/assignment.ts
QR Code Generation — src/lib/qr-code.ts
Validation — src/lib/validation.ts

Key features:

Modular, testable business logic
Confidence scoring for deduplication
JSON-based rule engine for segmentation
Capacity-based assignment algorithms

4. Data layer

Technology: PostgreSQL with Drizzle ORM

Components:

Schema — Database schema in src/db/schema.ts
Queries — Database queries in src/db/queries.ts
Migrations — Database migrations in src/db/migrations/

Key features:

Type-safe database queries
Optimized indexes for performance
Multi-tenant data isolation
JSONB support for flexible data storage

Data flow

Lead ingestion flow

External Source → Integration Worker → Validation → Normalization → Deduplication → Database

Integration Worker — Fetches data from external source (API, SFTP, Email, Webhook)
Validation — Validates data format and required fields
Normalization — Standardizes data format (email, phone, addresses)
Deduplication — Checks for duplicates and merges if found
Database — Stores lead in PostgreSQL

Lead processing flow

New Lead → Segmentation → Assignment → Campaign Deployment → QR Tracking

Segmentation — Evaluates lead against all active segments
Assignment — Determines which team/campaign to assign lead to
Campaign Deployment — Generates QR code and deploys campaign
QR Tracking — Tracks scans and updates engagement metrics

Campaign flow

Campaign Created → Segment Selected → Leads Assigned → QR Codes Generated → Deployment → Tracking

Campaign Creation — User creates campaign with target segment
Lead Assignment — Leads from segment are assigned to campaign
QR Generation — Unique QR codes generated for each lead
Deployment — Campaign content sent to leads
Tracking — QR scans tracked in real-time

Database schema

Core tables

teams — Multi-tenant organization unit. Each team has its own leads, segments, and campaigns.
users — User accounts with authentication credentials.
team_members — Junction table linking users to teams with roles.
leads — Core lead data with contact, company, geographic, and intent information.
integrations — Data source integrations (API, SFTP, Email, Webhook, CSV).
segments — Lead segments with JSON-based rules.
segment_leads — Junction table linking leads to segments.
campaigns — Marketing campaigns with target segments and QR codes.
qr_tracking_events — QR code scan events with metadata.
deduplication_audits — Audit trail for lead merges.

Relationships

teams (1) ──→ (N) leads
teams (1) ──→ (N) segments
teams (1) ──→ (N) campaigns
teams (1) ──→ (N) integrations

leads (N) ──→ (N) segments (via segment_leads)
segments (1) ──→ (N) campaigns
campaigns (1) ──→ (N) qr_tracking_events
leads (1) ──→ (N) qr_tracking_events

Multi-tenancy

Data isolation

All data is scoped by teamId
Database queries automatically filter by team
Users can only access their team’s data
Foreign keys ensure referential integrity

Team management

Teams are created during user signup
Team members can be invited via email
Role-based access control (Owner, Member)
Team settings and billing managed per team

Authentication & authorization

Authentication

JWT tokens stored in HTTP-only cookies
Session management via src/lib/session.server.ts
Password hashing with bcrypt
Middleware protects routes (src/middleware.ts)

Authorization

Team-based access control
Role-based permissions (Owner, Member)
Route-level protection
Action-level validation

Background processing

Workers

Workers are located in the workers/ directory:

Ingestion workers (workers/ingestion/):

csv-import.ts — CSV file processing
leadpost-api.ts — LeadPost API integration
buyer-intent-api.ts — Buyer Intent Provider integration

Segmentation workers (workers/segmentation/):

segment-worker.ts — Segment assignment and recalculation

Lead processing (workers/lead-processing/):

process-lead.ts — End-to-end lead processing workflow

Processing strategy

Synchronous — For small batches (< 100 leads)
Asynchronous — For large batches (via queue system in production)
Batch Processing — Process multiple leads in parallel
Error Handling — Retry logic with exponential backoff

Integration architecture

Integration types

API Integrations — REST API clients, authentication (Bearer, Basic, Header), rate limiting and retry logic, pagination support
SFTP Integrations — File-based data delivery, scheduled file downloads, CSV/JSON parsing
Email Integrations — IMAP email retrieval, attachment processing, automated parsing
Webhook Integrations — Real-time data delivery, signature verification, event handling
CSV Import — Manual file upload, column mapping, batch processing

Integration flow

Integration Config → Worker → Data Fetch → Validation → Normalization → Import

Security architecture

Data security

Encryption — Sensitive data encrypted at rest
HTTPS — All traffic encrypted in transit
SQL Injection — Protected by Drizzle ORM parameterized queries
XSS Protection — Astro’s built-in XSS protection
CSRF Protection — Session-based CSRF tokens

Access control

Authentication — Required for all protected routes
Authorization — Team-based data isolation
Role-Based Access — Owner vs. Member permissions
API Keys — Secure storage of integration credentials

Audit trail

Activity Logging — All user actions logged
Deduplication Audits — Merge history tracked
Integration Syncs — Sync history and errors logged

Performance optimization

Database optimization

Indexes — Composite indexes for common query patterns
Connection Pooling — PgBouncer or Neon Pooler
Query Optimization — Efficient joins and filters
JSONB Indexes — GIN indexes for array searches

Application optimization

Caching — HTTP caching headers
CDN — Static asset delivery
Lazy Loading — Components loaded on demand
Code Splitting — Astro’s automatic code splitting

Scalability

Horizontal Scaling — Stateless application servers
Database Scaling — Read replicas for analytics
Queue System — Background job processing (future)
Caching Layer — Redis for session storage (future)

Error handling

Error types

Validation Errors — Zod schema validation
Database Errors — Drizzle ORM error handling
Integration Errors — Retry logic with exponential backoff
Business Logic Errors — Custom error types

Error handling strategy

Try-Catch — Comprehensive error catching
Error Logging — All errors logged with context
User Feedback — Toast notifications for user-facing errors
Retry Logic — Automatic retries for transient errors

Monitoring & observability

Logging

Application Logs — Console logging for development
Error Tracking — Sentry or similar for production
Activity Logs — User actions tracked in database

Metrics

Performance Metrics — Response times, query performance
Business Metrics — Lead counts, conversion rates
System Metrics — CPU, memory, database connections

Alerts

Error Alerts — High error rates
Performance Alerts — Slow queries or responses
Integration Alerts — Failed syncs

Deployment architecture

Development environment

Core Platform:

Server: bun run dev on localhost:3000 (note: port 3000, not default Astro 4321)
Database: Local PostgreSQL or Neon development instance
Stripe: Test mode with Stripe CLI webhooks (stripe listen --forward-to localhost:3000/api/stripe/webhook)
Hot Reload: Astro dev server with HMR

n8n:

Development Instance: Local n8n via Docker or hosted development instance
Webhook Testing: ngrok or localhost tunnels for webhook testing
Workflow Development: n8n UI at http://localhost:5678 (default)
Environment Variables: .env file with test credentials

Directus:

Development Instance: Local Directus via Docker or hosted development instance
Data Studio: Directus admin UI for content management
Database: Separate PostgreSQL database or shared with platform (not recommended)
Static Token: Development token for API authentication

Production environment

Core Platform:

Hosting: Vercel (recommended), Cloudflare Pages, or self-hosted Node.js
Database: Neon (recommended), Supabase, or managed PostgreSQL
CDN: Automatic via hosting platform
SSL: Automatic HTTPS certificate management
Environment Variables: Production secrets in hosting platform dashboard
Build Command: bun run build
Output: ./dist/ directory with SSR functions

n8n:

Hosting Options: n8n Cloud (managed service, recommended); self-hosted on DigitalOcean, AWS, or Render; Docker deployment with persistent volumes
Database: Separate PostgreSQL for workflow data
Environment Variables: Production API keys and credentials
Webhook URLs: Public HTTPS endpoints for workflow triggers
Monitoring: Built-in execution history and error logs

Directus:

Hosting Options: Directus Cloud (managed service); self-hosted on DigitalOcean, AWS, or Render; Docker deployment
Database: Separate PostgreSQL for CMS data
File Storage: S3, DigitalOcean Spaces, or local storage
CDN: CloudFront or Cloudflare for asset delivery
Extensions: Custom interfaces and endpoints (if needed)

Deployment workflow

1. Core Platform Deployment:

# Build for production
bun run build

# Deploy to Vercel (example)
vercel --prod

# Or deploy to Cloudflare
npm run deploy

2. Database Setup:

# Run migrations
bun run db:migrate

# Seed initial data (first time only)
bun run db:seed

3. n8n Workflow Deployment:

Export workflows from development n8n instance
Import to production n8n instance via UI or API
Configure production credentials in n8n
Update environment variables (production API URLs)
Activate workflows

4. Directus Content Migration:

Export schema from development Directus
Import schema to production Directus
Migrate content (AI prompts, settings)
Update production URLs in globals collection
Configure CDN for file assets

Environment variables by system

Core Platform (.env):

# Database
DATABASE_URL=postgresql://...

# Authentication
AUTH_SECRET=xxx

# n8n Integration
N8N_URL=https://n8n.yourdomain.com
N8N_API_KEY=xxx

# Directus Integration
DIRECTUS_URL=https://cms.yourdomain.com
DIRECTUS_STATIC_TOKEN=xxx
PUBLIC_DIRECTUS_URL=https://cms.yourdomain.com

# Services
OPENAI_API_KEY=sk-xxx

n8n (Environment Variables):

# Platform API
PLATFORM_BASE_URL=https://app.yourdomain.com
PLATFORM_API_KEY=xxx

# Email
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=noreply@yourdomain.com
SMTP_PASSWORD=xxx

# Notifications
SLACK_WEBHOOK_URL=xxx
ADMIN_EMAIL=admin@yourdomain.com

# Integrations
LEADPOST_API_KEY=xxx
CLEARBIT_API_KEY=xxx
HUNTER_API_KEY=xxx

Directus (Environment Variables):

# Database
DB_CLIENT=postgres
DB_HOST=xxx
DB_PORT=5432
DB_DATABASE=directus
DB_USER=xxx
DB_PASSWORD=xxx

# Security
KEY=xxx
SECRET=xxx

# Admin
ADMIN_EMAIL=admin@yourdomain.com
ADMIN_PASSWORD=xxx

# Public URL
PUBLIC_URL=https://cms.yourdomain.com

# File Storage (S3 example)
STORAGE_LOCATIONS=s3
STORAGE_S3_DRIVER=s3
STORAGE_S3_KEY=xxx
STORAGE_S3_SECRET=xxx
STORAGE_S3_BUCKET=directus-files
STORAGE_S3_REGION=us-east-1

Multi-environment strategy

Environment tiers:

Development — Local development with test data
Staging — Production-like environment for testing
Production — Live customer-facing system

Data flow between environments:

Schema migrations: Development → Staging → Production
Content: Manual migration or sync tools
Workflows: Export/import via JSON files
Secrets: Never committed to version control

Monitoring & health checks

Core Platform:

Vercel Analytics for performance metrics
Error tracking via Sentry or similar
Uptime monitoring via Pingdom or UptimeRobot
Database connection pooling metrics

n8n:

Built-in execution history and logs
Custom health check workflows
Alert workflows for critical failures
Performance monitoring per workflow

Directus:

Built-in activity logs
API request monitoring
File storage usage metrics
Database query performance logs

Backup strategy

Database backups:

Automated daily backups via hosting provider
Point-in-time recovery (Neon, Supabase)
Manual backups before major migrations

n8n workflow backups:

Regular exports to version control (n8n/ directory)
Automated backup via n8n API
Store in S3 or Git repository

Directus content backups:

Schema snapshots in version control
Content exports via Directus SDK
File storage backups (S3 versioning)

Disaster recovery

Recovery Time Objective (RTO): < 4 hours
Recovery Point Objective (RPO): < 24 hours

Recovery procedures:

Restore database from latest backup
Redeploy core platform from Git
Import n8n workflows from backup
Restore Directus schema and content
Verify all integrations functional
Test critical user flows

Technology stack

Core platform

Frontend:

Astro — Web framework with SSR
HTMX — Dynamic UI updates without full page reloads
Alpine.js — Client-side interactivity
TailwindCSS 4.x — Utility-first CSS framework
Astro Icon — Icon components
Biome — Linter and formatter

Backend:

Astro SSR — Server-side rendering and API routes
Drizzle ORM — Type-safe database queries with PostgreSQL
Zod — Schema validation and type safety
Node.js/Bun — Runtime environment
JWT — Authentication with HTTP-only cookies

Database:

PostgreSQL — Primary transactional database
PostGIS — Geographic queries (optional)
JSONB — Flexible data storage for rules and metadata
Composite Indexes — Optimized query performance

Automation & workflow

n8n:

Workflow Engine — Visual workflow automation platform
23 Automated Workflows — Lead ingestion, processing, notifications
External Integrations — API, SFTP, Email, Webhook support
Data Enrichment — Clearbit, Hunter, Google Maps integrations
Monitoring — Health checks and error alerting
Scheduling — Cron-based workflow triggers

Content management

Directus:

Headless CMS — Data Studio UI for content management
REST & GraphQL API — Flexible data access
Real-time WebSocket — Live data synchronization
File Management — Media library and asset organization
AI Prompt Library — Versioned prompt templates
Configuration Store — Global settings and API credentials
Flows — Built-in automation capabilities

Infrastructure & services

Payments:

Stripe — Subscription billing and payment processing
Stripe Customer Portal — Self-service billing management
Stripe Webhooks — Event-driven subscription updates

Hosting & database:

Neon/Supabase — Managed PostgreSQL with connection pooling
Vercel/Cloudflare — Edge hosting and CDN
SSL/HTTPS — Automatic certificate management

Communications:

Twilio — SMS and voice messaging
SMTP — Email delivery (Gmail, SendGrid, etc.)
Slack — Team notifications and alerts

AI & analytics:

OpenAI — AI-powered content generation and analysis
Perplexity — Advanced search and research
Apify — Web scraping and data extraction

Future enhancements

Planned features

Core Platform:

Queue System — Redis or BullMQ for background job processing
API Rate Limiting — Token bucket algorithm for API throttling
Advanced Analytics — ClickHouse or Snowflake data warehouse integration
Multi-region — Geographic data distribution with edge functions
GraphQL API — Alternative to REST for complex queries
SSE/WebSockets — Enhanced real-time updates beyond current Directus integration

n8n Workflow Enhancements:

AI-Powered Workflows — GPT-4 integration for intelligent lead routing
A/B Testing Automation — Automated campaign testing and optimization
Predictive Analytics — ML models for lead scoring and conversion prediction
Advanced Deduplication — Machine learning-based duplicate detection
Multi-channel Orchestration — Coordinated email, SMS, and direct mail campaigns

Directus CMS Enhancements:

Custom Dashboards — Team-specific analytics dashboards
Content Versioning — Full version control for all content
Workflow Approvals — Content approval workflows
Multi-language Support — Internationalization for global teams
Advanced Permissions — Fine-grained role-based access control

Integration Enhancements:

CRM Bi-directional Sync — Real-time sync with Salesforce/HubSpot
Marketing Automation — Marketo, Pardot, and Eloqua integrations
Data Warehouse — BigQuery, Redshift integration for analytics
Webhook Retry Logic — Exponential backoff with dead letter queue
Event Sourcing — Complete audit trail with event replay capabilities

Scalability improvements

Database:

Read Replicas — Separate read replicas for analytics and reporting
Sharding — Horizontal partitioning by team ID for large-scale deployments
Caching Layer — Redis for session storage and query result caching
Connection Pooling — PgBouncer for connection management at scale

Application:

Microservices — Split workers into separate services with message queue
Edge Functions — Cloudflare Workers or Vercel Edge for global performance
CDN Optimization — Advanced caching strategies for static assets
Load Balancing — Multi-region deployment with geographic routing

Workflow Automation:

n8n Clustering — Multiple n8n instances with load balancing
Workflow Versioning — Track and rollback workflow changes
Performance Monitoring — Detailed metrics per workflow execution
Auto-scaling — Dynamic workflow execution scaling based on load

Architecture evolution

Current state (3-tier integration):

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Astro     │◄──►│     n8n     │◄──►│  Directus   │
│   + PG      │     │  Workflows  │     │    CMS      │
└─────────────┘     └─────────────┘     └─────────────┘

Future state (event-driven microservices):

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Frontend   │     │   API GW    │     │  n8n Auto   │
│  (Astro)    │◄──►│  (GraphQL)  │◄──►│ (Workflows) │
└─────────────┘     └─────────────┘     └─────────────┘
                          │                    │
                          ▼                    ▼
              ┌───────────────────────────────┐
              │      Message Queue (Redis)     │
              └───────────────────────────────┘
                          │
       ┌──────────────────┼──────────────────┐
       ▼                  ▼                  ▼
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  Lead Svc   │    │ Campaign Svc│    │  Analytics  │
│   + PG      │    │    + PG     │    │ (Warehouse) │
└─────────────┘    └─────────────┘    └─────────────┘
       │                  │
       └──────────┬───────┘
                  ▼
           ┌─────────────┐
           │  Directus   │
           │    CMS      │
           └─────────────┘

Technical debt & improvements

Code quality:

Comprehensive test coverage (unit, integration, E2E)
API documentation with OpenAPI/Swagger
Component documentation with Storybook
Performance profiling and optimization

DevOps:

CI/CD pipeline automation
Infrastructure as Code (Terraform/Pulumi)
Automated security scanning
Dependency update automation

Monitoring & observability:

Distributed tracing (OpenTelemetry)
Application Performance Monitoring (APM)
Log aggregation (ELK stack or similar)
Custom business metrics dashboards

Development guidelines

Code organization

Modular Design — Separate concerns into modules
Type Safety — TypeScript for all code
Error Handling — Comprehensive error handling
Testing — Unit and integration tests (future)

Best practices

DRY — Don’t repeat yourself
SOLID Principles — Object-oriented design principles
Security First — Security considerations in all code
Performance — Optimize for performance from the start