Copy-Based Framework

Phexium uses a copy-based distribution model rather than a traditional package dependency approach. The framework code lives directly in your project's src/ directory, not hidden in vendor/.

Key Benefits

How It Differs

When you clone Phexium, you receive the complete framework source code as part of your project:

No Framework Lock-In

The framework code belongs to your project. There is no external dependency to manage, no version constraints to satisfy, no breaking changes forced upon you. If Phexium development stops tomorrow, your project continues unchanged.

Full Transparency

Every framework component is visible and readable. No "black box" behavior hidden in vendor packages. When debugging, you can step through framework code. When learning, you can study the implementation directly.

Local Customization

Modify any framework file to suit your specific needs without maintaining a separate fork:

• Adapt abstractions to your domain
• Change default behaviors
• Extend core components
• Remove features you don't need

Your modifications stay local to your project.

Selective Updates

When Phexium releases updates, you control what enters your project:

# Add upstream as remote (one-time setup)
git remote add upstream https://gitlab.com/phexium/framework.git

# Fetch upstream changes
git fetch upstream

# Review what changed in framework
git diff HEAD upstream/trunk -- src/

# Merge selectively or cherry-pick specific commits
git cherry-pick <commit-hash>

Compare upstream changes against your customizations. Accept improvements that benefit your project. Ignore changes that would conflict with your modifications.

Git-Native Workflow

All framework changes are tracked in your project's Git history:

# Make changes to src/
git diff src/                    # Review framework modifications
git add src/
git commit -m "Custom: Extended CommandBus for async support"

You maintain a complete audit trail of customizations. Every modification is documented, reviewable, and reversible.

Directory Structure

The src/ directory contains the Phexium framework core (namespace: Phexium):

• src/Application/ - Command/Query/Event base classes
• src/Domain/ - Domain layer interfaces
• src/Plugin/ - Port & Adapter implementations
• src/Presentation/ - Presentation layer interfaces

The app/ directory contains your application code (namespace: App). The demo application provides working examples of framework usage.

Trade-offs

This distribution model requires developers to:

• Understand framework code when making modifications
• Manage merges when incorporating upstream updates
• Take responsibility for framework-level changes

These trade-offs align with Phexium's educational purpose: the framework serves as a learning tool and reference implementation, not a black-box dependency.

When to Modify Framework Code

Consider modifying src/ when:

• Default behavior doesn't fit your domain requirements
• You need to add cross-cutting concerns to base classes
• You want to experiment with architectural variations

Avoid modifying src/ when:

• The change belongs in application code (app/)
• You can achieve the goal through composition or configuration
• The modification would break existing patterns without clear benefit