michaelschiemer/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**:
```bash
# 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)
```bash
# 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)
```bash
# 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
```bash
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
```bash
php console.php cleanup:project

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

### 3. Migration Helper
```bash
php console.php migrate:structure --dry-run

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