Core Concepts

Understanding the key concepts behind WDG AI Development Environment.

Projects

A project in WDG is a complete WordPress installation with:

• Isolated WordPress instance
• Dedicated MySQL database
• Custom theme/plugin repositories
• SSL certificate for HTTPS
• Vector collection for AI search

Project Lifecycle

%%{init: {'theme':'neutral'}}%%
stateDiagram-v2
    [*] --> Created: wdg create
    Created --> Running: wdg start
    Running --> Stopped: wdg stop
    Stopped --> Running: wdg start
    Running --> Indexed: wdg index
    Indexed --> Running: code changes
    Stopped --> Deleted: wdg delete
    Running --> Deleted: wdg delete
    Deleted --> [*]

Repositories

Repositories are Git-managed codebases that get mounted into your WordPress installation:

• Themes → /wp-content/themes/
• Plugins → /wp-content/plugins/
• Must-use plugins → /wp-content/mu-plugins/

Repository Types

1. Embedded: Created with the project
2. Attached: Linked from external location
3. Remote: Cloned from Git URL

Vector Collections

Each project has its own vector collection - a searchable database of code embeddings:

wdg_framework         → All Wikit code
project_my_site      → my-site project code
project_another_site → another-site project code

Collection Isolation

• Projects can't search each other's code
• Framework collection is available to all
• Clean separation of concerns

Local Embeddings

Embeddings are numerical representations of code that capture semantic meaning:

"function getUserById()" → [0.23, -0.45, 0.67, ...]
                          384 dimensions

Why Local?

• Privacy: Code never leaves your machine
• Cost: No API fees
• Speed: No network latency
• Control: Choose your model

Docker Services

WDG uses several Docker services:

Core Services (Shared)

• Nginx: Routes traffic to projects
• MySQL: Shared database server
• Qdrant: Vector database
• MCP: AI assistant bridge

Project Services (Isolated)

• WordPress: One container per project
• Theme watchers: Build tools

SSL Certificates

Every project gets automatic SSL certificates:

• Self-signed for development
• Valid for *.localhost domains
• Port 8443 for HTTPS
• Automatic generation on project creation

MCP (Model Context Protocol)

MCP bridges AI assistants to your development environment:

• Provides code search API
• Enables context-aware assistance
• Works with Claude Desktop
• RESTful interface

Wikit Framework

Wikit is WDG's WordPress component framework:

• Gutenberg blocks library
• Reusable components
• Consistent patterns
• Pre-indexed for search

Wikit Components

• wikit-core: Core functionality
• wikit-theme: Base theme template
• wikit-facets: Search & filters
• wikit-app: Application framework

Code Indexing

Indexing processes your code for AI search:

1. Parsing: Extract functions, classes, hooks
2. Chunking: Break into semantic units
3. Embedding: Convert to vectors
4. Storing: Save in Qdrant

What Gets Indexed

• PHP functions and classes
• WordPress hooks and filters
• JavaScript functions and components
• CSS selectors and rules
• JSON configurations

Development Workflow

The typical workflow follows these steps:

1. Create project from template
2. Start WordPress and services
3. Develop with hot-reload
4. Index for AI search
5. Search with semantic queries
6. Build for production

Environment Variables

Environment variables configure your system:

EMBEDDING_MODEL     # AI model choice
MYSQL_ROOT_PASSWORD # Database access
WP_DEBUG           # WordPress debugging
ANTHROPIC_API_KEY  # Claude integration (optional)

Network Architecture

All services communicate on the Docker network:

wdg-network (172.25.0.0/16)
├── nginx (172.25.0.2)
├── mysql (172.25.0.3)
├── qdrant (172.25.0.4)
├── mcp (172.25.0.5)
└── wp-* (172.25.0.10+)

File Synchronization

File sync keeps your code in sync:

• Edit locally in your IDE
• Changes sync to Docker instantly
• No rebuild needed
• Hot-reload in browser

Project Isolation

Each project is isolated:

• Separate WordPress installation
• Own database
• Independent repositories
• Isolated vector collection
• No cross-contamination

Performance Optimization

WDG optimizes for developer experience:

Fast Operations

• Project creation: <30 seconds
• Container start: <5 seconds
• Code indexing: ~100 files/second
• Search queries: <100ms

Resource Efficiency

• Shared base services
• Docker layer caching
• Incremental indexing (planned)
• Lazy loading of models

Security Model

WDG follows security best practices:

Local-Only Processing

• No external API calls for embeddings
• No telemetry or tracking
• No cloud dependencies
• Complete data sovereignty

Container Security

• Isolated namespaces
• Read-only mounts where possible
• Non-root containers
• Network segmentation

Extensibility

WDG is designed to be extensible:

Custom Templates

Create your own project templates:

templates/
├── my-template/
│   ├── docker-compose.yml
│   ├── theme/
│   └── config.json

Custom Models

Use different embedding models:

EMBEDDING_MODEL=all-mpnet-base-v2

Custom Services

Add services to docker-compose:

services:
  redis:
    image: redis:alpine
    networks:
      - wdg-network

Troubleshooting Concepts

Common Issues

Port Conflicts: Another service using 8443 SSL Warnings: Normal for self-signed certs Indexing Delays: First model download Memory Issues: Adjust Docker resources

Debug Modes

Enable debugging in .env:

WP_DEBUG=true
DEBUG=true
LOG_LEVEL=DEBUG

Future Concepts

Coming Soon

• Incremental Indexing: Index only changes
• Multi-Model Support: Different models per project
• Cloud Sync: Optional backup to cloud
• Team Sharing: Shared vector collections

Under Research

• Local LLMs: Code completion
• Semantic Diff: AI-powered code review
• Auto-Documentation: Generate from code
• Pattern Detection: Find code smells