Skip to main content

Drupal Development Documentation

Drupal Development Documentation

Separation of Duties: See Separation of Duties - Drupal modules are responsible for Drupal-specific functionality. They do NOT own agent manifests, execution, or OSSA spec.

Complete developer guides for Drupal module development in the LLM Platform ecosystem.

Overview

This documentation provides comprehensive guides for developing Drupal modules, recipes, and OSSA-compliant AI agents for the LLM Platform.

Epic 73: Drupal Canvas Automation Platform

Epic 73 — Contrib-first migration + page-building automation. Use Drupal AI and Tool API only (ai, tool, tool_ai_connector, ai_automators); no custom LLM or migration engine code. Contract: migration.graph.v1. All modules follow Drupal coding standards, security best practices, and OSSA compliance requirements.

Core Development Guides

1. [object Object]

Complete guide for developing custom Drupal modules:

  • Module structure and organization
  • Development workflow
  • OSSA compliance requirements
  • Service definitions and dependency injection
  • Entity definitions and plugin system
  • API endpoints (REST, GraphQL, JSON:API)
  • Testing with PHPUnit
  • Deployment procedures

Source Location: $LLM_ROOT/all_drupal_custom/modules/MODULE_NAME/

2. [object Object]

Guide for creating and managing Drupal recipes:

  • Recipe structure and YAML format
  • Sub-recipe system for modular components
  • Recipe validation and testing
  • Deployment workflows
  • Recipe onboarding module integration
  • LLM Platform and Secure Drupal recipes

Source Location: $LLM_ROOT/all_drupal_custom/recipes/recipe_name/

3. [object Object]

Drupal-OSSA integration guide:

  • OSSA specification and manifest structure
  • Agent types (Worker, Coordinator, Observer, Specialist)
  • Tool system and definitions
  • Security model and isolation levels
  • Deployment to Kagent, LibreChat, and other platforms
  • Multi-platform agent deployment

4. [object Object]

Coding standards and quality tools:

  • PHPCS configuration and usage
  • PHPStan static analysis
  • Design taste validation
  • Common violations and fixes
  • Auto-fixing with BuildKit
  • Pre-commit hooks and CI/CD integration

Quick Reference

Essential Commands

# Module development
buildkit drupal module:create MODULE_NAME
buildkit drupal sync --modules
buildkit drupal phpcs MODULE_PATH --fix
buildkit drupal taste MODULE_PATH

# Recipe management
drush recipe recipes/RECIPE_NAME
drush recipe-onboarding:validate recipes/RECIPE_NAME

# OSSA validation
ossa validate .agents/AGENT_NAME/manifest.json
buildkit agents list

# Code quality
buildkit golden test
buildkit golden audit
buildkit golden optimize

Module Documentation

AI & Agent Orchestration

Core Platform Services

JSON:API & REST Integration

Security & Compliance

  • Gov Compliance - FedRAMP, HIPAA, GDPR, FISMA, and NIST compliance framework

Analytics & Monitoring

AI Providers (Backlog)

Content Management (Backlog)

  • DITA CCMS - Enterprise DITA XML authoring and publishing framework

Module Status

Active Modules (Production)

Located in $LLM_ROOT/all_drupal_custom/modules/:

  1. ai_agentic_workflows
  2. ai_agents_orchestra
  3. ai_agents_client
  4. ai_agents_ossa
  5. ai_agents_kagent
  6. ai_agents_claude
  7. ai_agents_cursor
  8. ai_agents_marketplace
  9. alternative_services
  10. api_normalization
  11. code_executor
  12. gov_compliance
  13. mcp_registry
  14. recipe_onboarding
  15. charts_ai_analytics

Backlog Modules (In Development)

Located in $LLM_ROOT/all_drupal_custom/modules/_Backlog/:

  1. ai_provider_apple
  2. ai_provider_langchain
  3. dita_ccms

Development Workflow

1. Edit Source Files

Edit modules in source location:

$LLM_ROOT/all_drupal_custom/modules/MODULE_NAME/

DO NOT EDIT deployment location (Composer-managed):

$LLM_ROOT/llm-platform/web/modules/custom/MODULE_NAME/

2. Sync to Deployment

# Preview changes
buildkit drupal sync --modules --dry-run

# Apply changes
buildkit drupal sync --modules

3. Quality Checks

# PHPCS validation
buildkit drupal phpcs modules/custom/MODULE_NAME --fix

# Design taste
buildkit drupal taste modules/custom/MODULE_NAME

# Run tests
buildkit golden test

# Security audit
buildkit golden audit

4. Deployment

# Sync modules
buildkit drupal sync --modules

# Export config
buildkit drupal config:export

# Deploy
buildkit golden deploy --env dev

Employment Protection

All modules include .claude/CLAUDE.md with employment protection:

## EMPLOYMENT PROTECTION ACTIVE
- Claude Code BLOCKED from development branch
- AI attribution BLOCKED in commits
- Feature branch workflow ENFORCED

##  TOKEN OPTIMIZATION MANDATORY
Before writing ANY code > 500 tokens:
- Check: buildkit agents list
- Use: buildkit agents spawn --type worker

Best Practices

1. OSSA Compliance

All AI agent modules must include:

  • .agents/AGENT_NAME/manifest.json - OSSA manifest
  • Validation with ossa validate
  • Security isolation and permissions
  • Tool definitions following OSSA spec

2. Code Quality

  • Follow Drupal coding standards
  • Use PHPCS and PHPStan
  • Write PHPUnit tests for critical functionality
  • Document all public APIs
  • Use dependency injection

3. Security

  • Validate all inputs
  • Sanitize all outputs
  • Use permissions properly
  • Implement audit logging
  • Follow government compliance requirements

4. Performance

  • Enable caching where appropriate
  • Use queues for long-running tasks
  • Lazy-load services
  • Optimize database queries
  • Monitor resource usage

Resources

Official Documentation

Drupal Resources

Community

Contributing

When contributing to any module:

  1. Create GitLab issue first
  2. Use git worktrees for feature branches
  3. Follow coding standards
  4. Write tests
  5. Update documentation
  6. Create MR via GitLab issue page

Support

For questions or issues:

  • Check module-specific documentation
  • Review GitLab Wiki
  • Create GitLab issue
  • Contact: security@bluefly.io

Last Updated: 2025-01-22 Drupal Compatibility: 10.3+, 11.0+ OSSA Compliant: Yes