Wheels 4.0: Interface-driven design contracts Issue #1967

[bpamiri]

Summary

Define interfaces for all core subsystems, enabling drop-in replacements.

Details

• Interfaces for ORM, routing, controller, view, validation, events subsystems
• Modules communicate only through contracts — no internal coupling
• Enables community-built alternative implementations of any subsystem
• Part of Wheels 4.0 epic (Plugin system → Service Provider model (Wheels 4.0) #1917)

Source

design_docs/architecture/wheels-4-architecture-guide.md

[bpamiri]

Analysis

Synopsis

This issue proposes defining formal interfaces for all core Wheels subsystems (ORM, routing, controller, view, validation, events), enabling drop-in replacements where modules communicate only through contracts rather than internal coupling.

Merit Assessment

Recommendation: Proceed with modifications

• The pattern already exists in embryonic form. vendor/wheels/middleware/MiddlewareInterface.cfc is a working CFML interface with a handle(request, next) contract. The DI container (vendor/wheels/Injector.cfc) already has bind() as a semantic alias for interface-style mapping (line 104). These prove the pattern works in Wheels' CFML context.
• The problem is real and measurable. Core subsystems are tightly coupled through $integrateComponents() (Model.cfc line 524), which dynamically mixes all public methods from files in a directory into the parent component. There are no contracts — any CFC in vendor/wheels/model/ gets its public methods injected into every Model instance. This makes it impossible to replace a subsystem without forking core files.
• Enables the broader 4.0 vision. Engine adapters (Wheels 4.0: Engine adapter modules (Lucee, Adobe, BoxLang) Issue #1968 #1968), module system (Wheels 4.0: Module system and package format #1966), and legacy adapter (Wheels 4.0: Legacy compatibility adapter and migration path Issue #1969 #1969) all depend on having clear contracts to code against. Without interfaces, "drop-in replacement" is aspirational.
• Modification needed: prioritize subsystems. Defining interfaces for all subsystems at once is scope creep. Start with the subsystems that have the clearest boundaries: ORM (model CRUD), routing (mapper), and middleware (already done). Defer view and validation interfaces — they have deep internal coupling that requires more design work.

Implementation Plan

1. Audit existing subsystem boundaries — Map which methods in each subdirectory constitute the public API:

   • vendor/wheels/model/ (17 CFCs): read.cfc, create.cfc, update.cfc, delete.cfc, associations.cfc, validations.cfc, callbacks.cfc, properties.cfc, sql.cfc, etc.
   • vendor/wheels/controller/ (14 CFCs): rendering.cfc, filters.cfc, flash.cfc, services.cfc, csrf.cfc, etc.
   • vendor/wheels/view/ (14 CFCs): forms.cfc, links.cfc, pagination.cfc, assets.cfc, etc.
   • vendor/wheels/mapper/ (routing sub-components)

2. Define Phase 1 interfaces (create in vendor/wheels/interfaces/):

   • ORMInterface.cfc — findAll(), findOne(), findByKey(), create(), update(), delete(), save(), new(), exists()
   • RouterInterface.cfc — resources(), get(), post(), put(), patch(), delete(), root(), scope(), end(), getRoutes()
   • MiddlewareInterface.cfc — already exists at vendor/wheels/middleware/MiddlewareInterface.cfc
   • DatabaseAdapterInterface.cfc — $executeQuery(), $getColumnInfo(), $identitySelect() (the vendor/wheels/databaseAdapters/ directory already follows an adapter pattern with Abstract.cfc → vendor-specific subclasses)

3. Refactor DI bindings — Extend vendor/wheels/Bindings.cfc (currently only 3 mappings) to register subsystem implementations against their interfaces: injector.bind("ORM").to("wheels.model.DefaultORM").asSingleton()

4. Update $integrateComponents to respect contracts — Rather than blindly mixing all public methods, integrate only methods declared by the interface. This is the riskiest change and should be gated behind a feature flag.

5. Phase 2 interfaces (after module system lands):

   • ValidatorInterface.cfc
   • ViewRendererInterface.cfc
   • EventDispatcherInterface.cfc

Estimated complexity: Medium-Large. Interface definitions = ~1 week. Refactoring integration to respect contracts = ~2-3 weeks. High test surface area.

Dependencies & Risks

• No hard prerequisites, but this should land before Wheels 4.0: Module system and package format #1966 (module system) since modules need interfaces to declare provides.
• Breaking change risk: High if done aggressively. The $integrateComponents() / $integrateFunctions() pattern (Model.cfc lines 524-560) dynamically mixes methods based on file presence, not interface conformance. Changing this alters how every Model and Controller is assembled. Must be feature-flagged.
• CFML interface limitation: CFML interfaces cannot enforce return types reliably across engines (Lucee vs Adobe vs BoxLang behave differently). Consider "documentation interfaces" (abstract base classes) rather than strict CFML interface components for maximum cross-engine compatibility.
• Related: Wheels 4.0: Engine adapter modules (Lucee, Adobe, BoxLang) Issue #1968 #1968 (engine adapters) would be the first real consumer of these interfaces — engine adapters implement DatabaseAdapterInterface and engine-specific contracts.
• Test impact: The CI matrix runs 8 CFML engines x 5+ databases (.github/workflows/tests.yml). Any interface changes must pass across the full matrix.

---

Automated analysis by @claude — review and adjust as needed.