Architecture & Design Rationale

Technical decisions and architectural patterns behind the WDG AI Development Environment.

Architecture Philosophy

Local-First Design

The system uses local embeddings and vector search instead of cloud APIs. This architectural decision addresses several technical requirements:

Data Privacy

• Code never leaves local machine
• No external API calls for indexing or search
• Compliant with GDPR/HIPAA requirements for client projects
• Full control over what gets indexed

Operational Independence

• Functions without internet connectivity
• No rate limits or quotas
• No dependency on third-party service availability
• Predictable performance characteristics

Git-Driven Knowledge Base

Indexing triggers on git commits rather than file saves or continuous monitoring.

Technical Rationale:

• Ensures only stable, committed code enters the knowledge base
• Creates versioned knowledge that maps to git history
• Leverages existing developer workflow (git hooks)
• Prevents indexing of temporary/experimental code
• Enables team knowledge sync via git pull

Trade-offs:

• Uncommitted changes not searchable (intentional)
• Requires git commit for index updates (workflow integration)
• Hook failures may block commits (can be bypassed)

Vector Database Design

Uses Qdrant for vector storage with collection-per-project isolation.

Technical Benefits:

• Efficient similarity search with HNSW algorithm
• Rich metadata filtering capabilities
• Project isolation via collections
• Docker-friendly deployment
• Python client with async support

Collection Strategy:

wdg_framework       → Wikit framework (core, theme, blocks)
platform            → Platform code (CLI, MCP, indexer)
project_{name}      → Project-specific code

Docker Compose Architecture

All services run in containers with defined networking.

services:
  wordpress:    # One per project (isolated containers)
  mysql:        # Shared container, separate databases
  vector-db:    # Shared Qdrant instance
  mcp-server:   # Shared MCP API server
  nginx:        # Reverse proxy

Design Decisions:

• One WordPress container per project → Full isolation
• Shared MySQL container, separate databases → Resource efficiency
• Shared vector DB → Centralized knowledge
• Shared MCP server → Single API endpoint
• Nginx proxy → SSL termination, routing

Traditional WordPress Development

Setup Comparison

Standard Setup:

Manual process requiring multiple steps:

• Install MAMP/Local
• Configure virtual host
• Download WordPress
• Configure database
• Install Wikit manually
• Set up SSL
• Configure PHP

WDG Setup:

# Automated via Docker Compose
wdg create project-name --init-wikit
# WordPress + MySQL + SSL + Wikit ready

Technical Advantages:

• Infrastructure as code (docker-compose.yml)
• Reproducible environments
• Version-controlled configuration
• Automated SSL certificate generation
• Consistent PHP/MySQL versions

MCP Integration Rationale

Why Model Context Protocol?

The system uses FastMCP instead of REST APIs or GraphQL for AI tool integration.

Technical Advantages:

• Standardized tool schema for AI agents
• Built-in parameter validation
• Multiple transport options (STDIO, SSE, HTTP)
• Natural language tool descriptions
• Type safety via Pydantic models

vs REST API:

• MCP tools self-document for AI consumption
• No need for API client libraries
• Standardized error handling
• Better AI agent integration

vs Direct Database Access:

• Abstraction layer for complex queries
• Business logic in tools, not AI prompts
• Controlled access to data
• Easier to modify backend

Transport Options

The MCP server supports multiple transport mechanisms:

STDIO Transport:

• Used for Claude Code integration via docker exec
• Process-based communication
• Single client per process

HTTP Server:

• Runs on port 8765 for general API access
• Supports multiple concurrent clients
• Standard REST API interface

Wikit Framework Integration

Pre-Indexed Framework Knowledge

The system indexes Wikit framework components separately from project code.

Shared Collections:

• wdg_framework → All Wikit components (core, theme, blocks, facets)
• platform → Platform code (CLI, MCP server, indexer)

Project Collections:

• project_{name} → Project-specific code and customizations

Capabilities:

• New projects instantly have framework knowledge
• Block discovery without reading source
• Pattern recognition across framework
• Inheritance-aware search (finds base classes)

Semantic Search for Blocks

Traditional approach:

ls wikit-theme/block-editor/blocks/
# 60+ directories, which one?

Semantic search (via AI assistant):

# When you ask: "Find an image comparison slider"
# Your AI assistant calls:
search_wikit_blocks("image comparison slider")
# Returns: image-comparison block with props

Technical Implementation:

• Block metadata embedded: name, description, props, example usage
• Vector search finds conceptually similar blocks
• Returns actual implementation location
• Includes prop types and default values

WordPress-Specific Design

Custom Post Type Patterns

Pre-indexed base classes with common patterns:

WDG\Core\PostType → Base post type class
WDG\Core\Taxonomy → Base taxonomy class
WDG\Core\PostTypeTerm → Cross-reference

Search Capabilities:

• Find all post types extending base class
• Locate taxonomy registrations
• Discover meta field patterns
• Identify REST API customizations

Security Pattern Recognition

Indexed security functions and patterns:

// System knows these patterns
wp_verify_nonce()       → Nonce verification
sanitize_text_field()   → Input sanitization
esc_html()              → Output escaping
$wpdb->prepare()        → SQL preparation
current_user_can()      → Capability checks

Search Examples:

• "Show unescaped output" → Finds potential XSS
• "Find direct SQL" → Locates unprepared queries
• "Missing nonce checks" → Security audit

Development Workflow Integration

Git Hook Integration

Post-commit hook pipeline:

1. Code committed
2. post-commit hook runs
   - Detects repository type (framework/project)
   - Triggers indexer service
   - Extracts changed files
   - Generates embeddings
   - Updates vector DB
3. Indexing completes in background

Design Rationale:

• Automatic knowledge updates on commit
• No manual index commands required
• Runs in background (non-blocking)
• Scoped to changed files only (efficient)

Multi-Project Management

Each project gets:

• Isolated WordPress installation
• Separate MySQL database
• Own vector collection
• Dedicated container network

Shared Resources:

• Vector database service
• MCP server instance
• Nginx proxy
• Base Wikit collections

Trade-offs:

• Disk space: ~500MB per project
• Memory: ~200MB per running project
• Network: Isolated, no cross-contamination
• Knowledge: Shared base, isolated projects

System Requirements Rationale

Minimum Specifications:

RAM: 8GB minimum
  - Docker services: 2GB
  - Vector DB: 1GB
  - WordPress instances: 1GB (2 projects)
  - OS + tools: 2GB
  - Buffer: 2GB

Disk: 20GB minimum
  - Docker images: 5GB
  - Vector DB: 2GB
  - Projects (3): 1.5GB
  - System: 5GB
  - Buffer: 6.5GB

CPU: 4 cores recommended
  - Embedding generation: 1-2 cores
  - Vector search: 1 core
  - WordPress: 1 core
  - System: 1 core

Design Constraints

What This System Is:

• Local WordPress development platform
• AI-powered code search for committed code
• Wikit framework learning tool
• Multi-project management system

What This System Is Not:

• Production hosting environment
• Code completion engine (use Copilot for that)
• Real-time indexing system (git-driven only)
• General-purpose development tool (WDG Wikit WordPress specific)

Technical Limitations

Known Constraints:

• Embedding model fixed (sentence-transformers)
• Git-based updates only (uncommitted code not indexed)
• Docker required (no native installation)
• WordPress-specific (not for generic projects)
• Single-user focused (no built-in collaboration)

Next Steps

For system setup and configuration, see:

• Getting Started - Installation and first project
• Architecture Overview - Detailed system design
• CLI Reference - Command documentation