foundation/Claude.md

# Foundation Framework - Claude Context

## Project Overview

Foundation is a PHP framework built with Domain-Driven Design (DDD) principles, featuring clean architecture, modular design, and modern PHP 8+ capabilities. The framework emphasizes separation of concerns, testability, and maintainability.

## Technology Stack

- **PHP**: 8.1+
- **HTTP Framework**: Slim 4
- **Dependency Injection**: PHP-DI 7.0
- **Database**: MySQL 8.0 with PDO and Repository pattern
- **Logging**: Monolog 3.0
- **Environment Config**: phpdotenv
- **Development**: Docker + Docker Compose with Xdebug

## Architecture Principles

### Clean Architecture Layers

The framework follows strict layered architecture with clear dependency rules:

```
Domain (Pure business logic - No dependencies)
   ↑
Application (Use cases - Depends on Domain only)
   ↑
Infrastructure (External adapters - Depends on Application only)
```

**Layer Dependency Rules:**
- **Domain Layer**: Completely independent, no external dependencies
- **Application Layer**: Can depend on Domain and itself only
- **Infrastructure Layer**: Can depend on Application and itself only

### Module Structure

Each module follows this structure:

```
src/Modules/{ModuleName}/
├── Domain/                           # Pure business logic
│   ├── {Entity}.php                  # Entities with identity
│   ├── {ValueObject}.php             # Immutable value objects
│   └── {Repository}Interface.php     # Repository contracts
├── Application/                      # Use cases and orchestration
│   └── {UseCase}/
│       └── {UseCase}.php
└── Infrastructure/                   # External implementations
    ├── Api/                          # API controllers
    ├── Web/                          # Web controllers
    └── Database/                     # Repository implementations
        ├── {Repository}.php
        ├── Commands/
        └── Queries/
```

### Core Framework Structure

```
src/Core/
├── Application/                      # Application orchestration
│   ├── Application.php               # Main application class
│   ├── Kernel/HttpKernel.php         # HTTP request handling
│   ├── DependencyInjection/          # DI container setup
│   ├── Bootstrapper/                 # Application initialization
│   └── ServiceProvider/              # Service registration abstractions
├── ErrorHandling/                    # Error handling and responses
├── Logging/                          # Logging infrastructure
├── Session/                          # Session management
└── Cache/                            # Caching interfaces
```

## Key Concepts

### 1. Service Providers

Service Providers register services and bootstrap module-specific functionality:

- Register services in the DI container
- Bootstrap module-specific functionality
- Register HTTP routes via attribute scanning
- Auto-discovered by `ModuleLoader` from `src/Modules/*/` directories

### 2. Bootstrappers

Framework components that set up the application before handling requests:

- `ConfigInitializer` - Environment configuration
- `DatabaseInitializer` - Database connections
- `SessionInitializer` - Session management
- `ModuleLoader` - Auto-discovers and loads module service providers

### 3. Dependency Injection Container

The framework uses `InflectableContainer`, a wrapper around PHP-DI with enhanced features:

- **Container Inflection**: Automatic method invocation during object resolution
- **Smart Parameter Resolution**: Intelligent detection of class names vs static values
- **Simplified Registration**: Clean syntax for dependency declaration

**Example:**
```php
// Basic registration
$container->register(ServiceClass::class, [DependencyClass::class]);

// Interface binding
$container->bind(InterfaceClass::class, ImplementationClass::class, [Dep1::class]);

// Container inflection (automatic method calls)
$container->inflect(UnitOfWork::class)
          ->invokeMethod('registerPersister', [ActivityPersister::class]);
```

### 4. Attribute-Based Routing

Controllers use PHP 8+ attributes for route definitions:

- Controllers must implement `ControllerInterface`
- Routes automatically discovered during controller registration
- Available attributes: `#[Get]`, `#[Post]`, `#[Put]`, `#[Delete]`, `#[Route]`, `#[Group]`

**Example:**
```php
#[Group('/api/v1/users')]
class UserController implements ControllerInterface
{
    #[Get('')]
    public function index(): ResponseInterface { }

    #[Get('/{id}')]
    public function show(string $id): ResponseInterface { }

    #[Post('', middleware: [AuthMiddleware::class])]
    public function create(): ResponseInterface { }
}
```

### 5. Unit of Work Pattern

Manages database transactions and entity persistence:

- **Entity Persisters**: Handle database operations for specific entity types
- **Registration**: Via container inflection
- **Transactional**: All operations executed in single transaction

### 6. CQRS Separation

Commands (write operations) and Queries (read operations) are separated:

- Commands in `Infrastructure/Database/Commands/`
- Queries in `Infrastructure/Database/Queries/`

## Development Workflow

### Docker Environment

All development happens in Docker containers:

```bash
# Start environment
make up

# Install dependencies
make install

# Access container shell
make shell
```

**Available Services:**
- **App**: PHP 8.1 + Apache (http://localhost:8000)
- **Database**: MySQL 8.0 (port 3306)
- **phpMyAdmin**: Database management (http://localhost:8080)

### Testing

Comprehensive testing suite with PHPUnit:

```bash
make test              # Run all tests
make test-unit         # Unit tests only
make test-integration  # Integration tests only
make test-coverage     # Coverage report
```

### Code Quality

Static analysis and code quality tools:

```bash
make phpstan           # PHPStan static analysis
make deptrac           # Deptrac layer analysis
make static-analysis   # Run both
make rector            # Preview Rector changes
make rector-fix        # Apply Rector changes
```

## Important Patterns

### Adding New Modules

1. Create directory: `src/Modules/{ModuleName}/`
2. Implement Domain, Application, and Infrastructure layers
3. Create `{ModuleName}ServiceProvider.php` in module root
4. ModuleLoader automatically discovers and registers it

### Creating Service Provider

```php
class MyModuleServiceProvider extends ServiceProvider
{
    public function register(InflectableContainer $container): void
    {
        // Register services
        $container->register(MyController::class, [MyService::class]);

        // Bind interfaces
        $container->bind(MyRepositoryInterface::class, MyRepository::class);
    }
}
```

### Repository Implementation

Repositories use Commands/Queries pattern:

```php
class MyRepository implements MyRepositoryInterface
{
    public function __construct(
        private FetchAllQuery $fetchAll,
        private SaveCommand $save,
        private UnitOfWorkInterface $unitOfWork
    ) {}

    public function save(Entity $entity): void
    {
        $this->unitOfWork->registerNew($entity);
        $this->unitOfWork->commit();
    }
}
```

## Authentication System

Two authentication modes available:

- **Session-based**: Traditional session authentication
- **JWT-based**: Token-based authentication with firebase/php-jwt

Configured via `AUTH_TYPE` environment variable.

## Internationalization

Multi-language support using Symfony Translation:

- Default locale configurable via environment
- YAML translation files
- Module-specific translations supported

## Environment Variables

Key environment variables (see `.env.example`):

```env
# Database
DB_HOST=db
DB_PORT=3306
DB_DATABASE=foundation
DB_USERNAME=foundation_user
DB_PASSWORD=foundation_password

# Authentication
AUTH_TYPE=session
JWT_SECRET=your-secret-key
JWT_ACCESS_TOKEN_TTL=900

# Locale
APP_LOCALE=en
APP_SUPPORTED_LOCALES=en,de,fr
```

## Debugging

Xdebug is configured for debugging:

- Set breakpoints in IDE
- Access application via http://localhost:8000
- Debug sessions automatically connect on port 9003

## Documentation

Complete documentation available in `./documentation/`:

- `application-core.md` - Framework architecture overview
- `application-layers.md` - Layer dependency rules
- `attribute-routing.md` - Route attribute system
- `dependency-injection.md` - DI container guide
- `docker-setup.md` - Docker environment details
- `unit-of-work.md` - Unit of Work pattern
- `authentication.md` - Authentication implementation
- `internationalization.md` - i18n setup

## Common Commands Reference

**Docker:**
```bash
make up              # Start Docker environment
make down            # Stop Docker environment
make shell           # Access container shell
```

**Dependencies:**
```bash
make install         # Install composer dependencies
make dump-autoload   # Refresh autoload files
```

**Testing:**
```bash
make test            # Run all tests
make test-unit       # Run unit tests
make test-coverage   # Generate coverage report
```

**Quality:**
```bash
make phpstan         # Static analysis
make deptrac         # Layer analysis
make rector          # Code quality preview
```

**Database:**
```bash
# Import schema
docker compose exec -T db mysql -u foundation_user -pfoundation_password foundation < database/schema.sql

# Access MySQL CLI
docker compose exec db mysql -u foundation_user -p foundation

# Export database
docker compose exec db mysqldump -u foundation_user -pfoundation_password foundation > backup.sql
```

## Best Practices

1. **Always respect layer boundaries** - Domain must remain pure
2. **Use value objects** for primitive obsession
3. **Keep controllers thin** - Delegate to application services
4. **Use repository interfaces** in Domain layer
5. **Implement CQRS** - Separate read and write operations
6. **Write tests** - Unit tests for domain, integration for infrastructure
7. **Use attributes for routes** - Don't register routes manually
8. **Follow PSR standards** - PSR-4 autoloading, PSR-7 HTTP messages
9. **Document public APIs** - Clear docblocks for interfaces
10. **Use type hints** - Leverage PHP 8.1+ type system

## Troubleshooting

### Docker Issues

- Ensure Docker and Docker Compose are installed
- Check port conflicts (8000, 8080, 3306)
- Verify user permissions: `export USER_ID=$(id -u) && export GROUP_ID=$(id -g)`

### Database Connection Issues

- Verify database container is running: `docker compose ps`
- Check environment variables in `.env`
- Ensure database schema is imported

### Routing Issues

- Verify controller implements `ControllerInterface`
- Check route attributes syntax
- Ensure controller is registered in service provider

### Autoloading Issues

- Run `make dump-autoload` after adding new classes
- Verify PSR-4 namespace matches directory structure