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
+<?php
+return [
+    'default' => 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
+<?php
+return [
+    'default' => 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