michaelschiemer/docs/planning/SRC_STRUCTURE_IMPROVEMENTS.md

Src Directory Structure Improvements

Current Issues

1. Application Layer Fragmentation

src/Application/
├── Admin/              # Admin features
├── Api/                # API endpoints
├── Auth/               # Authentication
├── Backend/            # Backend integrations?
├── Campaign/           # Campaign management
├── Controller/         # Generic controllers?
├── Design/             # Design system?
├── Http/               # HTTP utilities
├── Service/            # Generic services?
├── Website/            # Website pages
└── ... (20+ directories)

Problem:

• No clear separation between features and infrastructure
• Mix of feature modules and technical layers
• Hard to find related code

2. Framework Layer Organization

src/Framework/
├── Async/
├── AsyncExamples/      # Examples should not be in Framework/
├── Cache/
├── Database/
├── DI/
├── Discovery/
└── ... (50+ directories)

Problem:

• Examples mixed with production code
• Very deep nesting (Database/Schema/Index/Analysis/)
• Some modules could be consolidated

3. Domain Layer Inconsistency

src/Domain/
├── AI/                 # Is this really domain?
├── Common/             # Shared code
├── Contact/
├── Media/
├── Meta/               # What is Meta domain?
├── Newsletter/
├── PreSave/            # Feature-specific
├── SmartLink/
└── User/

Problem:

• Mix of bounded contexts and shared code
• Unclear domain boundaries
• Technical concerns (AI) mixed with business domains

Proposed Improvements

A. Application Layer Restructuring

Option 1: Feature-Based Modules (RECOMMENDED)

src/Application/
├── Admin/                          # Admin Panel Feature
│   ├── Analytics/
│   ├── Content/
│   ├── System/
│   └── Controllers/
├── Api/                            # API Layer
│   ├── V1/
│   ├── V2/
│   └── Middleware/
├── Auth/                           # Authentication Feature
│   ├── Controllers/
│   ├── Middleware/
│   └── Services/
├── Campaign/                       # Campaign Management Feature
│   ├── Controllers/
│   ├── Services/
│   └── ValueObjects/
├── Website/                        # Public Website Feature
│   ├── Controllers/
│   ├── Services/
│   └── templates/
└── Shared/                         # Application-wide shared code
    ├── Controllers/                # Base controllers
    ├── Middleware/
    └── Services/

Benefits:

• Clear feature boundaries
• Related code grouped together
• Easy to find and navigate
• Follows Vertical Slice Architecture

Option 2: Layer-Based Organization

src/Application/
├── Controllers/                    # All controllers
│   ├── Admin/
│   ├── Api/
│   ├── Auth/
│   └── Website/
├── Services/                       # All services
├── Middleware/                     # All middleware
└── ValueObjects/                   # Application VOs

Benefits:

• Technical separation
• Easy to see all controllers/services
• Simpler structure

Downside: Harder to see complete features

B. Framework Layer Improvements

Clean Up Examples:

# Move examples OUT of src/Framework/
src/
├── Framework/                      # Production framework code
│   ├── Cache/
│   ├── Database/
│   ├── DI/
│   └── ...
└── Examples/                       # All examples here
    ├── Async/
    ├── Cache/
    ├── Database/
    └── GraphQL/

Consolidate Deep Nesting:

src/Framework/Database/
├── Connection/                     # Consolidated connection handling
│   ├── Async/
│   ├── Middleware/
│   ├── Pooled/
│   └── ReadWrite/
├── Migration/
│   ├── Commands/
│   ├── Runners/
│   └── ValueObjects/
├── Monitoring/
│   ├── Health/
│   ├── Profiling/
│   └── Metrics/
├── QueryBuilder/
├── Repository/
├── Schema/
│   ├── Blueprint/
│   ├── Comparison/
│   └── Index/
└── UnitOfWork/

Instead of:

Database/
  Monitoring/
    Health/
      Checks/                       # Too deep!

C. Domain Layer Restructuring

Bounded Contexts Approach:

src/Domain/
├── BoundedContexts/                # Clear business domains
│   ├── Campaign/
│   │   ├── Entities/
│   │   ├── ValueObjects/
│   │   ├── Services/
│   │   └── Repositories/
│   ├── Contact/
│   ├── Media/
│   ├── Newsletter/
│   ├── SmartLink/                  # Renamed from PreSave
│   └── User/
├── Shared/                         # Shared Kernel
│   ├── ValueObjects/               # Cross-domain VOs
│   ├── Interfaces/
│   └── Exceptions/
└── Services/                       # Domain Services
    └── AI/                         # AI as domain service

Benefits:

• Clear bounded context boundaries
• Shared kernel explicit
• Domain services separated
• DDD-compliant structure

Migration Strategy

Phase 1: Immediate Cleanup (Week 1)

# 1. Move examples out of Framework
mkdir -p examples
mv src/Framework/AsyncExamples examples/Async
mv src/Framework/Database/Examples examples/Database
# ... repeat for all examples

# 2. Update composer.json autoload
"autoload": {
    "psr-4": {
        "App\\": "src/",
        "Examples\\": "examples/"
    }
}

# 3. Regenerate autoloader
composer dump-autoload

Phase 2: Documentation (Week 2)

# Create architecture docs
docs/architecture/
├── application-layer.md            # Feature-based organization
├── framework-layer.md              # Framework structure
├── domain-layer.md                 # Bounded contexts
└── migration-guide.md              # How to navigate new structure

Phase 3: Gradual Migration (Weeks 3-6)

• Move Application code to feature modules (one at a time)
• Consolidate Framework deep nesting
• Restructure Domain bounded contexts
• Update imports and tests

Recommended Final Structure

michaelschiemer/
├── bin/
├── config/
├── docs/
│   ├── architecture/
│   ├── deployment/
│   └── guides/
├── examples/                       # All framework examples
│   ├── Async/
│   ├── Cache/
│   ├── Database/
│   └── GraphQL/
├── public/                         # Minimal! Only index.php + health.php
├── resources/
│   ├── css/
│   └── js/
├── scripts/
│   ├── debug/
│   ├── test/
│   ├── deployment/
│   └── maintenance/
├── src/
│   ├── Application/                # Feature-based modules
│   │   ├── Admin/
│   │   ├── Api/
│   │   ├── Auth/
│   │   ├── Campaign/
│   │   ├── Website/
│   │   └── Shared/
│   ├── Domain/                     # Bounded contexts
│   │   ├── BoundedContexts/
│   │   │   ├── Campaign/
│   │   │   ├── Contact/
│   │   │   ├── Media/
│   │   │   ├── Newsletter/
│   │   │   ├── SmartLink/
│   │   │   └── User/
│   │   ├── Shared/
│   │   └── Services/
│   ├── Framework/                  # Framework (production only)
│   │   ├── Cache/
│   │   ├── Console/
│   │   ├── Database/
│   │   ├── DI/
│   │   ├── Discovery/
│   │   ├── Http/
│   │   └── ...
│   └── Infrastructure/             # External integrations
│       ├── GeoIp/
│       └── ...
├── storage/
├── tests/                          # Mirrors src/ structure
│   ├── Application/
│   ├── Domain/
│   ├── Framework/
│   └── Integration/
├── var/
└── vendor/

Quality Metrics

Before:

• Root files: 105
• Public debug files: 9
• Application directories: 25+
• Framework nesting depth: 6 levels
• Examples in production: Yes

After:

• Root files: ~15 (essential only)
• Public debug files: 0 (SECURITY!)
• Application modules: ~8 (feature-based)
• Framework nesting depth: 3-4 levels max
• Examples location: Separate examples/ directory

Implementation Checklist

• Move debug/test scripts to scripts/
• Clean up public/ directory (SECURITY PRIORITY!)
• Move examples out of src/Framework/
• Create examples/ directory
• Consolidate documentation in docs/
• Restructure Application layer (feature-based)
• Simplify Framework deep nesting
• Organize Domain bounded contexts
• Update composer autoload
• Update all imports
• Update tests to match new structure
• Update .gitignore
• Clear old cache files
• Document new structure
• Create navigation guide

Tools to Create

1. Structure Validator

php console.php structure:validate

# Checks:
# - No PHP files in public/ except index.php/health.php
# - All examples in examples/ directory
# - Cache size warnings
# - Proper namespace structure

2. Automatic Cleanup

php console.php cleanup:project

# Actions:
# - Clear old cache files
# - Remove temporary files
# - Report orphaned files

3. Migration Helper

php console.php migrate:structure --dry-run

# Shows what would be moved/changed
# Then run without --dry-run to execute