User Module Research

Research: Cross-Module Libraries in ChAoS MVC


Research Status


Conclusion: Established
A ChAoS MVC user Module can own reusable domain libraries that are consumed by other user Modules without moving those libraries into Core or duplicating their implementation within the consuming Module.

This conclusion was established through three progressively stronger experiments using the Registry and Enroll Modules of the Ars Rosaic installation of ChAoS MVC.


Research Question


Can a ChAoS MVC user Module own reusable domain libraries that other user Modules consume similarly to shared Core libraries, while allowing the owning Module to retain responsibility for its domain-specific implementation?

The immediate architectural question arose from the Registry Module.

Registry is the authoritative source for organizational and geographic information used throughout the Ars Rosaic platform. Its responsibilities include Regions, States and Territories, Covens, geographic relationships, and other organizational information.

Several other Modules require information derived from Registry.

Enroll, for example, must determine geographic information during enrollment. Other Modules may eventually require the same geographic capabilities.

Moving Registry-specific geography logic into ChAoS MVC Core would make domain-specific functionality a responsibility of the framework itself.

Duplicating that functionality in every Module would create multiple implementations of the same rules and introduce unnecessary opportunities for inconsistent results.

The proposed alternative was therefore:

Allow Registry to own its domain libraries while permitting other user Modules to consume them.


Hypothesis


A user Module can own reusable domain libraries—geography, timezone, and other domain capabilities—and other user Modules can consume those libraries similarly to how ChAoS MVC exposes shared libraries, without moving Module-specific logic into Core.

This would allow a foundational Module to remain authoritative for its domain while other Modules consume the resulting capabilities.


Architectural Constraints


  • ChAoS MVC Core must remain unchanged.
    • Registry-specific functionality must not be promoted into Core merely to make it reusable.
    • The experiment must demonstrate a user-space solution.

  • Registry must retain ownership of its libraries.
    • Geography remains physically located within the Registry Module.
    • Registry remains responsible for its internal dependencies.

  • The consuming Module must not contain a duplicate implementation.
    • Enroll must consume Registry's implementation.
    • Geography libraries must not be copied into Enroll.

  • The final experiment must operate through ChAoS MVC.
    • A standalone PHP test is sufficient for proving PHP-level loading and execution.
    • It is not sufficient for establishing that the architecture works between Modules during normal MVC execution.

  • Conclusions must follow observed evidence.
    • The architectural pattern would not be considered established merely because PHP theoretically permits it.
    • The hypothesis required implementation and experimentation.


Registry Geography Libraries


Registry already contained a set of domain-specific libraries:

user/modules/registry/lib/
├── geocoder.php
├── geography.php
└── mgrs.php


The primary geography library owns the coordination of geographic operations.

Its dependencies remain within Registry.

Conceptually, the relationship is:

registry/geography.php
    |
    +-- registry/geocoder.php
    |
    +-- registry/mgrs.php


A consuming Module therefore does not need to independently implement geocoding or MGRS conversion.

It requests the operation from Registry's geography implementation and consumes the resulting geographic information.


Experiment 1: Cross-Module Library Loading


Objective


Determine whether code outside the Registry Module can load a Registry-owned library while allowing that library to resolve its own Registry-owned dependencies.

This experiment intentionally did not perform a geographic operation.

The first question was more fundamental:

Can the library cross the Module boundary at all?


Method


A separate test environment outside Registry attempted to load:

registry/lib/geography.php


The experiment then verified that:

  • registry_geography became available.
  • registry_geocoder became available.
  • registry_mgrs became available.
  • registry_geography could be instantiated.

No Registry library was copied into the test environment.

No ChAoS MVC Core modification was made.


Observed Result


ChAoS MVC Cross-Module Library Experiment
=========================================

[1] Registry library path
PASS
/home/microcms/public_html/arsrosaic.org/user/modules/registry/lib/geography.php

[2] Load Registry-owned library
PASS
registry_geography loaded successfully.

[3] Verify Registry-owned dependencies
PASS
registry_geocoder loaded.
registry_mgrs loaded.

[4] Instantiate Registry geography library
PASS
registry_geography instantiated successfully.

=========================================
EXPERIMENT 1 PASSED
=========================================

Observed evidence:
- Code outside the Registry Module loaded registry/lib/geography.php.
- geography.php loaded its Registry-owned dependencies.
- registry_geography was instantiated outside its owning Module.
This experiment establishes cross-module library loading.



Experiment 1 Finding


Experiment 1 established that a library physically owned by Registry could be loaded outside its owning Module.

It additionally demonstrated that the consuming code did not need to independently load each Registry dependency.

Registry's geography library retained responsibility for its own dependencies.

The experiment therefore established:

Cross-Module Library Loading

It did not yet establish that external code could successfully execute Registry domain functionality.

That required another experiment.


Experiment 2: Cross-Module Domain Execution


Objective


Determine whether external user-space code could execute functionality owned by Registry and receive a completed domain result.

Experiment 1 established that Registry's library could be loaded.

Experiment 2 asked the next question:

Can external code actually use it?


Method


The test environment loaded Registry's geography library and executed its geographic determination operation using a known public address:

1600 Pennsylvania Avenue NW
Washington, DC 20500


Registry's geography implementation was responsible for:

  • Geocoding the supplied address.
  • Producing latitude.
  • Producing longitude.
  • Passing those coordinates to Registry's MGRS implementation.
  • Returning the completed geographic result to the consuming code.

The consuming code did not independently perform geocoding or MGRS conversion.


Observed Result


ChAoS MVC Cross-Module Library Experiment 2
===========================================

[1] Load Registry-owned geography library
PASS

[2] Execute Registry-owned geography operation
PASS

[3] Validate returned geographic data
PASS
Latitude: 38.8986989
Longitude: -77.0351875
MGRS: 18S UJ 23510 07503

===========================================
EXPERIMENT 2 PASSED
===========================================

Observed evidence:
- External code executed Registry-owned domain functionality.
- Registry's geocoder produced coordinates.
- Registry's MGRS library processed those coordinates.
- The consuming code received the completed Registry result.
The Registry-owned library was not copied or moved into Core.



Experiment 2 Finding


Experiment 2 established that Registry's library was not merely loadable outside Registry.

Its domain functionality could actually be executed by external user-space code.

Registry remained responsible for the operation and its internal dependencies.

The consumer received the completed result.

The experiment therefore established:

Cross-Module Domain Execution Outside the MVC Lifecycle

One question remained.

The previous experiments demonstrated the behavior from external user-space test code.

The hypothesis specifically concerned one ChAoS MVC user Module consuming functionality owned by another ChAoS MVC user Module.

That required execution through the normal MVC lifecycle.


Experiment 3: Module-to-Module Consumption Through ChAoS MVC


Objective


Determine whether the Enroll Module could consume Registry's geography library while executing as a normal ChAoS MVC Module.

This was the strongest test of the hypothesis.

The required relationship was:

ChAoS MVC
    |
    +-- Enroll Module
            |
            +-- Registry-owned geography library
                    |
                    +-- Registry geocoder
                    |
                    +-- Registry MGRS


Registry must retain ownership of the geographic implementation.

Enroll must act as the consumer.

Core must remain unchanged.


Experimental Control Issue


During preparation for Experiment 3, an unrelated problem with the Enroll Module was discovered.

The /enroll baseline was not functioning correctly.

Observed symptoms included:

  • The authenticated account email was not populated.
  • The State or Territory selection was not populated.

Inspection established that the public Enroll controller and view no longer contained the complete enrollment workflow expected by the existing Enroll model.

The model still contained the required operations, including:

ensureMember()
coreAccount()
registryStates()
profileForMember()
saveEnrollment()


The public controller and view were rebuilt around those existing model operations.

Before continuing Experiment 3, the restored /enroll baseline was tested independently.

The user confirmed that the enrollment page was again operating correctly.

Only after establishing a working baseline did Experiment 3 continue.

This distinction is important.

The broken enrollment page was not evidence concerning the cross-Module library hypothesis. It was an unrelated baseline defect discovered while preparing the experiment.


Experimental Controller Verification


The temporary Experiment 3 controller was generated from the confirmed working Enroll controller.

A differential comparison was performed before deployment.

The comparison established:

Removed baseline lines: 0


The only modification was the addition of the temporary experimental controller method.

The resulting controller also passed PHP syntax validation:

No syntax errors detected


This protected the established /enroll baseline from being unknowingly altered by the experimental instrumentation.


Routing Observation


The first attempt to execute the experimental controller method resulted in:

404
Not Found
The requested resource does not exist.


The cause was subsequently established:

The experimental controller method required an explicit ChAoS MVC route.

The method existed and passed PHP syntax validation, but the requested URL had not yet been routed by the framework.

After the required route was provided, the experiment executed normally through ChAoS MVC.

This routing requirement is an implementation finding from the experiment and is preserved as part of the research record.


Method


Enroll was temporarily given an experimental controller operation.

During normal ChAoS MVC execution, the Enroll controller:

  1. Confirmed execution through the MVC lifecycle.
  2. Located Registry's geography library.
  3. Loaded the Registry-owned library.
  4. Executed Registry's geography operation.
  5. Supplied the same known public address used during Experiment 2.
  6. Received the resulting latitude, longitude, and MGRS coordinate.
  7. Validated the returned geographic data.

Registry's library remained at:

/home/microcms/public_html/arsrosaic.org/user/modules/registry/lib/geography.php


No Registry library was copied into Enroll.

No Registry library was moved into Core.


Observed Result


ChAoS MVC Cross-Module Library Experiment 3
===========================================

[1] Normal MVC execution
PASS
Enroll controller is executing through ChAoS MVC.

[2] Locate Registry-owned library
PASS
/home/microcms/public_html/arsrosaic.org/user/modules/registry/lib/geography.php

[3] Load Registry-owned library from Enroll
PASS

[4] Execute Registry geography from Enroll
PASS

[5] Validate result returned to Enroll
PASS
Latitude: 38.8986989
Longitude: -77.0351875
MGRS: 18S UJ 23510 07503

===========================================
EXPERIMENT 3 PASSED
===========================================

Observed evidence:
- Enroll executed through the normal ChAoS MVC lifecycle.
- Enroll located a library physically owned by Registry.
- Enroll loaded Registry's geography library.
- Registry loaded its own geocoder and MGRS dependencies.
- Enroll executed Registry-owned domain functionality.
- The completed geographic result returned to Enroll.
- No Registry library was copied into Enroll or Core.



Experiment 3 Finding


Experiment 3 established the complete relationship proposed by the hypothesis.

A ChAoS MVC user Module successfully consumed a library physically and logically owned by another ChAoS MVC user Module.

Specifically:

Enroll
    |
    +-- consumes --> Registry Geography
                         |
                         +-- Registry Geocoder
                         |
                         +-- Registry MGRS


The consuming Module did not require a duplicate implementation.

The owning Module retained its internal dependencies.

ChAoS MVC Core was not modified.


Result Consistency


Experiments 2 and 3 independently returned the same geographic result for the same supplied address.

Experiment 2:

Latitude: 38.8986989
Longitude: -77.0351875
MGRS: 18S UJ 23510 07503


Experiment 3:

Latitude: 38.8986989
Longitude: -77.0351875
MGRS: 18S UJ 23510 07503


The matching results provide additional evidence that the change in consuming environment did not alter the Registry-owned operation.

The same Registry implementation produced the same observed result when consumed externally and when consumed by Enroll through ChAoS MVC.


Evidence Established


The three experiments progressively established the following:

  • Experiment 1
    • A Registry-owned library can be loaded outside Registry.
    • Registry-owned dependencies can remain with the owning Module.
    • The Registry geography class can be instantiated externally.

  • Experiment 2
    • External user-space code can execute Registry-owned domain functionality.
    • Registry's geocoder can produce coordinates for the consumer.
    • Registry's MGRS implementation can process those coordinates.
    • The completed result can be returned to the consumer.

  • Experiment 3
    • Another ChAoS MVC user Module can consume Registry-owned functionality.
    • Consumption can occur during normal MVC execution.
    • Registry retains ownership of the implementation.
    • Registry retains ownership of its internal dependencies.
    • The consuming Module does not require a duplicate implementation.
    • ChAoS MVC Core does not require modification.


Conclusion


Hypothesis Established


The research hypothesis is established under the conditions tested.

A ChAoS MVC user Module can own reusable domain libraries that are consumed by other user Modules without moving those libraries into Core or duplicating their implementation within each consuming Module.

The research demonstrated this using the Registry and Enroll Modules.

Registry retained ownership of:

geography.php
geocoder.php
mgrs.php


Enroll successfully consumed Registry's geography functionality through ChAoS MVC and received the completed result.

No Registry geography implementation was copied into Enroll.

No Registry geography implementation was moved into ChAoS MVC Core.


Architectural Implication


The experiment establishes a viable ChAoS MVC architectural pattern:

Core
    |
    +-- provides framework capabilities

User Module A
    |
    +-- owns a domain
    |
    +-- owns reusable domain libraries
            |
            +-- consumed by User Module B
            |
            +-- consumed by User Module C
            |
            +-- consumed by other authorized user-space components


This allows a Module that is authoritative for a particular domain to remain the root of that domain's implementation.

Other Modules can grow outward from that root without reproducing it.

The result also preserves an important architectural boundary:

Reusable does not automatically mean Core.

Framework functionality belongs in Core.

Domain functionality can remain with the Module that owns the domain, even when multiple Modules need to consume it.


Application to Ars Rosaic


For the Ars Rosaic platform, Registry is the authoritative organizational and geographic root.

Registry can therefore retain ownership of domain capabilities such as:

  • Geographic determination.
  • Geocoding.
  • MGRS conversion.
  • Other Registry-owned geographic operations.
  • Additional reusable Registry domain capabilities established through future development and qualification.

Modules such as Enroll can consume those capabilities rather than implementing competing versions of the same rules.

The resulting architecture can remain:

Registry
    |
    +-- authoritative organizational data
    |
    +-- authoritative geographic capabilities
    |
    +-- reusable Registry-owned libraries
            |
            +-- Enroll
            +-- Covens
            +-- Academy
            +-- other Modules where required


This does not establish that every user Module should expose reusable libraries.

It establishes that a user Module can do so when the architecture requires it.

The owning Module remains responsible for the domain.


Research Principle


This research began with an architectural hypothesis rather than an architectural conclusion.

The fact that PHP permits one file to include another was not considered sufficient evidence that the proposed ChAoS MVC architecture was established.

The hypothesis was progressively tested:

Can it load?
        |
        v
Can it execute?
        |
        v
Can another ChAoS MVC Module consume it during MVC execution?
        |
        v
Established


Each conclusion followed an observed result.

The implementation was therefore adopted only after the evidence demonstrated that the proposed relationship actually operates under ChAoS MVC.

Evidence is the root of the conclusion.


Final Research Status


Hypothesis:
A ChAoS MVC user Module can own reusable domain libraries
that other user Modules consume without moving those
libraries into Core.

Experiment 1 — Cross-Module Loading
PASS

Experiment 2 — Cross-Module Domain Execution
PASS

Experiment 3 — ChAoS MVC Module-to-Module Consumption
PASS

Conclusion
ESTABLISHED