# balmarcha/common-lib architecture

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

- Interactive diagram: https://gitdiagram.com/balmarcha/common-lib
- Repository: https://github.com/balmarcha/common-lib

## Overview

##### Main Components
- Domain Layer: This is the core of the application and holds business entities, models (both DTOs and POJOs), and domain-specific interfaces (such as Obsoletable). Look for packages like “domain/src/main/java/es/bxg/commonlib/model”, “domain/src/main/java/es/bxg/commonlib/model/dtos”, “domain/src/main/java/es/bxg/commonlib/model/pojo”, as well as domain ports and services.
- Infrastructure Layer: Acts as the adapter side that connects external systems with your core business logic. It includes adapters for persistence (repositories, such as IGenericRepository), REST controllers (IGenericCommandController, IGenericQueryController), exception handlers (NoContentException), and mapping between domain and database objects. Look into “infrastructure/src/main/java/es/bxg/commonlib/adapter”, “infrastructure/src/main/java/es/bxg/commonlib/rest”, and related subfolders.

##### Establish Relationships and Data Flow
- The Infrastructure Layer should be shown as an external adapter layer connecting to both the Application and Domain Layers. Indicate that it “implements” the domain port interfaces to interact with external resources (e.g., databases, APIs, messaging systems), and also exposes REST endpoints to external clients.
– External requests flow into the Infrastructure (through REST controllers) then pass to the Application, and finally trigger the Domain logic.
– Outbound dependencies, such as persistence operations, flow from the Domain/Application through the Infrastructure adapters.

##### Architectural Patterns and Design Principles
- That the design follows the Hexagonal Architecture: a core domain unit kept isolated from technical concerns via defined “ports” that are plugged with “adapters” (infrastructure code).
- Dependency inversion principle – the outer layers depend on abstract interfaces defined in the core rather than concrete implementations.
- Generic utility components like mappers (CycleAvoidingMappingContext) and generic command/query handlers/services which are meant to be extended or implemented in specific use cases.

##### Incorporate Relevant Technologies and Frameworks
- Since this is a Java-based project (per the README badge and .pom.xml files), mention that Maven is used as a build tool.
- Even if the actual frameworks (like a specific Persistence API or REST framework) are not explicitly listed, it’s helpful to include annotations or notes that these components are likely integrated with technologies like Spring, JPA, or similar Java libraries.

##### Final Advice
- Avoid clutter by grouping related components and only expanding into subcomponents if they convey significant detail.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Infrastructure Layer"
        direction TB
        IRest["REST Controllers"]:::infra
        IAdapterPort["Adapter Ports"]:::infra
        IAdapter["Adapters & Repository"]:::infra
        IEx["Exception Handling"]:::infra
        IMap["Mapping Utilities"]:::infra
    end

    subgraph "Application Layer"
        direction TB
        AHandler["Use Case Handlers"]:::app
        AMappers["Mappers"]:::app
    end

    subgraph "Domain Layer"
        direction TB
        DM["Domain Models"]:::domain
        DT["DTOs (domain)"]:::domain
        DP["POJOs (domain)"]:::domain
        DI["Obsoletable Interface"]:::domain
        DPort["Domain Ports"]:::domain
        DService["Domain Services"]:::domain
    end

    IRest -->|"request_flow"| AHandler
    AHandler -->|"invoke"| DPort
    DPort -->|"process"| DService
    DService -->|"outbound"| IAdapterPort
    IAdapterPort -->|"repository_call"| IAdapter

    AHandler -->|"mapping"| AMappers
    AMappers -->|"map_utilities"| IMap

    IEx ---|"error_advice"| IRest

    classDef domain fill:#FFDDC1,stroke:#333,stroke-width:2px;
    classDef app fill:#C1FFD7,stroke:#333,stroke-width:2px;
    classDef infra fill:#C1D4FF,stroke:#333,stroke-width:2px;

    click DM "https://github.com/balmarcha/common-lib/tree/main/domain/src/main/java/es/bxg/commonlib/model"
    click DT "https://github.com/balmarcha/common-lib/tree/main/domain/src/main/java/es/bxg/commonlib/model/dtos"
    click DP "https://github.com/balmarcha/common-lib/tree/main/domain/src/main/java/es/bxg/commonlib/model/pojo"
    click DI "https://github.com/balmarcha/common-lib/blob/main/domain/src/main/java/es/bxg/commonlib/model/interfaces/Obsoletable.java"
    click DPort "https://github.com/balmarcha/common-lib/tree/main/domain/src/main/java/es/bxg/commonlib/port"
    click DService "https://github.com/balmarcha/common-lib/tree/main/domain/src/main/java/es/bxg/commonlib/service"

    click AHandler "https://github.com/balmarcha/common-lib/tree/main/application/src/main/java/es/bxg/commonlib/service"
    click AMappers "https://github.com/balmarcha/common-lib/tree/main/application/src/main/java/es/bxg/commonlib/mapper"

    click IRest "https://github.com/balmarcha/common-lib/tree/main/infrastructure/src/main/java/es/bxg/commonlib/rest/controllers"
    click IAdapter "https://github.com/balmarcha/common-lib/tree/main/infrastructure/src/main/java/es/bxg/commonlib/adapter"
    click IAdapterPort "https://github.com/balmarcha/common-lib/tree/main/infrastructure/src/main/java/es/bxg/commonlib/adapter/port"
    click IEx "https://github.com/balmarcha/common-lib/blob/main/infrastructure/src/main/java/es/bxg/commonlib/adapter/exception/NoContentException.java"
    click IMap "https://github.com/balmarcha/common-lib/tree/main/infrastructure/src/main/java/es/bxg/commonlib/adapter/mapper"
```
