System Architecture Overview

WDG AI Development Environment is a containerized WordPress development platform with integrated AI capabilities.

High-Level Architecture

%%{init: {'theme':'neutral'}}%%
graph TB
    subgraph "Developer Machine"
        CLI[WDG CLI]
        Browser[Web Browser]
        Editor[Code Editor]
        Claude[Claude Desktop]

        subgraph "Docker Environment"
            subgraph "Core Services"
                Nginx[Nginx Proxy<br/>:8443]
                MySQL[(MySQL<br/>:3306)]
                Qdrant[(Qdrant<br/>:6333)]
                MCP[MCP Server<br/>:8765]
            end

            subgraph "Project Containers"
                WP1[Project 1<br/>WordPress + PHP]
                WP2[Project 2<br/>WordPress + PHP]
                WP3[Project N<br/>WordPress + PHP]
            end

            subgraph "AI Layer"
                Indexer[Code Indexer]
                Embedder[Local Embeddings<br/>all-MiniLM-L6-v2]
            end
        end

        subgraph "File System"
            Projects["/projects"]
            Repos["/repositories"]
            SSL["/ssl"]
            Data["/data"]
        end
    end

    CLI --> Nginx
    Browser --> Nginx
    Claude --> MCP
    Editor --> Projects

    Nginx --> WP1
    Nginx --> WP2
    Nginx --> WP3

    WP1 --> MySQL
    WP2 --> MySQL
    WP3 --> MySQL

    Indexer --> Embedder
    Embedder --> Qdrant
    MCP --> Qdrant

    WP1 --> Repos
    WP2 --> Repos
    WP3 --> Repos

Component Architecture

1. CLI Layer

The WDG CLI (/cli/wdg) is the primary interface:

• Shell Script: Pure bash for portability
• Docker Integration: Manages containers via docker-compose
• Project Management: Creates, starts, stops, deletes projects
• Repository Management: Git operations and syncing
• Indexing Control: Triggers AI indexing pipeline

2. Container Layer

Core Services (Always Running)

Nginx Proxy

• Routes *.localhost:8443 to project containers
• SSL termination with self-signed certificates
• WebSocket support for hot-reload
• Header injection for WordPress HTTPS detection

MySQL Database

• Single instance for all projects
• Separate database per project (wp_project_name)
• Root access for management operations
• Persistent volume mounting

Qdrant Vector Database

• Stores code embeddings
• Separate collections per project
• REST API on port 6333
• Web UI dashboard included

MCP Server (Optional)

• Model Context Protocol for AI assistants
• Bridges Claude Desktop to vector search
• Python FastAPI application
• WebSocket connections

Project Containers (On-Demand)

Each project runs in its own WordPress container:

• Base Image: wordpress:latest
• PHP Version: 8.1+ with extensions
• WordPress: Latest version auto-installed
• WP-CLI: Pre-installed for automation
• Volume Mounts:
  • Theme repositories → /var/www/html/wp-content/themes/
  • Plugin repositories → /var/www/html/wp-content/plugins/

3. AI Layer

Indexing Pipeline

%%{init: {'theme':'neutral'}}%%
sequenceDiagram
    participant CLI
    participant Docker
    participant Indexer
    participant Model
    participant Qdrant
    
    CLI->>Docker: Run indexer container
    Docker->>Indexer: Execute indexer.py
    Indexer->>Indexer: Parse code files
    loop For each code chunk
        Indexer->>Model: Generate embedding
        Model->>Indexer: Return vector
        Indexer->>Qdrant: Store vector + metadata
    end
    Qdrant->>CLI: Indexing complete

Local Embedding Model

• Library: Sentence-Transformers
• Model: all-MiniLM-L6-v2 (80MB)
• Dimensions: 384-dimensional vectors
• Performance: ~100 files/second
• No Internet Required: Model cached locally

4. Storage Architecture

/home/user/wdg-ai-dev/
├── projects/                 # Project files
│   └── my-site/
│       ├── backups/          # Database backups
│       ├── config/           # Project configuration
│       ├── logs/             # Application logs
│       ├── repositories/     # Project-specific repository clones
│       │   └── my-site/      # Repository for this project
│       │       └── wp-content/
│       │           ├── themes/
│       │           ├── plugins/
│       │           ├── mu-plugins/
│       │           └── uploads/
│       ├── docker-compose.yml
│       └── project.json
├── repositories/             # Central repository storage
│   ├── wikit-core/           # Wikit framework
│   ├── wikit-theme/          # Base theme template
│   ├── wikit-facets/         # Component library
│   └── wikit-app/            # Application framework
├── services/                 # Service configurations
│   ├── nginx/
│   │   └── sites-enabled/    # Per-project configs
│   ├── mysql/
│   │   └── init/             # Database initialization
│   └── wordpress/
│       └── setup-wp.sh       # WP-CLI automation
├── ssl/                      # SSL certificates
│   ├── my-site.localhost.crt
│   └── my-site.localhost.key
├── data/                     # Persistent data volumes
│   ├── mysql/                # MySQL data files
│   └── qdrant/               # Vector database
├── cli/                      # Command-line tools
└── docker-compose.yml        # Main service orchestration

Note: WordPress core files are stored in Docker volumes (e.g., wordpress-my-site), not in the project directory. The project directory only contains configuration, logs, and the wp-content from repositories.

Network Architecture

Docker Networks

networks:
  wdg-network:
    driver: bridge
    ipam:
      config:
        - subnet: 172.25.0.0/16

All containers join the wdg-network for inter-service communication.

Port Mapping

Service	Internal Port	External Port	Purpose
Nginx	80, 443	8880, 8443	HTTP/HTTPS proxy
MySQL	3306	3307	Database
Qdrant	6333, 6334	6333, 6334	Vector DB + gRPC
MCP	8765	8765	AI bridge
WordPress	80	-	Internal only
Dashboard Frontend	3000	3000	React dashboard
Dashboard Backend	8000	8000	FastAPI backend
Docs	5173	5173	VitePress docs
phpMyAdmin	80	8081	Database admin

Note: Ports 8880 (HTTP) and 8443 (HTTPS) are used for Nginx to avoid conflicts with common local development servers. MySQL uses 3307 externally to avoid conflicts with local MySQL installations.

SSL/TLS Configuration

Each project gets automatic SSL:

server {
    listen 443 ssl http2;
    server_name my-site.localhost;
    
    ssl_certificate /etc/nginx/ssl/my-site.localhost.crt;
    ssl_certificate_key /etc/nginx/ssl/my-site.localhost.key;
    
    location / {
        proxy_pass http://wdg-wp-my-site:80;
        proxy_set_header X-Forwarded-Proto https;
    }
}

Database Architecture

MySQL Structure

-- System databases
mysql
information_schema
performance_schema

-- Project databases
wp_my_site       -- Project: my-site
wp_another_site  -- Project: another-site

Qdrant Collections

{
  "collections": [
    {
      "name": "wdg_framework",
      "vectors": 15000,
      "dimension": 384
    },
    {
      "name": "project_my_site",
      "vectors": 3000,
      "dimension": 384
    }
  ]
}

Security Architecture

Container Isolation

• Each project runs in isolated container
• No shared file system between projects
• Network segmentation via Docker networks
• Resource limits prevent noisy neighbors

Database Security

• Unique database per project
• Random passwords generated
• No external MySQL access by default
• Connection only via Docker network

SSL/TLS

• Self-signed certificates for development
• Forced HTTPS redirect
• Secure headers (HSTS, XSS protection)
• Certificate per domain

Code Privacy

• All processing happens locally
• No external API calls for embeddings
• Vector database runs on localhost
• Git repositories remain private

Performance Architecture

Caching Layers

1. Docker Layer Caching

   • Base images cached locally
   • Incremental builds
   • Shared layers between projects

2. Model Caching

   • Embedding model downloaded once
   • Cached in Docker volume
   • Shared across all indexing operations

3. Query Caching

   • Qdrant in-memory cache
   • MCP server response cache
   • 15-minute TTL

Optimization Strategies

Container Start Time

• Pre-built base images
• Minimal container layers
• Volume mounts over COPY
• Parallel container starts

Indexing Performance

• Batch processing (32 files/batch)
• Async I/O for file reading
• Vector quantization
• Incremental indexing (planned)

Query Performance

• HNSW index in Qdrant
• Approximate nearest neighbor
• Sub-100ms query times
• Limited result sets

Scalability Considerations

Horizontal Scaling

%%{init: {'theme':'neutral'}}%%
graph LR
    subgraph "Current"
        Single[Single Machine<br/>All Services]
    end

    subgraph "Scalable"
        LB[Load Balancer]
        WP_1[WordPress Fleet]
        DB[(MySQL Cluster)]
        QD[(Qdrant Cluster)]
    end

    Single --> LB
    LB --> WP_1
    WP_1 --> DB
    WP_1 --> QD

Resource Limits

Component	CPU Limit	Memory Limit	Disk Usage
WordPress	2 cores	2GB	1GB/project
MySQL	2 cores	4GB	10GB total
Qdrant	1 core	2GB	5GB
Nginx	0.5 cores	512MB	100MB
Indexer	2 cores	1GB	Ephemeral

Scaling Strategies

1. Vertical: Increase Docker resource limits
2. Horizontal: Run projects on multiple machines
3. Distributed: Separate database/vector tiers
4. Cloud: Deploy to Kubernetes cluster

Development vs Production

This architecture is optimized for local development:

Aspect	Development (Current)	Production
SSL	Self-signed	Let's Encrypt
Database	Single MySQL	RDS/CloudSQL
Vectors	Local Qdrant	Managed Qdrant
Storage	Local disk	Object storage
Backup	Manual	Automated
Monitoring	Basic logs	Full observability

Future Architecture

Planned Enhancements

1. Kubernetes Deployment

   • Helm charts for easy deployment
   • Auto-scaling based on load
   • Multi-node support

2. Incremental Indexing

   • Watch file changes
   • Index only modified files
   • Real-time vector updates

3. Distributed Vectors

   • Qdrant clustering
   • Sharded collections
   • Federated search

4. Local LLMs

   • Code completion
   • Automated refactoring
   • Bug detection

---

Key Takeaway: The architecture prioritizes developer experience with fast project creation, local AI features, and complete privacy while maintaining flexibility for future scaling.