Feature-Focused Organization

prompt.md

Your project structure follows a Feature-Focused Organization principle, which is an excellent way to manage complex applications by grouping related functionalities together. Here’s a breakdown of how your structure aligns with best practices:

---

Key Principles of Feature-Focused Organization

1. Group by Feature First – Organize code primarily by business features rather than technical layers.
2. Modules Represent Business Domains – Each module corresponds to a business context (e.g., Auth, Package, User).
3. Features Represent Specific User Actions – Each feature within a module represents a use case (e.g., IssueToken, SubmitPackage).
4. Complete Feature Folders – Each feature folder contains all components needed to implement that feature.
5. Keep Interfaces and Implementations Separate – Business logic is defined in handlers and services, keeping infrastructure independent.
6. Consistent Naming and Structure – Uniform structure across modules, making it easy to navigate and maintain.

---

Hierarchy & Organization

• Modules (Auth, Package, User, etc.) → Represent Business Domains.
• Features (IssueToken, RevokeToken, SubmitPackage, etc.) → Represent User Actions/Operations.
• Components (Handlers, Controllers, Services, DTOs) → Technical implementations.

---

Example Project Structure

src/
├── Domain/                          # Core business models and logic (independent of infrastructure)
│   ├── Auth/                        # Authentication business logic
│   │   ├── Entity/                  # Entities representing domain models
│   │   ├── Repository/              # Data access interfaces
│   │   ├── Service/                 # Business logic services
│   │   ├── Command/                 # Actions that modify state
│   │   ├── Event/                   # Notifications of state changes
│   │   ├── Exception/               # Custom exceptions
│   │   └── ValueObject/             # Immutable objects
│   │
│   ├── Package/                     # Package tracking and submission logic
│   │   ├── Entity/
│   │   ├── Repository/
│   │   ├── Service/
│   │   ├── Command/
│   │   ├── Event/
│   │   ├── Factory/
│   │   └── Exception/
│   │
│   └── User/                        # User-related business logic
│       ├── Entity/
│       ├── Repository/
│       ├── Service/
│       ├── Command/
│       ├── Event/
│       └── Exception/
│
├── Feature/                         # Business features organized by capability
│   ├── Authentication/              # Authentication-related features
│   │   ├── IssueToken/              # Feature for issuing API tokens
│   │   │   ├── Handler/             # Business logic handlers
│   │   │   ├── Service/             # Feature-specific services
│   │   │   ├── UI/                  # User interface components
│   │   │   │   ├── Http/            # HTTP controllers
│   │   │   │   ├── Console/         # CLI commands
│   │   │   └── DTO/                 # Data Transfer Objects
│   │   │
│   │   ├── RevokeToken/             # Feature for revoking API tokens
│   │   │   ├── Handler/
│   │   │   ├── UI/
│   │   │   ├── Service/
│   │   │   └── DTO/
│   │
│   ├── PackageManagement/           # Features related to package handling
│   │   ├── SubmitPackage/
│   │   │   ├── Handler/
│   │   │   ├── Service/
│   │   │   ├── UI/
│   │   │   ├── Workflow/            # Temporal workflows
│   │   │   └── DTO/
│   │   │
│   │   ├── UpdatePackage/
│   │   │   ├── Handler/
│   │   │   ├── UI/
│   │   │   ├── Service/
│   │   │   └── DTO/
│   │
│   ├── WebhookProcessing/           # Features for handling webhooks
│   │   ├── ReceiveWebhook/
│   │   │   ├── Handler/
│   │   │   ├── Service/
│   │   │   ├── UI/
│   │   │   └── DTO/
│   │   │
│   │   └── DispatchWebhook/
│   │       ├── Handler/
│   │       ├── Workflow/
│   │       └── DTO/
│
├── Infrastructure/                  # External dependencies and infrastructure
│   ├── Persistence/                 # ORM and database persistence
│   │   ├── CycleOrm/
│   │   ├── SearchIndex/
│   │   └── Cache/
│   │
│   ├── ExternalService/             # Third-party service integrations
│   │   ├── GitHub/
│   │   ├── OpenAI/
│   │   └── CloudStorage/
│   │
│   ├── Bus/                         # Command and event bus implementations
│   │   ├── CommandBus/
│   │   └── EventBus/
│   │
│   ├── Workflow/                    # Temporal workflow implementations
│   │   └── Temporal/
│   │
│   └── Security/                    # Security & authentication mechanisms
│
├── Application/                     # Application bootstrapping and services
│   ├── Bootloader/                  # Application initialization
│   ├── Middleware/                  # HTTP middleware
│   ├── Interceptor/                 # Request/response interceptors
│   ├── Response/                    # Shared response objects
│   ├── Service/                     # Core services
│   ├── Bus/                         # Application-wide command/event bus interfaces
│   └── Kernel.php                    # Application kernel
│
└── UI/                              # User Interface Layer
    ├── Http/                        # HTTP API components
    │   ├── Action/                  # HTTP request handlers
    │   ├── Filter/                  # Request validation
    │   ├── Resource/                 # Response formatting
    │   └── Middleware/               # HTTP middleware
    │
    ├── Console/                      # CLI-based commands
    │   ├── BaseCommand.php
    │   ├── CommandHandler.php
    │   └── InteractiveShell.php

Folder Descriptions:

Domain Layer

• Domain/: Contains the core business concepts, rules, and interfaces.
  • Entity/: Business domain objects with identity.
  • Command/: Immutable objects representing intentions to change system state.
  • Event/: Notifications of state changes that have occurred.
  • Repository/: Interfaces for data access and storage.
  • Factory/: Interfaces for creating domain entities.
  • Exception/: Domain-specific exceptions.
  • ValueObject/: Immutable objects with no identity, only attributes.

Feature Layer

• Feature/: Business capabilities organized by functional area.
  • Handler/: Business logic for processing commands and queries.
  • DTO/: Data Transfer Objects for request/response modeling.
  • Service/: Feature-specific services for business operations.
  • UI/: User interfaces organized by interface type (Http, Console).
    • Action/: Single-purpose HTTP endpoint classes.
    • Filter/: Request validation and mapping.
    • Resource/: Response formatting for HTTP.
  • Workflow/: Temporal workflow definitions.
    • Activity/: Workflow activity implementations.

Infrastructure Layer

• Infrastructure/: Technical implementations and external integrations.
  • Persistence/: Data storage implementations.
    • CycleOrm/: ORM implementation for database access.
    • SearchIndex/: Search indexing implementation.
  • ExternalService/: Integrations with external services.
  • Bus/: Command and event bus implementations.
  • Workflow/: Workflow orchestration implementation.

Application Layer

• Application/: Application services and bootstrapping.
  • Bootloader/: Application initialization.
  • Middleware/: HTTP request preprocessing.
  • Interceptor/: HTTP request/response manipulation.
  • Response/: Shared response formatting.
  • Bus/: Command and event bus interfaces.
  • Service/: Cross-cutting application services.

UI Layer

• UI/: Shared UI components.
  • Http/: Base HTTP component classes.
  • Console/: Base console component classes.

Key Architectural Benefits:

1. Clear Domain Boundaries: Domain concepts are isolated and well-defined.
2. Feature Cohesion: Related functionality is grouped together by business capability.
3. Service Boundary Flexibility: Commands and events at the domain level facilitate service extraction.
4. Implementation Independence: Domain doesn't depend on infrastructure.
5. Single Responsibility: Each class has a clear, focused purpose.
6. Clean Testability: Separation of concerns makes testing easier.
7. Interface-Based Design: Interfaces define contracts before implementation.
8. Command-Query Separation: Distinct handling for state changes vs. queries.

This architecture provides a solid foundation for building complex applications while maintaining flexibility for future changes in service boundaries. It combines the best aspects of domain-driven design, feature-focused organization, and clean architecture principles.