Skip to content

Refactor Framework to Package-Based Monorepo Structure #418

@armanist

Description

@armanist

Description

Currently, the framework is a monolithic library with a mix of "Libraries", "Modules", and core components in src/. This structure creates tight coupling and unclear boundaries (e.g., Config depending on Loader which depends on App).

We propose moving to a Monorepo Structure using a packages/ directory. This will allow for:

  1. Strict Decoupling: Each package has its own src and explicit dependencies.
  2. Clearer Architecture: Separation of Core (Kernel) from App (Adapters) and Features (Http, Database).
  3. Future-Proofing: Easier to extract/publish standalone components.

Proposed Structure

The src/ directory will be dissolved into packages/.

/packages
  ├── Core/          (Bootstrap: App Kernel, Container, Config, Loader, Env, Hook)
  ├── App/           (Glue: Web/Console Adapters, Traits)
  ├── Http/          (Request, Response, Middleware)
  ├── Console/       (Commands, Output)
  ├── Pipeline/      (New Shared Pipe Builder)
  ├── Database/      (ORM, Migrations)
  ├── Security/      (Csrf, Encryption, Hasher)
  ├── ...            (See full plan for Auth, Session, etc.)

Synergy with Issue #373 (App Bootstrapping)

This refactoring directly supports the goals of Issue #373:

  • Boot Pipeline: The new packages/Pipeline component enables the "Boot Stages" logic.
  • Explicit Kernel: Moving App, Container, and Loader to packages/Core physically defines the "Application Execution Boundary".
  • DI Ownership: Centralizing Container in Core makes it the clear owner of service lifetimes.

Critical Changes

  • Split App: src/App/App.php moves to packages/Core. src/App/Adapters moves to packages/App. This resolves the circular dependency between the Kernel and the Http layer.
  • Config in Core: src/Config moves to packages/Core to resolve dependencies on Loader and Di.
  • Security Grouping: Csrf, Encryption, and Hasher are grouped under packages/Security.

Migration Checklist

  • Create packages/ directory structure.
  • Phase 1: Core: Move App, Di, Environment, Hook, Loader, Config, Tracer to packages/Core.
  • Phase 2: Features: Move Auth, Database, Session, View, Validation to packages/*.
  • Phase 3: Http/Console: Move Http, Console, Router to packages/*.
  • Phase 4: App Glue: Move Adapters and Traits to packages/App.
  • Phase 5: Cleanup: Remove empty src/ directories.
  • Phase 6: Wiring: Update root composer.json autoloading to map Quantum\ to these new paths.
  • Run tests to verify the move.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions