From 39bc5977e3ba197122f9d6f14fef0ae645cb7613 Mon Sep 17 00:00:00 2001 From: Yury Pikhtarev Date: Sat, 21 Jun 2025 21:15:40 +0400 Subject: [PATCH] feat(architecture): implement hexagonal architecture foundation with DDD structure (#1991) * feat(architecture): implement hexagonal architecture foundation with DDD structure - Add comprehensive hexagonal architecture directory structure for TorrentPier 3.0 - Create Domain, Application, Infrastructure, and Presentation layers - Establish bounded contexts for Forum, Tracker, and User domains - Add detailed README.md files for each layer and subdirectory with implementation guidance - Include hexagonal architecture specification document with migration strategy - Update composer dependencies to support new architecture - Set up foundation for CQRS, event-driven design, and clean separation of concerns This establishes the structural foundation for migrating TorrentPier to Domain-Driven Design principles using ports and adapters pattern. Future features will be built using this architecture while existing code remains functional during gradual migration. BREAKING CHANGE: New directory structure changes development workflow for new features * docs: update README files across layers to enhance clarity and consistency - Added detailed guidelines for Markdown file formatting in CLAUDE.md. - Improved README files in the Application, Domain, and Infrastructure layers to include additional context and examples. - Ensured all README files follow a consistent structure and style for better readability. - Updated documentation for Forum, Tracker, and User domains to reflect recent architectural changes. These updates aim to provide clearer guidance for developers and maintainers, aligning with the project's focus on modern architecture and clean code practices. --- CLAUDE.md | 20 + config/README.md | 53 +++ docs/specs/hexagonal-architecture-spec.md | 436 ++++++++++++++++++ src/Application/Forum/Command/README.md | 11 + src/Application/Forum/Handler/README.md | 9 + src/Application/Forum/Query/README.md | 10 + src/Application/README.md | 14 + src/Application/Tracker/Command/README.md | 21 + src/Application/Tracker/Handler/README.md | 9 + src/Application/Tracker/Query/README.md | 10 + src/Application/User/Command/README.md | 11 + src/Application/User/Handler/README.md | 9 + src/Application/User/Query/README.md | 10 + src/Domain/Forum/Exception/README.md | 8 + src/Domain/Forum/Model/README.md | 15 + src/Domain/Forum/Repository/README.md | 9 + src/Domain/Forum/ValueObject/README.md | 10 + src/Domain/README.md | 15 + src/Domain/Shared/Event/README.md | 15 + src/Domain/Shared/Exception/README.md | 10 + src/Domain/Shared/Model/README.md | 10 + src/Domain/Shared/Repository/README.md | 9 + src/Domain/Shared/ValueObject/README.md | 10 + src/Domain/Tracker/Exception/README.md | 8 + src/Domain/Tracker/Model/README.md | 19 + src/Domain/Tracker/Repository/README.md | 9 + src/Domain/Tracker/ValueObject/README.md | 23 + src/Domain/User/Exception/README.md | 9 + src/Domain/User/Model/README.md | 15 + src/Domain/User/Repository/README.md | 10 + src/Domain/User/ValueObject/README.md | 11 + src/Infrastructure/Cache/File/README.md | 9 + src/Infrastructure/Cache/Memcached/README.md | 9 + src/Infrastructure/Cache/Redis/README.md | 9 + src/Infrastructure/Email/Template/README.md | 16 + src/Infrastructure/Email/Transport/README.md | 10 + .../FileStorage/Local/README.md | 11 + src/Infrastructure/FileStorage/S3/README.md | 11 + .../Persistence/Database/README.md | 9 + .../Persistence/Migration/README.md | 10 + .../Persistence/Repository/README.md | 29 ++ src/Infrastructure/README.md | 11 + src/Presentation/Cli/Commands/README.md | 10 + .../Http/Controllers/Admin/README.md | 30 ++ .../Http/Controllers/Api/README.md | 31 ++ .../Http/Controllers/Web/README.md | 16 + src/Presentation/Http/Middleware/README.md | 12 + src/Presentation/Http/Requests/README.md | 25 + src/Presentation/Http/Responses/README.md | 11 + src/Presentation/README.md | 11 + 50 files changed, 1118 insertions(+) create mode 100644 config/README.md create mode 100644 docs/specs/hexagonal-architecture-spec.md create mode 100644 src/Application/Forum/Command/README.md create mode 100644 src/Application/Forum/Handler/README.md create mode 100644 src/Application/Forum/Query/README.md create mode 100644 src/Application/README.md create mode 100644 src/Application/Tracker/Command/README.md create mode 100644 src/Application/Tracker/Handler/README.md create mode 100644 src/Application/Tracker/Query/README.md create mode 100644 src/Application/User/Command/README.md create mode 100644 src/Application/User/Handler/README.md create mode 100644 src/Application/User/Query/README.md create mode 100644 src/Domain/Forum/Exception/README.md create mode 100644 src/Domain/Forum/Model/README.md create mode 100644 src/Domain/Forum/Repository/README.md create mode 100644 src/Domain/Forum/ValueObject/README.md create mode 100644 src/Domain/README.md create mode 100644 src/Domain/Shared/Event/README.md create mode 100644 src/Domain/Shared/Exception/README.md create mode 100644 src/Domain/Shared/Model/README.md create mode 100644 src/Domain/Shared/Repository/README.md create mode 100644 src/Domain/Shared/ValueObject/README.md create mode 100644 src/Domain/Tracker/Exception/README.md create mode 100644 src/Domain/Tracker/Model/README.md create mode 100644 src/Domain/Tracker/Repository/README.md create mode 100644 src/Domain/Tracker/ValueObject/README.md create mode 100644 src/Domain/User/Exception/README.md create mode 100644 src/Domain/User/Model/README.md create mode 100644 src/Domain/User/Repository/README.md create mode 100644 src/Domain/User/ValueObject/README.md create mode 100644 src/Infrastructure/Cache/File/README.md create mode 100644 src/Infrastructure/Cache/Memcached/README.md create mode 100644 src/Infrastructure/Cache/Redis/README.md create mode 100644 src/Infrastructure/Email/Template/README.md create mode 100644 src/Infrastructure/Email/Transport/README.md create mode 100644 src/Infrastructure/FileStorage/Local/README.md create mode 100644 src/Infrastructure/FileStorage/S3/README.md create mode 100644 src/Infrastructure/Persistence/Database/README.md create mode 100644 src/Infrastructure/Persistence/Migration/README.md create mode 100644 src/Infrastructure/Persistence/Repository/README.md create mode 100644 src/Infrastructure/README.md create mode 100644 src/Presentation/Cli/Commands/README.md create mode 100644 src/Presentation/Http/Controllers/Admin/README.md create mode 100644 src/Presentation/Http/Controllers/Api/README.md create mode 100644 src/Presentation/Http/Controllers/Web/README.md create mode 100644 src/Presentation/Http/Middleware/README.md create mode 100644 src/Presentation/Http/Requests/README.md create mode 100644 src/Presentation/Http/Responses/README.md create mode 100644 src/Presentation/README.md diff --git a/CLAUDE.md b/CLAUDE.md index 8f8a0bf86..aff1a9bf8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -137,3 +137,23 @@ The TorrentPier 3.0 release represents a major architectural shift focused on: - **Language system**: Update global $lang usage to new Language singleton methods When working with this codebase, prioritize modern architecture patterns and clean code practices. Focus on the new systems in `/src/` directory rather than maintaining legacy compatibility. + +## Markdown File Guidelines + +When creating or editing `.md` files in this project, follow these linting rules: + +### MD032 - Lists surrounded by blank lines +Always add blank lines before and after lists: + +```markdown +Some text here. + +- First item +- Second item +- Third item + +More text here. +``` + +### MD047 - Files should end with a single newline +Ensure every markdown file ends with exactly one newline character at the end of the file. diff --git a/config/README.md b/config/README.md new file mode 100644 index 000000000..1d4ccad07 --- /dev/null +++ b/config/README.md @@ -0,0 +1,53 @@ +# Application Configuration + +System configuration files using PHP arrays for type safety and IDE support: + +- **app.php**: Core application settings + - Site name, URL, timezone + - Debug mode, environment + - Feature flags and toggles + +- **database.php**: Database connection settings + - Multiple connection definitions + - Read/write splitting configuration + - Connection pooling settings + +- **cache.php**: Cache driver configurations + - Redis, Memcached, file-based settings + - TTL defaults per cache type + - Cache key prefixes + +- **tracker.php**: BitTorrent tracker settings + - Announce intervals + - Peer limits + - Ratio requirements + +- **environments/**: Environment-specific overrides + - Development, staging, production settings + - Local developer configurations + +Example database configuration: +```php + env('DB_CONNECTION', 'mysql'), + + 'connections' => [ + 'mysql' => [ + 'driver' => 'mysql', + 'host' => env('DB_HOST', '127.0.0.1'), + 'port' => env('DB_PORT', 3306), + 'database' => env('DB_DATABASE', 'tp'), + 'username' => env('DB_USERNAME', 'root'), + 'password' => env('DB_PASSWORD', ''), + 'charset' => 'utf8mb4', + 'collation' => 'utf8mb4_unicode_ci', + 'options' => [ + PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION, + PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC, + PDO::ATTR_EMULATE_PREPARES => false, + ], + ], + ], +]; +``` \ No newline at end of file diff --git a/docs/specs/hexagonal-architecture-spec.md b/docs/specs/hexagonal-architecture-spec.md new file mode 100644 index 000000000..07dc0a672 --- /dev/null +++ b/docs/specs/hexagonal-architecture-spec.md @@ -0,0 +1,436 @@ +# Hexagonal Architecture Directory Structure Specification + +## Overview + +This document specifies the new hexagonal architecture directory structure for TorrentPier 3.0. The structure follows Domain-Driven Design (DDD) principles and implements a clean separation of concerns through hexagonal architecture (ports and adapters pattern). + +## Directory Structure + +``` +/src/ +├── Domain/ # Core business logic - no framework dependencies +│ ├── Forum/ # Forum bounded context +│ │ ├── Model/ # Aggregates and entities +│ │ ├── ValueObject/ # Value objects (PostId, ThreadTitle, etc.) +│ │ ├── Repository/ # Repository interfaces +│ │ └── Exception/ # Domain-specific exceptions +│ ├── Tracker/ # BitTorrent tracker bounded context +│ │ ├── Model/ # Torrent, Peer aggregates +│ │ ├── ValueObject/ # InfoHash, PeerId, etc. +│ │ ├── Repository/ # Repository interfaces +│ │ └── Exception/ # Tracker-specific exceptions +│ ├── User/ # User management bounded context +│ │ ├── Model/ # User aggregate +│ │ ├── ValueObject/ # UserId, Email, Username +│ │ ├── Repository/ # User repository interface +│ │ └── Exception/ # Authentication/authorization exceptions +│ └── Shared/ # Shared kernel - minimal shared concepts +│ ├── Model/ # Base classes (AggregateRoot, Entity) +│ ├── ValueObject/ # Common value objects (Id, DateTime) +│ └── Event/ # Domain events base classes +│ +├── Application/ # Application services - orchestration layer +│ ├── Forum/ +│ │ ├── Command/ # Commands (CreatePost, LockThread) +│ │ ├── Query/ # Queries (GetThreadList, SearchPosts) +│ │ └── Handler/ # Command and query handlers +│ ├── Tracker/ +│ │ ├── Command/ # Commands (RegisterTorrent, ProcessAnnounce) +│ │ ├── Query/ # Queries (GetPeerList, GetTorrentStats) +│ │ └── Handler/ # Command and query handlers +│ └── User/ +│ ├── Command/ # Commands (RegisterUser, ChangePassword) +│ ├── Query/ # Queries (GetUserProfile, SearchUsers) +│ └── Handler/ # Command and query handlers +│ +├── Infrastructure/ # External concerns and implementations +│ ├── Persistence/ # Data persistence layer +│ │ ├── Database/ # Database adapter and connection management +│ │ ├── Migration/ # Database migrations +│ │ └── Repository/ # Repository implementations +│ ├── Cache/ # Caching implementations +│ │ ├── Redis/ # Redis adapter +│ │ ├── Memcached/ # Memcached adapter +│ │ └── File/ # File-based cache adapter +│ ├── Email/ # Email service implementations +│ │ ├── Template/ # Email templates +│ │ └── Transport/ # SMTP, API transports +│ └── FileStorage/ # File storage abstractions +│ ├── Local/ # Local filesystem storage +│ └── S3/ # AWS S3 storage adapter +│ +└── Presentation/ # User interface layer + ├── Http/ # Web interface + │ ├── Controllers/ # HTTP controllers + │ │ ├── Admin/ # Admin panel controllers + │ │ ├── Api/ # REST API controllers + │ │ └── Web/ # Web UI controllers + │ ├── Middleware/ # HTTP middleware (auth, CORS, etc.) + │ ├── Requests/ # Request DTOs and validation + │ └── Responses/ # Response transformers + └── Cli/ # Command line interface + └── Commands/ # Console commands + +# Additional directories (outside /src/) +/config/ # Application configuration +├── app.php # Main application settings +├── database.php # Database connections +├── cache.php # Cache drivers configuration +├── tracker.php # BitTorrent tracker settings +└── environments/ # Environment-specific overrides + +/tests/ # Test suites (Pest) +├── Unit/ # Unit tests (mirrors src/ structure) +├── Feature/ # Feature/Integration tests +├── Pest.php # Pest configuration +└── TestCase.php # Base test case +``` + +## Directory README.md Templates + +### Domain Layer READMEs + +#### `/src/Domain/README.md` +```markdown +# Domain Layer + +This directory contains the core business logic of TorrentPier. Code here should: +- Have no dependencies on frameworks or infrastructure +- Represent pure business rules and domain models +- Be testable in isolation +- Use only PHP language features and domain concepts + +## Bounded Contexts +- **Forum**: Discussion forums, posts, threads +- **Tracker**: BitTorrent tracking, peers, torrents +- **User**: User management, authentication, profiles +- **Shared**: Minimal shared concepts between contexts +``` + +#### `/src/Domain/Tracker/Model/README.md` +```markdown +# Tracker Domain Models + +Contains aggregate roots and entities for the BitTorrent tracker: +- `Torrent`: Aggregate root for torrent management +- `Peer`: Entity representing a BitTorrent peer +- `TorrentStatistics`: Value object for torrent stats + +Example: +```php +class Torrent extends AggregateRoot +{ + public function announce(Peer $peer, AnnounceEvent $event): void + { + // Business logic for handling announces + } +} +``` + +#### `/src/Domain/Tracker/ValueObject/README.md` +```markdown +# Tracker Value Objects + +Immutable objects representing domain concepts: +- `InfoHash`: 20-byte torrent identifier +- `PeerId`: Peer client identifier +- `Port`: Network port (1-65535) +- `BytesTransferred`: Upload/download bytes + +Example: +```php +final class InfoHash +{ + private string $hash; + + public function __construct(string $hash) + { + $this->guardAgainstInvalidHash($hash); + $this->hash = $hash; + } +} +``` + +### Application Layer READMEs + +#### `/src/Application/README.md` +```markdown +# Application Layer + +Contains application services that orchestrate domain objects to fulfill use cases. +- Commands: Write operations that change state +- Queries: Read operations for data retrieval +- Handlers: Process commands and queries + +This layer should: +- Coordinate domain objects +- Handle transactions +- Dispatch domain events +- Not contain business logic +``` + +#### `/src/Application/Tracker/Command/README.md` +```markdown +# Tracker Commands + +Commands representing write operations: +- `RegisterTorrentCommand`: Register new torrent +- `UpdateTorrentCommand`: Modify torrent details +- `DeleteTorrentCommand`: Remove torrent from tracker + +Example: +```php +final class RegisterTorrentCommand +{ + public function __construct( + public readonly string $infoHash, + public readonly int $uploaderId, + public readonly string $name, + public readonly int $size + ) {} +} +``` + +### Infrastructure Layer READMEs + +#### `/src/Infrastructure/README.md` +```markdown +# Infrastructure Layer + +Technical implementations and external service adapters: +- Database persistence +- Caching mechanisms +- Email services +- File storage +- Third-party integrations + +Infrastructure depends on domain, not vice versa. +``` + +#### `/src/Infrastructure/Persistence/Repository/README.md` +```markdown +# Repository Implementations + +Concrete implementations of domain repository interfaces: +- Uses database adapter for persistence +- Implements caching strategies +- Handles query optimization +- Supports multiple database backends + +Example: +```php +class TorrentRepository implements TorrentRepositoryInterface +{ + public function __construct( + private DatabaseAdapterInterface $db + ) {} + + public function findByInfoHash(InfoHash $infoHash): ?Torrent + { + // Database adapter implementation + $row = $this->db->select('torrents') + ->where('info_hash', $infoHash->toString()) + ->first(); + + return $row ? $this->hydrateFromRow($row) : null; + } +} +``` + +### Presentation Layer READMEs + +#### `/src/Presentation/README.md` +```markdown +# Presentation Layer + +User interface implementations: +- HTTP controllers for web and API +- CLI commands for console operations +- Request/response handling +- Input validation +- Output formatting + +This layer translates between external format and application format. +``` + +#### `/src/Presentation/Http/Controllers/Api/README.md` +```markdown +# API Controllers + +RESTful API endpoints following OpenAPI specification: +- JSON request/response format +- Proper HTTP status codes +- HATEOAS where applicable +- Rate limiting aware + +Example: +```php +class UserController +{ + public function register(RegisterRequest $request): JsonResponse + { + $command = new RegisterUserCommand( + $request->getUsername(), + $request->getEmail(), + $request->getPassword() + ); + + $userId = $this->commandBus->handle($command); + + return new JsonResponse([ + 'id' => $userId, + 'username' => $request->getUsername() + ], Response::HTTP_CREATED); + } +} +``` + +#### `/src/Presentation/Http/Controllers/Admin/README.md` +```markdown +# Admin Panel Controllers + +Administrative interface controllers with enhanced security: +- Role-based access control (RBAC) +- Audit logging for all actions +- Additional authentication checks +- Administrative dashboards and reports + +Example: +```php +class AdminUserController +{ + public function index(Request $request): Response + { + $query = new GetUsersQuery( + page: $request->getPage(), + filters: $request->getFilters() + ); + + $users = $this->queryBus->handle($query); + + return $this->render('admin/users/index', [ + 'users' => $users, + 'filters' => $request->getFilters() + ]); + } +} +``` + +#### `/config/README.md` +```markdown +# Application Configuration + +System configuration files using PHP arrays for type safety and IDE support: + +- **app.php**: Core application settings + - Site name, URL, timezone + - Debug mode, environment + - Feature flags and toggles + +- **database.php**: Database connection settings + - Multiple connection definitions + - Read/write splitting configuration + - Connection pooling settings + +- **cache.php**: Cache driver configurations + - Redis, Memcached, file-based settings + - TTL defaults per cache type + - Cache key prefixes + +- **tracker.php**: BitTorrent tracker settings + - Announce intervals + - Peer limits + - Ratio requirements + +- **environments/**: Environment-specific overrides + - Development, staging, production settings + - Local developer configurations + +Example database configuration: +```php + env('DB_CONNECTION', 'mysql'), + + 'connections' => [ + 'mysql' => [ + 'driver' => 'mysql', + 'host' => env('DB_HOST', '127.0.0.1'), + 'port' => env('DB_PORT', 3306), + 'database' => env('DB_DATABASE', 'tp'), + 'username' => env('DB_USERNAME', 'root'), + 'password' => env('DB_PASSWORD', ''), + 'charset' => 'utf8mb4', + 'collation' => 'utf8mb4_unicode_ci', + 'options' => [ + PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION, + PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC, + PDO::ATTR_EMULATE_PREPARES => false, + ], + ], + ], +]; +``` + +## Implementation Order + +1. **Phase 1: Foundation** + + - Create directory structure + - Set up base classes in Domain/Shared + - Configure dependency injection + +2. **Phase 2: Domain Modeling** + + - Implement core aggregates + - Create value objects + - Define repository interfaces + +3. **Phase 3: Application Services** + + - Create commands and queries + - Implement handlers + - Set up event dispatching + +4. **Phase 4: Infrastructure** + + - Implement repositories + - Configure database adapter + - Set up caching + +5. **Phase 5: Presentation** + + - Create controllers + - Implement middleware + - Build CLI commands + +## Migration Strategy + +- Existing code remains in current locations +- New features built in hexagonal architecture +- Gradual migration using strangler fig pattern +- Legacy adapters bridge old and new code +- Feature flags control rollout + +## Key Principles + +1. **Dependency Rule**: Dependencies point inward (Presentation → Application → Domain) +2. **Domain Isolation**: Business logic has no framework dependencies +3. **Interface Segregation**: Small, focused interfaces +4. **CQRS**: Separate read and write models +5. **Event-Driven**: Domain events for cross-context communication + +## Testing Strategy + +- **Domain**: Pure unit tests, no mocks needed +- **Application**: Unit tests with mocked repositories +- **Infrastructure**: Integration tests with real services +- **Presentation**: E2E tests for user journeys + +## Notes for Developers + +- Start reading code from the Domain layer +- Business rules live in aggregates, not services +- Use value objects for type safety +- Prefer composition over inheritance +- Keep bounded contexts loosely coupled diff --git a/src/Application/Forum/Command/README.md b/src/Application/Forum/Command/README.md new file mode 100644 index 000000000..eae098d4a --- /dev/null +++ b/src/Application/Forum/Command/README.md @@ -0,0 +1,11 @@ +# Forum Commands + +Commands representing write operations: + +- `CreateThreadCommand`: Start new discussion +- `CreatePostCommand`: Reply to thread +- `EditPostCommand`: Modify existing post +- `LockThreadCommand`: Lock thread from replies +- `DeletePostCommand`: Remove post + +Commands are simple DTOs containing operation data. \ No newline at end of file diff --git a/src/Application/Forum/Handler/README.md b/src/Application/Forum/Handler/README.md new file mode 100644 index 000000000..4af804611 --- /dev/null +++ b/src/Application/Forum/Handler/README.md @@ -0,0 +1,9 @@ +# Forum Handlers + +Command and query handlers for forum operations: + +- `CreateThreadHandler`: Handles thread creation +- `CreatePostHandler`: Handles post creation +- `GetThreadListHandler`: Retrieves thread listings + +Handlers coordinate between domain and infrastructure layers. \ No newline at end of file diff --git a/src/Application/Forum/Query/README.md b/src/Application/Forum/Query/README.md new file mode 100644 index 000000000..845ef3948 --- /dev/null +++ b/src/Application/Forum/Query/README.md @@ -0,0 +1,10 @@ +# Forum Queries + +Read-only queries for forum data: + +- `GetThreadListQuery`: Paginated thread listing +- `GetPostsByThreadQuery`: Thread posts with pagination +- `SearchPostsQuery`: Full-text post search +- `GetForumStatsQuery`: Forum statistics + +Queries return DTOs optimized for presentation. \ No newline at end of file diff --git a/src/Application/README.md b/src/Application/README.md new file mode 100644 index 000000000..f7a27973c --- /dev/null +++ b/src/Application/README.md @@ -0,0 +1,14 @@ +# Application Layer + +Contains application services that orchestrate domain objects to fulfill use cases. + +- Commands: Write operations that change state +- Queries: Read operations for data retrieval +- Handlers: Process commands and queries + +This layer should: + +- Coordinate domain objects +- Handle transactions +- Dispatch domain events +- Not contain business logic \ No newline at end of file diff --git a/src/Application/Tracker/Command/README.md b/src/Application/Tracker/Command/README.md new file mode 100644 index 000000000..800c6579d --- /dev/null +++ b/src/Application/Tracker/Command/README.md @@ -0,0 +1,21 @@ +# Tracker Commands + +Commands representing write operations: + +- `RegisterTorrentCommand`: Register new torrent +- `UpdateTorrentCommand`: Modify torrent details +- `DeleteTorrentCommand`: Remove torrent from tracker + +Example: + +```php +final class RegisterTorrentCommand +{ + public function __construct( + public readonly string $infoHash, + public readonly int $uploaderId, + public readonly string $name, + public readonly int $size + ) {} +} +``` \ No newline at end of file diff --git a/src/Application/Tracker/Handler/README.md b/src/Application/Tracker/Handler/README.md new file mode 100644 index 000000000..b30755d33 --- /dev/null +++ b/src/Application/Tracker/Handler/README.md @@ -0,0 +1,9 @@ +# Tracker Handlers + +Command and query handlers for tracker operations: + +- `RegisterTorrentHandler`: Processes torrent registration +- `GetTorrentDetailsHandler`: Retrieves torrent information +- `UpdateTorrentHandler`: Handles torrent updates + +Note: High-performance announce operations bypass this layer. \ No newline at end of file diff --git a/src/Application/Tracker/Query/README.md b/src/Application/Tracker/Query/README.md new file mode 100644 index 000000000..05e42e39f --- /dev/null +++ b/src/Application/Tracker/Query/README.md @@ -0,0 +1,10 @@ +# Tracker Queries + +Read-only queries for tracker data: + +- `GetTorrentDetailsQuery`: Single torrent information +- `GetPeerListQuery`: Active peers for torrent +- `GetTorrentStatsQuery`: Download/upload statistics +- `SearchTorrentsQuery`: Browse and filter torrents + +Optimized for high-performance read operations. \ No newline at end of file diff --git a/src/Application/User/Command/README.md b/src/Application/User/Command/README.md new file mode 100644 index 000000000..fbf0342be --- /dev/null +++ b/src/Application/User/Command/README.md @@ -0,0 +1,11 @@ +# User Commands + +Commands for user management operations: + +- `RegisterUserCommand`: New user registration +- `ChangePasswordCommand`: Password update +- `UpdateProfileCommand`: Profile modifications +- `ActivateUserCommand`: Account activation +- `BanUserCommand`: User suspension + +These commands trigger domain events for cross-context synchronization. \ No newline at end of file diff --git a/src/Application/User/Handler/README.md b/src/Application/User/Handler/README.md new file mode 100644 index 000000000..8f34ce418 --- /dev/null +++ b/src/Application/User/Handler/README.md @@ -0,0 +1,9 @@ +# User Handlers + +Command and query handlers for user operations: + +- `RegisterUserHandler`: Processes user registration +- `ChangePasswordHandler`: Handles password changes +- `GetUserProfileHandler`: Retrieves user profiles + +Handlers manage transactions and event dispatching. \ No newline at end of file diff --git a/src/Application/User/Query/README.md b/src/Application/User/Query/README.md new file mode 100644 index 000000000..1307a51ec --- /dev/null +++ b/src/Application/User/Query/README.md @@ -0,0 +1,10 @@ +# User Queries + +Read operations for user data: + +- `GetUserProfileQuery`: User profile details +- `SearchUsersQuery`: User search with filters +- `GetUserStatisticsQuery`: Upload/download stats +- `GetUserPermissionsQuery`: Authorization data + +Returns DTOs suitable for presentation layer. \ No newline at end of file diff --git a/src/Domain/Forum/Exception/README.md b/src/Domain/Forum/Exception/README.md new file mode 100644 index 000000000..07a483fe6 --- /dev/null +++ b/src/Domain/Forum/Exception/README.md @@ -0,0 +1,8 @@ +# Forum Domain Exceptions + +Domain-specific exceptions for forum operations: + +- `ThreadLockedException`: Attempt to post in locked thread +- `PostEditTimeExpiredException`: Edit time limit exceeded +- `ForumAccessDeniedException`: Insufficient permissions +- `InvalidPostContentException`: Post validation failed \ No newline at end of file diff --git a/src/Domain/Forum/Model/README.md b/src/Domain/Forum/Model/README.md new file mode 100644 index 000000000..6dafb0894 --- /dev/null +++ b/src/Domain/Forum/Model/README.md @@ -0,0 +1,15 @@ +# Forum Domain Models + +Contains aggregate roots and entities for the forum system: + +- `Forum`: Forum category aggregate +- `Thread`: Discussion thread aggregate root +- `Post`: Individual post entity +- `Attachment`: File attachment entity + +Business rules enforced at this level: + +- Post editing time limits +- Thread locking rules +- Forum access permissions +- Post moderation workflow \ No newline at end of file diff --git a/src/Domain/Forum/Repository/README.md b/src/Domain/Forum/Repository/README.md new file mode 100644 index 000000000..1a8430801 --- /dev/null +++ b/src/Domain/Forum/Repository/README.md @@ -0,0 +1,9 @@ +# Forum Repository Interfaces + +Repository interfaces for forum aggregates: + +- `ForumRepositoryInterface`: Forum aggregate persistence +- `ThreadRepositoryInterface`: Thread aggregate persistence +- `PostRepositoryInterface`: Post queries (read-only) + +These interfaces define contracts that infrastructure must implement. \ No newline at end of file diff --git a/src/Domain/Forum/ValueObject/README.md b/src/Domain/Forum/ValueObject/README.md new file mode 100644 index 000000000..eb8aec659 --- /dev/null +++ b/src/Domain/Forum/ValueObject/README.md @@ -0,0 +1,10 @@ +# Forum Value Objects + +Immutable objects representing forum concepts: + +- `PostId`: Unique post identifier +- `ThreadTitle`: Thread title with validation +- `PostContent`: Formatted post content +- `ForumSlug`: URL-friendly forum identifier + +These objects ensure type safety and encapsulate validation rules. \ No newline at end of file diff --git a/src/Domain/README.md b/src/Domain/README.md new file mode 100644 index 000000000..cb9254a68 --- /dev/null +++ b/src/Domain/README.md @@ -0,0 +1,15 @@ +# Domain Layer + +This directory contains the core business logic of TorrentPier. Code here should: + +- Have no dependencies on frameworks or infrastructure +- Represent pure business rules and domain models +- Be testable in isolation +- Use only PHP language features and domain concepts + +## Bounded Contexts + +- **Forum**: Discussion forums, posts, threads +- **Tracker**: BitTorrent tracking, peers, torrents +- **User**: User management, authentication, profiles +- **Shared**: Minimal shared concepts between contexts \ No newline at end of file diff --git a/src/Domain/Shared/Event/README.md b/src/Domain/Shared/Event/README.md new file mode 100644 index 000000000..11656fb4a --- /dev/null +++ b/src/Domain/Shared/Event/README.md @@ -0,0 +1,15 @@ +# Domain Events + +Base classes and interfaces for domain event system: + +- `DomainEvent`: Base event interface +- `EventRecording`: Trait for aggregate event recording +- `AggregateHistory`: Event sourcing support + +Example events: + +- `UserRegisteredEvent` +- `TorrentUploadedEvent` +- `ThreadCreatedEvent` + +Events enable loose coupling between bounded contexts. \ No newline at end of file diff --git a/src/Domain/Shared/Exception/README.md b/src/Domain/Shared/Exception/README.md new file mode 100644 index 000000000..2c5a556bd --- /dev/null +++ b/src/Domain/Shared/Exception/README.md @@ -0,0 +1,10 @@ +# Shared Domain Exceptions + +Base exception classes used across all bounded contexts: + +- `DomainException`: Base domain exception +- `InvalidArgumentException`: Invalid input validation +- `EntityNotFoundException`: Generic entity not found +- `BusinessRuleViolationException`: Business rule violations + +These provide common exception handling patterns without coupling contexts. \ No newline at end of file diff --git a/src/Domain/Shared/Model/README.md b/src/Domain/Shared/Model/README.md new file mode 100644 index 000000000..4daf36150 --- /dev/null +++ b/src/Domain/Shared/Model/README.md @@ -0,0 +1,10 @@ +# Shared Domain Models + +Base classes and interfaces used across bounded contexts: + +- `AggregateRoot`: Base class for all aggregates +- `Entity`: Base class for entities +- `DomainEvent`: Interface for domain events +- `ValueObject`: Base value object interface + +These provide common functionality while maintaining context boundaries. \ No newline at end of file diff --git a/src/Domain/Shared/Repository/README.md b/src/Domain/Shared/Repository/README.md new file mode 100644 index 000000000..999f9d300 --- /dev/null +++ b/src/Domain/Shared/Repository/README.md @@ -0,0 +1,9 @@ +# Shared Repository Interfaces + +Common repository patterns and base interfaces: + +- `RepositoryInterface`: Base repository contract +- `ReadOnlyRepositoryInterface`: Query-only operations +- `AggregateRepositoryInterface`: Aggregate-specific methods + +These define common persistence patterns without implementation details. \ No newline at end of file diff --git a/src/Domain/Shared/ValueObject/README.md b/src/Domain/Shared/ValueObject/README.md new file mode 100644 index 000000000..afc5b7bc6 --- /dev/null +++ b/src/Domain/Shared/ValueObject/README.md @@ -0,0 +1,10 @@ +# Shared Value Objects + +Common value objects used across contexts: + +- `Id`: Generic identifier base class +- `DateTime`: Immutable datetime wrapper +- `Money`: Monetary value representation +- `Percentage`: Percentage value (0-100) + +These are minimal shared concepts that don't violate bounded context principles. \ No newline at end of file diff --git a/src/Domain/Tracker/Exception/README.md b/src/Domain/Tracker/Exception/README.md new file mode 100644 index 000000000..73ae0f882 --- /dev/null +++ b/src/Domain/Tracker/Exception/README.md @@ -0,0 +1,8 @@ +# Tracker Domain Exceptions + +Domain-specific exceptions for tracker operations: + +- `InvalidInfoHashException`: Malformed info hash +- `InactiveTorrentException`: Torrent not active +- `PeerLimitExceededException`: Too many peers +- `InvalidAnnounceException`: Protocol violation \ No newline at end of file diff --git a/src/Domain/Tracker/Model/README.md b/src/Domain/Tracker/Model/README.md new file mode 100644 index 000000000..124456276 --- /dev/null +++ b/src/Domain/Tracker/Model/README.md @@ -0,0 +1,19 @@ +# Tracker Domain Models + +Contains aggregate roots and entities for the BitTorrent tracker: + +- `Torrent`: Aggregate root for torrent management +- `Peer`: Entity representing a BitTorrent peer +- `TorrentStatistics`: Value object for torrent stats + +Example: + +```php +class Torrent extends AggregateRoot +{ + public function announce(Peer $peer, AnnounceEvent $event): void + { + // Business logic for handling announces + } +} +``` \ No newline at end of file diff --git a/src/Domain/Tracker/Repository/README.md b/src/Domain/Tracker/Repository/README.md new file mode 100644 index 000000000..3745d6e4e --- /dev/null +++ b/src/Domain/Tracker/Repository/README.md @@ -0,0 +1,9 @@ +# Tracker Repository Interfaces + +Repository interfaces for tracker aggregates: + +- `TorrentRepositoryInterface`: Torrent aggregate persistence +- `PeerRepositoryInterface`: Peer data access +- `TrackerStatsRepositoryInterface`: Statistics queries + +These define persistence contracts without implementation details. \ No newline at end of file diff --git a/src/Domain/Tracker/ValueObject/README.md b/src/Domain/Tracker/ValueObject/README.md new file mode 100644 index 000000000..cd3fcf0ee --- /dev/null +++ b/src/Domain/Tracker/ValueObject/README.md @@ -0,0 +1,23 @@ +# Tracker Value Objects + +Immutable objects representing domain concepts: + +- `InfoHash`: 20-byte torrent identifier +- `PeerId`: Peer client identifier +- `Port`: Network port (1-65535) +- `BytesTransferred`: Upload/download bytes + +Example: + +```php +final class InfoHash +{ + private string $hash; + + public function __construct(string $hash) + { + $this->guardAgainstInvalidHash($hash); + $this->hash = $hash; + } +} +``` \ No newline at end of file diff --git a/src/Domain/User/Exception/README.md b/src/Domain/User/Exception/README.md new file mode 100644 index 000000000..f689a7943 --- /dev/null +++ b/src/Domain/User/Exception/README.md @@ -0,0 +1,9 @@ +# User Domain Exceptions + +Domain-specific exceptions for user operations: + +- `UserNotFoundException`: User not found +- `DuplicateUsernameException`: Username already taken +- `InvalidCredentialsException`: Authentication failed +- `UserNotActivatedException`: Account not activated +- `PasswordComplexityException`: Weak password \ No newline at end of file diff --git a/src/Domain/User/Model/README.md b/src/Domain/User/Model/README.md new file mode 100644 index 000000000..2001b3ebd --- /dev/null +++ b/src/Domain/User/Model/README.md @@ -0,0 +1,15 @@ +# User Domain Models + +Contains user management aggregates and entities: + +- `User`: User aggregate root +- `UserProfile`: User profile information +- `UserCredentials`: Authentication credentials +- `UserPermissions`: Authorization rules + +Business rules: + +- Password complexity requirements +- Username uniqueness +- Email verification workflow +- Account activation/deactivation \ No newline at end of file diff --git a/src/Domain/User/Repository/README.md b/src/Domain/User/Repository/README.md new file mode 100644 index 000000000..9d4c463c7 --- /dev/null +++ b/src/Domain/User/Repository/README.md @@ -0,0 +1,10 @@ +# User Repository Interface + +Repository interface for user aggregate: + +- `UserRepositoryInterface`: User persistence and retrieval + - `findById(UserId $id): ?User` + - `findByUsername(Username $username): ?User` + - `findByEmail(Email $email): ?User` + - `save(User $user): void` + - `delete(User $user): void` \ No newline at end of file diff --git a/src/Domain/User/ValueObject/README.md b/src/Domain/User/ValueObject/README.md new file mode 100644 index 000000000..79c930883 --- /dev/null +++ b/src/Domain/User/ValueObject/README.md @@ -0,0 +1,11 @@ +# User Value Objects + +Immutable objects for user domain: + +- `UserId`: Unique user identifier +- `Username`: Username with validation +- `Email`: Email address with format validation +- `HashedPassword`: Secure password representation +- `UserRole`: User role enumeration + +These ensure data integrity and type safety. \ No newline at end of file diff --git a/src/Infrastructure/Cache/File/README.md b/src/Infrastructure/Cache/File/README.md new file mode 100644 index 000000000..9f781c1b9 --- /dev/null +++ b/src/Infrastructure/Cache/File/README.md @@ -0,0 +1,9 @@ +# File Cache Adapter + +File system-based caching implementation: + +- Simple file-based storage +- Suitable for single-server deployments +- Directory structure optimization +- Lock file support for concurrency +- Automatic garbage collection \ No newline at end of file diff --git a/src/Infrastructure/Cache/Memcached/README.md b/src/Infrastructure/Cache/Memcached/README.md new file mode 100644 index 000000000..2e60b7e0b --- /dev/null +++ b/src/Infrastructure/Cache/Memcached/README.md @@ -0,0 +1,9 @@ +# Memcached Cache Adapter + +Memcached-based caching implementation: + +- Simple key-value caching +- Distributed cache support +- Automatic key expiration +- Connection pooling +- Consistent hashing for distribution \ No newline at end of file diff --git a/src/Infrastructure/Cache/Redis/README.md b/src/Infrastructure/Cache/Redis/README.md new file mode 100644 index 000000000..da7e090aa --- /dev/null +++ b/src/Infrastructure/Cache/Redis/README.md @@ -0,0 +1,9 @@ +# Redis Cache Adapter + +Redis-based caching implementation: + +- High-performance key-value storage +- Support for data structures (lists, sets, hashes) +- TTL management +- Pub/sub for cache invalidation +- Cluster support for scalability \ No newline at end of file diff --git a/src/Infrastructure/Email/Template/README.md b/src/Infrastructure/Email/Template/README.md new file mode 100644 index 000000000..3497a96ba --- /dev/null +++ b/src/Infrastructure/Email/Template/README.md @@ -0,0 +1,16 @@ +# Email Templates + +Email template management: + +- HTML and plain text templates +- Template variables and placeholders +- Multi-language support +- Template caching +- Preview functionality + +Common templates: + +- User registration confirmation +- Password reset +- Torrent notifications +- Forum post notifications \ No newline at end of file diff --git a/src/Infrastructure/Email/Transport/README.md b/src/Infrastructure/Email/Transport/README.md new file mode 100644 index 000000000..0de823895 --- /dev/null +++ b/src/Infrastructure/Email/Transport/README.md @@ -0,0 +1,10 @@ +# Email Transport + +Email delivery mechanisms: + +- `SmtpTransport`: Traditional SMTP delivery +- `SendgridTransport`: SendGrid API integration +- `MailgunTransport`: Mailgun API integration +- `NullTransport`: Testing/development transport + +Supports queuing and retry mechanisms. \ No newline at end of file diff --git a/src/Infrastructure/FileStorage/Local/README.md b/src/Infrastructure/FileStorage/Local/README.md new file mode 100644 index 000000000..cb0fdac49 --- /dev/null +++ b/src/Infrastructure/FileStorage/Local/README.md @@ -0,0 +1,11 @@ +# Local File Storage + +Local filesystem storage implementation: + +- Direct disk storage +- Directory structure management +- File permissions handling +- Atomic file operations +- Cleanup and maintenance + +Used for torrent files, avatars, and attachments. \ No newline at end of file diff --git a/src/Infrastructure/FileStorage/S3/README.md b/src/Infrastructure/FileStorage/S3/README.md new file mode 100644 index 000000000..c008d9f5a --- /dev/null +++ b/src/Infrastructure/FileStorage/S3/README.md @@ -0,0 +1,11 @@ +# S3 File Storage + +Amazon S3 (or compatible) storage implementation: + +- Cloud object storage +- Pre-signed URLs for direct uploads +- CDN integration support +- Lifecycle policies +- Multi-region support + +Provides scalable storage for large deployments. \ No newline at end of file diff --git a/src/Infrastructure/Persistence/Database/README.md b/src/Infrastructure/Persistence/Database/README.md new file mode 100644 index 000000000..c250b60e8 --- /dev/null +++ b/src/Infrastructure/Persistence/Database/README.md @@ -0,0 +1,9 @@ +# Database Adapter + +Database connection and query building layer: + +- `DatabaseAdapterInterface`: Common database operations +- `QueryBuilder`: Fluent query construction +- `ConnectionPool`: Connection management + +Provides abstraction over raw database access. diff --git a/src/Infrastructure/Persistence/Migration/README.md b/src/Infrastructure/Persistence/Migration/README.md new file mode 100644 index 000000000..1f203e645 --- /dev/null +++ b/src/Infrastructure/Persistence/Migration/README.md @@ -0,0 +1,10 @@ +# Database Migrations + +Schema version control and migration management: + +- Migration files for schema changes +- Seed data for initial setup +- Rollback support +- Migration history tracking + +Uses Phinx or similar migration tool. \ No newline at end of file diff --git a/src/Infrastructure/Persistence/Repository/README.md b/src/Infrastructure/Persistence/Repository/README.md new file mode 100644 index 000000000..002760d4a --- /dev/null +++ b/src/Infrastructure/Persistence/Repository/README.md @@ -0,0 +1,29 @@ +# Repository Implementations + +Concrete implementations of domain repository interfaces: + +- Uses database adapter for persistence +- Implements caching strategies +- Handles query optimization +- Supports multiple database backends + +Example: + +```php +class TorrentRepository implements TorrentRepositoryInterface +{ + public function __construct( + private DatabaseAdapterInterface $db + ) {} + + public function findByInfoHash(InfoHash $infoHash): ?Torrent + { + // Database adapter implementation + $row = $this->db->select('torrents') + ->where('info_hash', $infoHash->toString()) + ->first(); + + return $row ? $this->hydrateFromRow($row) : null; + } +} +``` \ No newline at end of file diff --git a/src/Infrastructure/README.md b/src/Infrastructure/README.md new file mode 100644 index 000000000..2098a9f97 --- /dev/null +++ b/src/Infrastructure/README.md @@ -0,0 +1,11 @@ +# Infrastructure Layer + +Technical implementations and external service adapters: + +- Database persistence +- Caching mechanisms +- Email services +- File storage +- Third-party integrations + +Infrastructure depends on domain, not vice versa. \ No newline at end of file diff --git a/src/Presentation/Cli/Commands/README.md b/src/Presentation/Cli/Commands/README.md new file mode 100644 index 000000000..5e2cf1239 --- /dev/null +++ b/src/Presentation/Cli/Commands/README.md @@ -0,0 +1,10 @@ +# CLI Commands + +Console commands for administrative tasks: + +- `UserCreateCommand`: Create users from CLI +- `CacheClearCommand`: Clear cache stores +- `MigrateCommand`: Run database migrations +- `CronCommand`: Execute scheduled tasks + +Built using Symfony Console component. \ No newline at end of file diff --git a/src/Presentation/Http/Controllers/Admin/README.md b/src/Presentation/Http/Controllers/Admin/README.md new file mode 100644 index 000000000..6e478949b --- /dev/null +++ b/src/Presentation/Http/Controllers/Admin/README.md @@ -0,0 +1,30 @@ +# Admin Panel Controllers + +Administrative interface controllers with enhanced security: + +- Role-based access control (RBAC) +- Audit logging for all actions +- Additional authentication checks +- Administrative dashboards and reports + +Example: + +```php +class AdminUserController +{ + public function index(Request $request): Response + { + $query = new GetUsersQuery( + page: $request->getPage(), + filters: $request->getFilters() + ); + + $users = $this->queryBus->handle($query); + + return $this->render('admin/users/index', [ + 'users' => $users, + 'filters' => $request->getFilters() + ]); + } +} +``` \ No newline at end of file diff --git a/src/Presentation/Http/Controllers/Api/README.md b/src/Presentation/Http/Controllers/Api/README.md new file mode 100644 index 000000000..7d944db2e --- /dev/null +++ b/src/Presentation/Http/Controllers/Api/README.md @@ -0,0 +1,31 @@ +# API Controllers + +RESTful API endpoints following OpenAPI specification: + +- JSON request/response format +- Proper HTTP status codes +- HATEOAS where applicable +- Rate limiting aware + +Example: + +```php +class UserController +{ + public function register(RegisterRequest $request): JsonResponse + { + $command = new RegisterUserCommand( + $request->getUsername(), + $request->getEmail(), + $request->getPassword() + ); + + $userId = $this->commandBus->handle($command); + + return new JsonResponse([ + 'id' => $userId, + 'username' => $request->getUsername() + ], Response::HTTP_CREATED); + } +} +``` \ No newline at end of file diff --git a/src/Presentation/Http/Controllers/Web/README.md b/src/Presentation/Http/Controllers/Web/README.md new file mode 100644 index 000000000..015c2d19c --- /dev/null +++ b/src/Presentation/Http/Controllers/Web/README.md @@ -0,0 +1,16 @@ +# Web Controllers + +Traditional web interface controllers: + +- HTML response generation +- Template rendering +- Form handling +- Session management +- CSRF protection + +Controllers for: + +- Forum browsing and posting +- Torrent browsing and downloading +- User profiles and settings +- Search functionality \ No newline at end of file diff --git a/src/Presentation/Http/Middleware/README.md b/src/Presentation/Http/Middleware/README.md new file mode 100644 index 000000000..c5a1d1a0c --- /dev/null +++ b/src/Presentation/Http/Middleware/README.md @@ -0,0 +1,12 @@ +# HTTP Middleware + +Request/response pipeline middleware: + +- `AuthenticationMiddleware`: User authentication +- `AuthorizationMiddleware`: Permission checks +- `CsrfProtectionMiddleware`: CSRF token validation +- `RateLimitMiddleware`: Request throttling +- `LocalizationMiddleware`: Language detection +- `CorsMiddleware`: Cross-origin resource sharing + +Middleware follows PSR-15 standard. \ No newline at end of file diff --git a/src/Presentation/Http/Requests/README.md b/src/Presentation/Http/Requests/README.md new file mode 100644 index 000000000..8e0a47d1c --- /dev/null +++ b/src/Presentation/Http/Requests/README.md @@ -0,0 +1,25 @@ +# HTTP Requests + +Request objects and validation: + +- Request DTOs with validation rules +- Type-safe access to request data +- File upload handling +- Input sanitization +- Custom validation rules + +Example: + +```php +class RegisterRequest extends FormRequest +{ + public function rules(): array + { + return [ + 'username' => ['required', 'string', 'min:3', 'max:20', 'unique:users'], + 'email' => ['required', 'email', 'unique:users'], + 'password' => ['required', 'string', 'min:8', 'confirmed'], + ]; + } +} +``` \ No newline at end of file diff --git a/src/Presentation/Http/Responses/README.md b/src/Presentation/Http/Responses/README.md new file mode 100644 index 000000000..bce8c8325 --- /dev/null +++ b/src/Presentation/Http/Responses/README.md @@ -0,0 +1,11 @@ +# HTTP Responses + +Response transformation and formatting: + +- Response factories +- JSON transformers +- View presenters +- Error response formatting +- Content negotiation + +Ensures consistent API responses and proper HTTP semantics. \ No newline at end of file diff --git a/src/Presentation/README.md b/src/Presentation/README.md new file mode 100644 index 000000000..3e99a424b --- /dev/null +++ b/src/Presentation/README.md @@ -0,0 +1,11 @@ +# Presentation Layer + +User interface implementations: + +- HTTP controllers for web and API +- CLI commands for console operations +- Request/response handling +- Input validation +- Output formatting + +This layer translates between external format and application format. \ No newline at end of file