ai architecture
Drupal AI Architecture - Complete System Design
Version: 1.0.0 Last Updated: 2026-01-08 Status: Production
System Overview
Drupal 11 Application Layer
Content Management
Nodes, Comments, Users
Workflows (Content AI Publish)
AI Integration Layer
drupal/ai drupal/ai_
(Providers) agents
GitLab AI OSSA
Gateway Bridge
Provider Service
Automation Layer
drupal/eca drupal/
(Workflows) flowdrop
ECA AI Actions
Data Layer
PostgreSQL Vector DB
(Content) (Embeddings)
External Services
GitLab AI GitLab Agent Anthropic
Gateway Platform Claude API
Core Components
1. Provider Layer (drupal/ai)
- Purpose: Unified interface to 48+ AI providers
- Capabilities: Chat, embeddings, image generation, text-to-speech
- Custom Provider: GitLab AI Gateway integration
- Configuration: Token management, model selection, rate limiting
2. Agent Layer (drupal/ai_agents)
- Purpose: Stateful AI agents with tools and memory
- Capabilities: Multi-tool execution, context management, OSSA export
- Agent Types: Content moderator, taxonomy tagger, search assistant
- Integration: OSSA Bridge for GitLab Agent Platform deployment
3. Automation Layer (drupal/eca + drupal/flowdrop)
- Purpose: No-code/low-code AI workflows
- ECA: 500+ actions, 70+ conditions, 200+ events + AI actions
- FlowDrop: Visual DAG builder for AI workflows
- Bridge: FlowDrop ECA bidirectional conversion
4. Data Layer
- Content: PostgreSQL for structured data (nodes, users, config)
- Embeddings: Vector database (ChromaDB, Pinecone, Milvus)
- Search: Hybrid search (keyword + vector similarity)
- Caching: Redis for AI response caching
Data Flow
Example: Auto-Generate Meta Descriptions
1. User creates article node
2. ECA event: node_presave fires
3. ECA condition: field_meta_description is empty?
(yes)
4. ECA action: eca_ai:generate_text
- Provider: gitlab_ai_gateway
- Model: claude-sonnet-4
- Prompt: "Write 150-char meta for: [node:title]"
5. GitLab AI Gateway routes to Claude API
6. Response cached (1 hour TTL)
7. field_meta_description populated
8. Node saved with AI-generated meta
Module Dependencies
Required Modules
drupal/ai(1.2.5+) - AI provider frameworkdrupal/ai_agents(1.2.1+) - Agent managementdrupal/eca(2.0+) - Event-Condition-Action frameworkdrupal/key(1.17+) - Secure token storage
Recommended Modules
drupal/flowdrop(1.x-dev) - Visual workflow builderdrupal/search_api(1.35+) - Search integrationdrupal/redis(1.7+) - Caching backend
Custom Modules
ai_provider_gitlab- GitLab AI Gateway providerai_agents_ossa- OSSA bridge serviceeca_ai- AI action plugins for ECAflowdrop_eca_bridge- FlowDrop ECA converter
Security Architecture
1. Token Management
// Use drupal/key for secure storage $key_repository = \Drupal::service('key.repository'); $token = $key_repository->getKey('gitlab_ai_gateway')->getKeyValue();
2. OIDC Authentication
// Use short-lived OIDC tokens instead of PATs $oidc_token = getenv('CI_JOB_JWT');
3. Rate Limiting
- Per-user rate limits (60 requests/min)
- Per-project cost limits ($100/day)
- Token budget tracking in GitLab
4. Input Sanitization
// Sanitize all user input before AI prompts $safe_text = \Drupal\Component\Utility\Html::escape($user_input);
Performance Optimization
1. Response Caching
- Cache AI responses (Redis, 1-24 hour TTL)
- Cache embeddings (permanent, invalidate on content update)
- Cache agent execution results
2. Queue Processing
- Async processing for non-critical AI tasks
- Batch processing for bulk operations
- Priority queue for time-sensitive tasks
3. Database Optimization
- Index vector columns
- Partition large tables
- Use read replicas for search
Monitoring & Observability
Metrics to Track
- Token Usage: Tokens/day, cost/day, by provider
- Response Time: P50, P95, P99 latencies
- Error Rate: Failed requests, timeouts, rate limits
- Cache Hit Rate: Response cache effectiveness
- Queue Depth: Pending AI tasks
GitLab Integration
- Tracing: OpenTelemetry distributed tracing
- Logging: Structured logs to GitLab Logs
- Metrics: Prometheus metrics export
- Alerting: PagerDuty integration for critical errors
Deployment Architecture
Development Environment (DDEV)
# .ddev/config.yaml name: llm-platform type: drupal php_version: "8.3" webserver_type: nginx-fpm database: type: postgres version: "16" redis: enabled: true
Production Environment (Kubernetes)
# k8s deployment apiVersion: apps/v1 kind: Deployment metadata: name: drupal-ai-platform spec: replicas: 3 template: spec: containers: - name: drupal image: drupal:11-php8.3-fpm env: - name: GITLAB_AI_GATEWAY_TOKEN valueFrom: secretKeyRef: name: ai-credentials key: gitlab-token
Scaling Considerations
Horizontal Scaling
- Stateless Drupal pods (shared filesystem via NFS/S3)
- PostgreSQL read replicas
- Redis cluster for caching
- Vector DB sharding
Vertical Scaling
- PHP-FPM workers (16-32 per pod)
- PostgreSQL connection pooling (PgBouncer)
- Redis memory allocation (8GB+ per node)
Disaster Recovery
Backup Strategy
- Database: Daily full backup + hourly incremental
- Embeddings: Weekly full backup (slow-changing)
- Configuration: Git-based config management
- Files: S3 with versioning enabled
Recovery Procedures
- Restore PostgreSQL from latest backup
- Restore Redis from snapshot (if available)
- Rebuild vector embeddings from content (if needed)
- Redeploy Drupal pods from Docker images
Cost Management
Token Usage Optimization
- Cache aggressively (1-24 hour TTL)
- Use cheaper models for simple tasks (GPT-4o-mini vs Claude Opus)
- Batch similar requests
- Set per-project cost limits
Infrastructure Optimization
- Auto-scaling based on traffic patterns
- Spot instances for non-critical workloads
- Reserved instances for baseline capacity
References
- Phase 0 Audits:
DRUPAL-PROJECTS-INVENTORY.md,CODE-DUPLICATION-REPORT.md - Phase 1 Research:
modules/drupal-ai-integration-guide.md,modules/drupal-ai-agents-plugin-guide.md - Integration Guides:
integrations/gitlab-ai-gateway-drupal.md,integrations/ossa-bridge-drupal.md