DDD & Clean Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• DDD_IMPLEMENTATION_SUMMARY.md
• DDD_IMPLEMENTATION_REPORT_SPEC_WFL_005.md
• DDD_IMPLEMENTATION_REPORT_SPEC_WFL_009.md
• SPEC-WFL-007-IMPLEMENTATION-REPORT.md
• DOCUMENTATION_SUMMARY.md
• README.md
• IMPLEMENTATION_REPORT_SPEC_WFL_003.md

The GoHighLevel Clone project is built upon a rigorous implementation of Domain-Driven Design (DDD) and Clean Architecture principles. This architectural approach ensures that the core business logic—the "Domain"—remains isolated from external concerns like databases, UI frameworks, or third-party integrations. By structuring the codebase into four distinct layers, the system achieves high maintainability, testability, and scalability.

The project follows a "SPEC-First" development methodology, where features are planned in EARS format before being implemented through a DDD cycle of ANALYZE → PRESERVE → IMPROVE. This process ensures that the software evolves while maintaining 100% behavioral consistency and high code quality as defined by the TRUST 5 framework (Tested, Readable, Unified, Secured, Trackable).
Sources: README.md, DOCUMENTATION_SUMMARY.md, DDD_IMPLEMENTATION_SUMMARY.md

Architectural Layers

The system is organized into four concentric layers, where dependencies only point inwards.

This diagram illustrates the directional dependencies between the four layers of the project's Clean Architecture.
Sources: DDD_IMPLEMENTATION_SUMMARY.md, SPEC-WFL-007-IMPLEMENTATION-REPORT.md

1. Domain Layer

This is the innermost layer containing the core business rules and logic. It is entirely independent of any technology stack or external frameworks.

• Entities: Objects with a unique identity that persist over time (e.g., Workflow, Action, GoalConfig).
• Value Objects: Immutable objects defined by their attributes rather than identity (e.g., ActionConfig, GoalCriteria, WorkflowStatus).
• Domain Services: Logic that doesn't naturally fit within a single entity (e.g., MetricsCalculationService, GoalDetectionService).
• Domain Exceptions: Custom errors specific to business rule violations (e.g., WorkflowMustBeInDraftError).
  Sources: IMPLEMENTATION_REPORT_SPEC_WFL_003.md, DDD_IMPLEMENTATION_REPORT_SPEC_WFL_009.md, SPEC-WFL-007-IMPLEMENTATION-REPORT.md

2. Application Layer

The Application Layer orchestrates the flow of data to and from the domain. It contains the "Use Cases" of the system.

• Use Cases: Specific tasks the system performs, such as AddActionUseCase or ExecuteWorkflowUseCase.
• DTOs (Data Transfer Objects): Plain objects used to pass data across layer boundaries (e.g., CreateActionRequest, GoalResponseDTO).
• Application Services: Orchestrators like WorkflowExecutionService that coordinate domain objects and infrastructure repositories.
  Sources: DDD_IMPLEMENTATION_REPORT_SPEC_WFL_005.md, DDD_IMPLEMENTATION_SUMMARY.md, SPEC-WFL-007-IMPLEMENTATION-REPORT.md

3. Infrastructure Layer

This layer handles technical concerns, providing implementations for the interfaces defined in the inner layers.

• SQLAlchemy Models: Database table definitions (e.g., ActionModel, GoalAchievementModel).
• Repositories: Concrete implementations of data access interfaces (e.g., PostgresGoalRepository).
• External Clients: Integrations with third-party services like Stripe or Twilio.
  Sources: IMPLEMENTATION_REPORT_SPEC_WFL_003.md, SPEC-WFL-007-IMPLEMENTATION-REPORT.md, DDD_IMPLEMENTATION_REPORT_SPEC_WFL_005.md

4. Presentation Layer

The outermost layer responsible for interacting with the user or external systems.

• FastAPI Routes: REST API endpoints that receive requests and return responses.
• Pydantic Schemas: Validation logic for API requests and responses.
  Sources: DDD_IMPLEMENTATION_SUMMARY.md, DDD_IMPLEMENTATION_REPORT_SPEC_WFL_009.md

Workflow Execution System

The Workflow Execution system serves as a primary example of DDD and Clean Architecture in action. It utilizes a state machine to manage the lifecycle of an execution across 7 distinct states.

Execution Lifecycle

The execution engine uses the WorkflowExecution aggregate root to track state transitions and maintain the audit trail via ExecutionLog entities.

State	Description
QUEUED	Initial state when a trigger is activated.
ACTIVE	Currently processing workflow steps.
PAUSED	Manually paused by a user or system event.
WAITING	Waiting for a time delay or external event.
COMPLETED	All actions processed successfully.
FAILED	Terminated due to unrecoverable error or max retries exceeded.
CANCELLED	Manually terminated by an administrator.
Sources: DDD_IMPLEMENTATION_REPORT_SPEC_WFL_005.md

Execution Data Flow

This sequence diagram shows how a workflow execution request flows through the architectural layers.
Sources: DDD_IMPLEMENTATION_REPORT_SPEC_WFL_005.md

Key Components and Metrics

The project enforces high quality standards through specific metrics and structured components.

TRUST 5 Quality Framework

All DDD implementations are validated against these five pillars:

Pillar	Description
Tested	Minimum 85% test coverage, including unit, integration, and acceptance tests.
Readable	Clear naming conventions and comprehensive English documentation.
Unified	Consistent patterns across all modules and architectural layers.
Secured	Multi-tenant isolation and strict input validation.
Trackable	Complete audit trails with timestamps and user tracking.
Sources: README.md, DDD_IMPLEMENTATION_SUMMARY.md, SPEC-WFL-007-IMPLEMENTATION-REPORT.md

Aggregate Roots & Entities

Business logic is encapsulated within these primary structures:

Aggregate Root	Module	Responsibility
Workflow	Workflows	Managing the definition of automation steps and triggers.
Action	Workflows	Managing individual steps within a workflow.
GoalConfig	Workflows	Defining and validating conversion goals.
GoalAchievement	Workflows	Recording when contacts meet specific conversion criteria.
WorkflowExecution	Workflows	Orchestrating the runtime state of a workflow for a contact.
Sources: IMPLEMENTATION_REPORT_SPEC_WFL_003.md, SPEC-WFL-007-IMPLEMENTATION-REPORT.md, DDD_IMPLEMENTATION_REPORT_SPEC_WFL_005.md

Domain-Driven Logic Example: Goal Tracking

The Goal Tracking system (SPEC-WFL-007) demonstrates how domain logic is isolated. The GoalDetectionService evaluates events against GoalCriteria value objects without knowing about the underlying database.

# From src/workflows/domain/goal_entities.py
class GoalConfig(BaseEntity):
    def deactivate(self):
        self.is_active = False
        self.updated_at = datetime.now()

    def matches(self, event_data: dict) -> bool:
        # Business logic for matching criteria
        return self.criteria.evaluate(event_data)

Sources: SPEC-WFL-007-IMPLEMENTATION-REPORT.md, SPEC-WFL-007-EXECUTIVE-SUMMARY.md

Conclusion

The implementation of DDD and Clean Architecture provides a robust foundation for the GoHighLevel Clone project. By isolating business logic in the Domain Layer and using the Application Layer to orchestrate use cases, the system remains resilient to changes in infrastructure and external dependencies. This structure, combined with the TRUST 5 quality framework, ensures that the platform is production-ready, auditable, and easily extensible for future marketing automation features.
Sources: DDD_IMPLEMENTATION_SUMMARY.md, DDD_IMPLEMENTATION_REPORT_SPEC_WFL_005.md