# alibaba/cola architecture

> Architecture diagram of the GitHub repository alibaba/cola, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alibaba/cola
- Repository: https://github.com/alibaba/cola

## Overview

Based on our analysis of the file tree and the README, this project is not a typical “end‑user” application but rather a rich, multi‐module framework under the “COLA” (Clean Object‑Oriented and Layered Architecture) umbrella. It is designed to offer both a set of concrete architectural components (for DTOs, exception handling, state machines, rule engines, etc.) and archetypes (project templates) that enable rapid creation of new service or web applications (even a “light” variant) following the COLA architecture principles. The project also provides several sample applications that demonstrate best practices for applying the architecture.

##### Main Architectural Areas and Modules
- Core COLA Architecture Concept: This includes the layered design (domain, application, adapter/infrastructure) emphasized in the README and supported by the COLA philosophy.
- COLA Components: Represent all the reusable components available in “cola-components.” For example:
- DTOs: (cola-component-dto)
- Exception Handling: (cola-component-exception)
- State Machine: (cola-component-statemachine)
- Domain Starter: (cola-component-domain-starter)
- Extension Points: (cola-component-extension-starter)
- Testing Support: (cola-component-test-container and cola-component-unittest)
- Additional support such as catch-log and rule engine.
- Sample Applications: Under “cola-samples” you have demonstration projects that show how to apply COLA in real-world usage (e.g. the “charge” sample and “craftsman” sample projects).

##### Relationships and Interactions
- At the top, show an “Adapter/Presentation Layer” (for web controllers or other UI components), which points to the “Application Layer” (service/executor logic).
- Below that, show the “Domain Layer”, which includes domain entities, domain services, and domain rules.
- That supportive libraries like “cola-component-dto,” “exception,” and others are used by multiple layers.

##### Architectural Patterns/Principles
- Layered/Hexagonal architecture – emphasize clear separation between domain, application, and adapter/infrastructure.
- Dependency inversion – inner (business) layers are independent of external frameworks/components.
- Domain Driven Design – note the domain entities, domain factories, and domain services as key elements.
- Extensibility – show how extension points (from the extension-starter module) are integrated.
- Reusability – show recurring components (rule engine, state machine, test container) that provide cross-cutting functionalities.

##### Technologies and Frameworks
- Maven is used as the build tool (highlight presence of pom.xml’s and Maven wrapper scripts).
- Java is the implementation language (Java 17+ is required).
- Spring Boot is mentioned specifically for runtime (as seen in the archetype usage instructions).
- For testing support, include the testing containers and unit testing modules.

##### Final Details
- Be as comprehensive as possible: include not only the modules that are directly visible (like “cola-archetypes” and “cola-components”) but also denote configuration files, Maven wrapper mechanisms, and scripts (which support integration, CI and deployment)—even if they are not “runtime” components, they indicate how the project is built and maintained.
- Use text labels or brief annotations to denote design rationale—for instance, why the separation into “adapter”, “application”, “domain” and “infrastructure” is beneficial for managing complexity.
- That this framework is designed to allow rapid development of new applications that adhere to a clean, layered, and decoupled architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A("Core COLA Architecture (pom.xml)"):::core

    subgraph "COLA Archetypes"
        LA("Light Archetype"):::archetype
        SA("Service Archetype"):::archetype
        WA("Web Archetype"):::archetype
    end

    subgraph "COLA Components"
        C1("DTO"):::component
        C2("Exception Handling"):::component
        C3("State Machine"):::component
        C4("Domain Starter"):::component
        C5("Extension Points"):::component
        C6("Test Container"):::component
        C7("Unit Testing"):::component
        C8("Catch-Log Support"):::component
        C9("Rule Engine"):::component
    end

    subgraph "Sample Applications"
        CA("Charge Application"):::sample
        CRA("Craftsman Application"):::sample
        subgraph "Layered Structure"
            AD("Adapter/Presentation Layer"):::layer
            AP("Application Layer"):::layer
            DO("Domain Layer"):::layer
            IN("Infrastructure Layer"):::layer
        end
    end

    %% Global Connections
    A -->|"contains"| LA
    A -->|"provides"| C1
    A -->|"supports"| CA

    %% COLA Archetypes to Sample Applications
    LA -->|"generates"| AD

    %% Layered Structure Flow
    AD -->|"passes"| AP
    AP -->|"processes"| DO
    DO -->|"flowsTo"| IN

    %% Dependency arrows from Layers to COLA Components
    AD -->|"depends"| C1
    AP -->|"depends"| C2
    AP -->|"supports"| C6
    AP -->|"supports"| C7
    DO -->|"buildsOn"| C4
    DO -->|"extends"| C5
    IN -->|"integrates"| C3
    IN -->|"integrates"| C8
    IN -->|"integrates"| C9

    %% Click Events
    click A "https://github.com/alibaba/cola/blob/master/pom.xml"
    click LA "https://github.com/alibaba/cola/tree/master//cola-archetypes/cola-archetype-light"
    click SA "https://github.com/alibaba/cola/tree/master//cola-archetypes/cola-archetype-service"
    click WA "https://github.com/alibaba/cola/tree/master//cola-archetypes/cola-archetype-web"
    click C1 "https://github.com/alibaba/cola/tree/master//cola-components/cola-component-dto"
    click C2 "https://github.com/alibaba/cola/tree/master//cola-components/cola-component-exception"
    click C3 "https://github.com/alibaba/cola/tree/master//cola-components/cola-component-statemachine"
    click C4 "https://github.com/alibaba/cola/tree/master//cola-components/cola-component-domain-starter"
    click C5 "https://github.com/alibaba/cola/tree/master//cola-components/cola-component-extension-starter"
    click C6 "https://github.com/alibaba/cola/tree/master//cola-components/cola-component-test-container"
    click C7 "https://github.com/alibaba/cola/tree/master//cola-components/cola-component-unittest"
    click C8 "https://github.com/alibaba/cola/tree/master//cola-components/cola-component-catchlog-starter"
    click C9 "https://github.com/alibaba/cola/tree/master//cola-components/cola-component-ruleengine"
    click CA "https://github.com/alibaba/cola/tree/master//cola-samples/charge"
    click CRA "https://github.com/alibaba/cola/tree/master//cola-samples/craftsman"

    %% Styles
    classDef core fill:#f9e79f,stroke:#b7950b,stroke-width:2px;
    classDef archetype fill:#aed6f1,stroke:#2980b9,stroke-width:2px;
    classDef component fill:#a9dfbf,stroke:#27ae60,stroke-width:2px;
    classDef sample fill:#f5cba7,stroke:#d35400,stroke-width:2px;
    classDef layer fill:#d7bde2,stroke:#8e44ad,stroke-width:2px;
```
