This document provides a comprehensive guide to understanding the Wheels 3.0 monorepo structure, how components relate to each other, and how the development and distribution workflow operates.
- Overview
- Directory Structure
- Core Components
- Supporting Components
- Package Distribution Flow
- Development Workflow
- Component Relationships
Wheels 3.1 uses a monorepo structure to maintain all framework components in a single repository. This approach provides:
- Unified Versioning: All components share the same version number (currently
3.1.0) - Simplified Development: Changes across components can be developed and tested together
- Atomic Commits: Related changes across CLI, core, and templates happen in single commits
- Easier Testing: Cross-component integration testing without dependency management
- Separate Distribution: Components are still published as independent ForgeBox packages
The repo root IS a runnable Wheels application. Clone and box server start just works.
wheels/
├── app/ # Application code (controllers, models, views)
├── config/ # Configuration files (routes, settings, environments)
├── public/ # Web root (Application.cfc, index.cfm, assets)
├── vendor/
│ └── wheels/ # Framework core runtime (tracked as source)
├── db/ # Database files (H2 embedded)
├── plugins/ # Application plugins
├── tests/ # Framework test suite
├── box.json # Application/package manifest
├── server.json # CommandBox server configuration
│
│ ── Development infrastructure (not part of the app) ──
│
├── cli/ # Wheels CLI (CommandBox module)
├── docs/ # Documentation (MkDocs)
├── examples/ # Example applications
├── tools/ # Build and development tools
│ ├── build/ # Build scripts and packaging
│ ├── docker/ # Docker test environments
│ ├── installer/ # Installation tools
│ ├── scripts/ # Utility scripts
│ ├── vscode-ext/ # VSCode extension
│ └── workspace/ # Development workspace
├── design_docs/ # Architecture and design docs
├── .ai/ # AI reference documentation
├── .claude/ # Claude Code configuration
├── .github/ # GitHub Actions and templates
├── compose.yml # Docker Compose configuration
└── [config files] # .gitignore, .gitattributes, etc.
These components are published to ForgeBox and distributed to end users.
Published as: wheels-cli
Type: CommandBox module
Purpose: Provides command-line tools for Wheels development
cli/
├── box.json # Package metadata
├── src/
│ ├── ModuleConfig.cfc # CommandBox module configuration
│ ├── commands/ # CLI command implementations
│ │ └── wheels/ # Hierarchical command structure
│ │ ├── new.cfc # Create new app
│ │ ├── generate/ # Code generators
│ │ ├── db/ # Database commands
│ │ ├── routes/ # Routing commands
│ │ └── ...
│ ├── models/ # Business logic (WireBox DI)
│ ├── templates/ # Code generation templates
│ ├── recipes/ # Command recipes
│ └── interceptors/ # CommandBox interceptors
├── README.md # CLI documentation
└── CLAUDE.md # Development guidance
Key Features:
- Code generators for controllers, models, views, etc.
- Database migration tools
- Route inspection and management
- Template-based code generation using
{{variable}}syntax - WireBox dependency injection for business logic
Installation:
box install wheels-cliPublished as: wheels-core
Type: CFML framework library
Purpose: The actual MVC framework runtime
vendor/wheels/
├── Controller.cfc # Controller base class
├── Model.cfc # Model/ORM base class
├── Dispatch.cfc # Request routing
├── Global.cfc # Global helpers
├── Mapper.cfc # Route mapper
├── Migrator.cfc # Database migrations
├── controller/ # Controller mixins
├── model/ # Model mixins
├── view/ # View rendering
├── databaseAdapters/ # DB engine adapters
├── public/ # Built-in pages and docs
├── tests/ # Core unit tests
├── tests_testbox/ # TestBox integration tests
└── box.json # Package metadata
Installation:
box install wheels-coreRuntime Location: Installed to /vendor/wheels/ in application projects
Published as: wheels-base-template
Type: Application scaffold
Purpose: Starting structure for new Wheels applications
The app scaffold now lives at the repo root (not in a separate templates/ directory). The build scripts extract the relevant directories to produce the ForgeBox package.
(repo root)
├── app/ # Application code structure
│ ├── controllers/ # Controller directory
│ ├── models/ # Model directory
│ ├── views/ # View templates
│ ├── events/ # Application event handlers
│ ├── jobs/ # Background job definitions
│ ├── mailers/ # Email mailers
│ ├── migrator/ # Database migrations
│ └── ...
├── config/ # Configuration files
│ ├── app.cfm # Application settings
│ ├── environment.cfm # Environment detection
│ ├── routes.cfm # Route definitions
│ ├── settings.cfm # Framework settings
│ └── [env dirs]/ # Per-environment overrides
├── public/ # Web root
│ ├── Application.cfc # CFML application bootstrap
│ ├── index.cfm # Entry point
│ └── [asset dirs]/ # CSS, JS, images
├── db/ # Database files (H2)
├── plugins/ # Application plugins
└── box.json # App manifest and dependencies
Used by: CLI command wheels new myapp downloads this template from ForgeBox
These components support development but are not distributed as packages.
Published to: https://wheels.dev/guides Format: MkDocs (Markdown-based)
docs/
├── src/ # Documentation source
│ ├── command-line-tools/ # CLI documentation
│ ├── database-interaction-through-models/
│ ├── displaying-views-to-users/
│ ├── handling-requests-with-controllers/
│ ├── introduction/
│ ├── plugins/
│ ├── working-with-wheels/
│ ├── upgrading/
│ └── ...
├── mkdocs.yml # MkDocs configuration
├── SUMMARY.md # Documentation structure
├── _layouts/ # Layout templates
├── overrides/ # MkDocs overrides
└── public/ # Generated static site
Build Process: Automatically deployed to wheels.dev via GitHub Actions
Purpose: Framework test suite for core functionality validation
tests/
├── runner.cfm # Test runner
├── specs/ # Test specifications
├── _assets/ # Test resources
├── README.md # Test setup instructions
└── CLAUDE.md # Test development guidance
Integration: Tests run against framework core with Docker support for multi-engine testing
Purpose: Build automation, testing environments, and development utilities
tools/
├── build/ # Build and packaging
│ ├── base/ # Base template build
│ ├── cli/ # CLI build scripts
│ ├── core/ # Core framework build
│ ├── lib/ # Shared utilities
│ └── scripts/ # Build automation (13 scripts)
├── docker/ # Docker test environments
│ ├── testui/ # Modern test UI
│ ├── lucee5/ # Lucee 5.x engine
│ ├── lucee6/ # Lucee 6.x engine
│ ├── lucee7/ # Lucee 7.x engine
│ ├── adobe2018/ # Adobe CF 2018
│ ├── adobe2021/ # Adobe CF 2021
│ ├── adobe2023/ # Adobe CF 2023
│ ├── adobe2025/ # Adobe CF 2025
│ ├── boxlang/ # BoxLang engine
│ ├── sqlserver/ # SQL Server
│ ├── mysql/ # MySQL
│ ├── postgres/ # PostgreSQL
│ └── Oracle/ # Oracle
├── installer/ # Installation tools
├── scripts/ # Utility scripts
├── vscode-ext/ # VSCode extension
└── workspace/ # Development workspace
Docker Testing: Supports simultaneous testing across multiple CFML engines and databases using Docker Compose
Purpose: Reference applications demonstrating Wheels patterns
examples/
└── starter-app/ # Comprehensive example application
Purpose: Architecture decisions, specifications, and development notes
design_docs/
├── ai-specs/ # AI integration specifications
├── architecture/ # Architecture documentation
├── scratchpad/ # Development notes
└── testing/ # Testing documentation
┌─────────────────────────────────────────────────────────────┐
│ Monorepo Repository │
│ ┌─────────┐ ┌──────────┐ ┌─────────────────┐ │
│ │ CLI │ │ Core │ │ Base Template │ │
│ │ /cli/ │ │ /core/ │ │ /templates/base/│ │
│ └────┬────┘ └─────┬────┘ └────────┬────────┘ │
│ │ │ │ │
└───────┼─────────────┼─────────────────┼──────────────────────┘
│ │ │
│ ┌────────▼─────────────────▼────────┐
│ │ Build Scripts (/tools/build/) │
│ └────────┬─────────────────┬────────┘
│ │ │
│ ┌────────▼─────────────────▼────────┐
│ │ GitHub Actions CI/CD │
│ └────────┬─────────────────┬────────┘
│ │ │
┌───────▼─────────────▼─────────────────▼────────────────────┐
│ ForgeBox Registry │
│ ┌─────────────┐ ┌─────────────┐ ┌──────────────────┐ │
│ │ wheels-cli │ │ wheels-core │ │ wheels-base- │ │
│ │ │ │ │ │ template │ │
│ └──────┬──────┘ └──────┬──────┘ └────────┬─────────┘ │
│ │ │ │ │
└─────────┼────────────────┼───────────────────┼──────────────┘
│ │ │
│ │ │
┌─────▼────────────────▼───────────────────▼─────┐
│ End User Installation │
│ │
│ 1. box install wheels-cli │
│ │
│ 2. wheels new myapp │
│ ├─> Downloads wheels-base-template │
│ └─> Installs wheels-core as dependency │
│ │
│ 3. Result: Working Wheels application │
│ myapp/ │
│ ├── app/ (from base template) │
│ ├── config/ (from base template) │
│ ├── public/ (from base template) │
│ └── vendor/ │
│ └── wheels/ (from wheels-core) │
└──────────────────────────────────────────────────┘
-
Clone and run:
git clone https://github.com/wheels-dev/wheels.git cd wheels box install box server startThe repo root IS a working Wheels application with an H2 embedded database.
-
Make changes in respective directories:
- Core framework:
vendor/wheels/ - App scaffold:
app/,config/,public/ - CLI:
cli/src/ - Documentation:
docs/src/
- Core framework:
-
Test changes locally:
# Use Docker for multi-engine testing docker compose up -
Build packages:
cd tools/build/scripts # Run appropriate build script
All components share the same version number defined in their box.json files. When releasing:
-
Update version in
box.jsonfiles:box.json(root — the base template manifest)examples/starter-app/box.json
-
Update
CHANGELOG.mdwith release notes -
Create git tag:
git tag v3.1.0 -
Push and let CI/CD handle ForgeBox publishing
Use Docker Compose to test against multiple CFML engines simultaneously:
docker-compose up lucee5 lucee6 lucee7 adobe2021 adobe2023Each service runs tests in isolation with proper database configurations.
┌─────────────┐
│ wheels-cli │ (CommandBox module)
└──────┬──────┘
│
│ uses during 'wheels new'
│
▼
┌──────────────────┐
│ wheels-base- │
│ template │
└──────┬───────────┘
│
│ depends on (via box.json)
│
▼
┌─────────────┐
│ wheels-core │ (Installed to /vendor/wheels/)
└─────────────┘
User Application
├── /app
│ ├── controllers/
│ │ └── MyController.cfc ──extends──> /vendor/wheels/Controller.cfc
│ ├── models/
│ │ └── MyModel.cfc ──extends──> /vendor/wheels/Model.cfc
│ └── views/
│ └── myview.cfm ──uses──> /vendor/wheels view helpers
├── /config
│ ├── app.cfm ──configures──> Wheels settings
│ └── routes.cfm ──defines──> URL routing
├── /public
│ └── index.cfm ──bootstraps──> /vendor/wheels/
└── /vendor
└── wheels/ (wheels-core package)
├── Controller.cfc
├── Model.cfc
├── Wheels.cfc
└── ...
In Monorepo (Development):
wheels/
├── app/, config/, public/ → App scaffold (published as wheels-base-template)
├── vendor/wheels/ → Framework core (published as wheels-core)
└── cli/src/ → CLI source (published as wheels-cli)
After Distribution:
User's System:
├── ~/.CommandBox/modules/wheels-cli/ (from ForgeBox)
User's Application:
├── vendor/wheels/ (from ForgeBox via dependency)
└── [app structure from base template] (from ForgeBox via CLI download)
- Version Synchronization: All components share version
3.1.0 - CFML-Based: Framework written in CFML with CommandBox module system
- Docker Testing: Multi-engine and multi-database testing support
- Template-Based Generation: CLI uses Handlebars-style
{{variable}}syntax - Automated Documentation: MkDocs published to wheels.dev via CI/CD
- Custom Build System: Uses CommandBox and custom scripts (not npm/pnpm workspaces)
- Separate Distribution: Unified development, independent ForgeBox packages
Wheels 3.0 includes comprehensive AI assistance configuration to help AI coding assistants (like Claude Code, GitHub Copilot, Cursor, etc.) work effectively with the framework.
Location: /.ai
Purpose: Comprehensive documentation structured specifically for AI assistants
.ai/
├── README.md # Knowledge base overview
├── CLAUDE.md # Wheels documentation index
├── QUICK_REFERENCE.md # Quick reference guide
├── CONTRIBUTION_SUMMARY.md # Contribution tracking
├── MCP-ENFORCEMENT.md # MCP tool enforcement rules
├── cfml/ # CFML language documentation
│ ├── README.md # CFML overview
│ ├── syntax/ # Basic syntax, CFScript vs tags
│ ├── data-types/ # Variables, arrays, structures, scopes
│ ├── control-flow/ # Conditionals, loops, exceptions
│ ├── components/ # CFCs, functions, properties
│ ├── database/ # Query basics
│ ├── advanced/ # Closures, advanced features
│ └── best-practices/ # Modern patterns, performance
└── wheels/ # Wheels framework documentation
├── README.md # Wheels overview
├── cli/ # CLI generators and commands
├── configuration/ # App settings, environments
├── controllers/ # Request handling, filters, rendering
├── core-concepts/ # MVC architecture, ORM, routing
├── database/ # Migrations, associations, validations
├── views/ # Templates, layouts, helpers
├── communication/ # Email, HTTP requests
├── files/ # File handling, uploads
├── patterns/ # Common patterns, best practices
├── security/ # Authentication, CSRF, authorization
├── snippets/ # Code examples
└── workflows/ # Implementation workflows
Key Features:
- Structured Documentation: Organized by both language (CFML) and framework (Wheels) concerns
- Anti-Pattern Prevention: Documents common mistakes and how to avoid them
- Code Templates: Working examples for models, controllers, views, migrations
- Best Practices: Modern CFML and Wheels development patterns
- Validation Templates: Checklists for preventing common errors
Example Content:
# From .ai/wheels/models/associations.md
## Critical Pattern
✅ CORRECT: hasMany(name="comments", dependent="delete")
❌ WRONG: hasMany("comments", dependent="delete") // Mixed argumentsUsage by AI Assistants:
- AI tools read these files to understand framework conventions
- Prevents common errors before code is written
- Provides working code templates for consistent implementation
- Documents Wheels-specific patterns that differ from Rails/Laravel
Location: /.claude
Purpose: Claude Code-specific configuration and custom commands
.claude/
├── settings.local.json # Permissions and tool configuration
└── commands/
└── wheels_execute.md # Custom slash command for development
settings.local.json:
Configures Claude Code permissions for the project:
{
"permissions": {
"allow": [
"Bash(box:*)", // CommandBox commands
"Bash(wheels:*)", // Wheels CLI commands
"Bash(git:*)", // Git operations
"Bash(docker:*)", // Docker commands
"WebFetch(domain:wheels.dev)", // Fetch documentation
"WebFetch(domain:github.com)", // GitHub API access
"mcp__puppeteer__*" // Browser testing tools
],
"deny": []
}
}Custom Commands:
The wheels_execute.md file defines a comprehensive development workflow:
# /wheels_execute - Comprehensive Wheels Development Workflow
Execute complete, systematic Wheels development with:
- Spec-driven development (user approves plan first)
- Incremental implementation with testing
- Real-time progress tracking
- Comprehensive browser testing
- TestBox BDD test suite creation
- Anti-pattern prevention
Usage: /wheels_execute create a blog with posts and commentsWorkflow Features:
- Pre-Flight Documentation Loading: Loads relevant
.aidocs before coding - Specification Generation: Creates detailed spec for user approval
- Task-Based Implementation: Breaks work into trackable tasks
- Incremental Testing: Tests each component immediately after creation
- Anti-Pattern Detection: Prevents common Wheels errors during generation
- Comprehensive Reporting: Provides evidence of working implementation
In Monorepo (Development) and distributed with Base Template:
/.ai/- Complete knowledge base (100+ markdown files)/.claude/- Claude Code configuration- Root
CLAUDE.mdandAGENTS.md- AI guidance files
Benefits for Contributors:
- Faster Onboarding: AI assistants understand the codebase immediately
- Consistent Code Quality: AI generates code following established patterns
- Error Prevention: Common mistakes caught before code is written
- Documentation Access: AI can reference official docs during development
- Custom Workflows: Project-specific commands for common tasks
Example AI Workflow:
# User runs custom command
/wheels_execute create a blog with posts and comments
# Claude Code:
# 1. Loads .ai/wheels/troubleshooting/common-errors.md
# 2. Loads .ai/wheels/database/associations.md
# 3. Loads .ai/wheels/controllers/rendering.md
# 4. Generates specification with correct patterns
# 5. Gets user approval
# 6. Implements incrementally with testing
# 7. Prevents mixed argument styles
# 8. Uses proper query handling patterns
# 9. Tests each component before moving forward
# 10. Provides comprehensive results reportThe .ai/ folder also documents MCP tool enforcement:
From .ai/MCP-ENFORCEMENT.md:
- If
.mcp.jsonexists in a project, MCP tools MUST be used - CLI commands are forbidden when MCP is available
- Enforces consistent tool usage across projects
Available MCP Tools:
mcp__wheels__wheels_generate()- Generate componentsmcp__wheels__wheels_migrate()- Run migrationsmcp__wheels__wheels_test()- Execute testsmcp__wheels__wheels_server()- Manage dev servermcp__wheels__wheels_analyze()- Analyze codebase
- CommandBox CLI installed
- Docker and Docker Compose (for testing)
- Git
- (Optional) Claude Code or other AI coding assistant
# Clone repository
git clone https://github.com/wheels-dev/wheels.git
cd wheels
# Install dependencies
box install
# Start development server (repo root is a runnable Wheels app)
box server start
# Run tests with Docker (multi-engine)
docker compose upIf using Claude Code or similar AI assistants:
- The
.ai/folder provides comprehensive framework documentation - The
.claude/folder contains Claude Code-specific configuration - Custom commands like
/wheels_executeprovide guided development workflows - AI assistants will automatically prevent common errors using the knowledge base
See CONTRIBUTING.md for detailed contribution guidelines.
- Documentation: https://wheels.dev/docs
- Community: https://github.com/wheels-dev/wheels/discussions
- Issues: https://github.com/wheels-dev/wheels/issues
Last Updated: 2025-10-20 Version: 3.1.0