# trustbank-inc/nicoca architecture

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

- Interactive diagram: https://gitdiagram.com/trustbank-inc/nicoca
- Repository: https://github.com/trustbank-inc/nicoca

## Overview

##### Main Components
- Domain Layer:
- Contains the core business logic of the library.
- Includes entities (Entity.php), factories (EntityFactory.php), events, and value objects (e.g., BooleanValue, DateTimeValue, DecimalValue, etc.).
- Includes persistence-related classes (ArrayCollection, Collection, IdGenerator, MappedCollection, etc.) which provide data management strategies.
- Infrastructure Layer:
- Implements the domain persistence. For example, there are implementations for entity iteration, entity repository (EntityRepositoryImpl.php), and event channel (EventChannelImpl.php).
- Provides integration with persistence mechanisms, possibly serving as adapters for a database or external storage.
- Use Case Layer:
- Contains classes for handling application-specific actions, such as CurrentPage, InputValidator, and search-related components.
- This layer defines how external inputs interact with the domain logic (for example, validating inputs and formatting data).
- Component Service Provider:
- The ComponentServiceProvider may be used to wire these layers together or register components (perhaps within a Laravel or similar ecosystem).

##### Detail the Relationships and Interactions
- How the Use Case layer interacts with the Domain layer – for instance, using the EntityFactory to create domain objects or triggering domain events.
- Feedback loops, such as events from the Domain layer being handled by the Infrastructure (or even back to the Use Case layer if needed).

##### Architectural Patterns and Design Principles
- Domain-Driven Design (DDD): Emphasize the separation of concerns (Domain, Infrastructure, and Use Cases) which encapsulates business rules away from technical implementation.
- Dependency Inversion: The Domain layer uses interfaces or abstract concepts which are then implemented within the Infrastructure layer.
- Repository and Factory Patterns: Identify factories for creating entities as well as repository implementations for data retrieval and persistence.
- Modularity: The component-based design (as seen in the directory “Components”) makes the system extensible.

##### Technologies and Frameworks
- PHP and Composer: Since installation is via Composer (composer require seasalt/nicoca), mark PHP as the core language.
- PHPUnit: For testing, as indicated by phpunit.xml and tests directories.
- Potential Integration Frameworks: The ComponentServiceProvider might suggest integration with a framework (such as Laravel) for service registration and dependency management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    A["User Request"]:::external

    %% Use Case Layer
    subgraph "Use Case Layer"
        UC1["InputValidator"]:::useCase
        UC2["CurrentPage"]:::useCase
        UC3["LimitPerPage"]:::useCase
        UC4["SearchPhrase"]:::useCase
        UC5["InvalidInputException"]:::useCase
    end

    %% Domain Layer
    subgraph "Domain Layer"
        D1["EntityFactory"]:::domain
        D2["Entity"]:::domain
        D3["Event"]:::domain
        D4["EventChannel"]:::domain
        D5["ValueObjects"]:::domain
        D6["Persistence Utilities"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        I1["EntityIterator"]:::infra
        I2["EntityRepositoryImpl"]:::infra
        I3["EventChannelImpl"]:::infra
        I4["HasSearchPhrase"]:::infra
        I5["IdGeneratorImpl"]:::infra
        I6["PaginatorCreatable"]:::infra
    end

    %% Service Provider
    S["ComponentServiceProvider"]:::provider

    %% Connections
    A -->|"triggers"| UC1
    UC1 -->|"createsObject"| D1
    UC2 -->|"usesFactory"| D1
    UC3 -->|"usesFactory"| D1
    UC4 -->|"usesFactory"| D1

    D1 -->|"produces"| D2
    D2 -->|"persistedBy"| I2
    D3 -->|"emitsTo"| I3
    D4 -->|"channelsTo"| I3
    D6 -->|"assists"| I2

    S -->|"registers"| UC1
    S -->|"wires"| D1
    S -->|"connects"| I2
    S -->|"connects"| I3

    %% Styles
    classDef external fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef useCase fill:#fadbd8,stroke:#c0392b,stroke-width:2px;
    classDef domain fill:#d6eaf8,stroke:#2471a3,stroke-width:2px;
    classDef infra fill:#d5f5e3,stroke:#229954,stroke-width:2px;
    classDef provider fill:#ebdef0,stroke:#af7ac5,stroke-width:2px;

    %% Click Events - Domain Layer
    click D2 "https://github.com/trustbank-inc/nicoca/blob/master/src/Components/Domain/Entity.php"
    click D1 "https://github.com/trustbank-inc/nicoca/blob/master/src/Components/Domain/EntityFactory.php"
    click D3 "https://github.com/trustbank-inc/nicoca/blob/master/src/Components/Domain/Event.php"
    click D4 "https://github.com/trustbank-inc/nicoca/blob/master/src/Components/Domain/EventChannel.php"
    click D5 "https://github.com/trustbank-inc/nicoca/tree/master/src/Components/Domain/ValueObject/"
    click D6 "https://github.com/trustbank-inc/nicoca/tree/master/src/Components/Domain/Persistence/"

    %% Click Events - Infrastructure Layer
    click I1 "https://github.com/trustbank-inc/nicoca/blob/master/src/Components/Infrastructure/Persistence/EntityIterator.php"
    click I2 "https://github.com/trustbank-inc/nicoca/blob/master/src/Components/Infrastructure/Persistence/EntityRepositoryImpl.php"
    click I3 "https://github.com/trustbank-inc/nicoca/blob/master/src/Components/Infrastructure/Persistence/EventChannelImpl.php"
    click I4 "https://github.com/trustbank-inc/nicoca/blob/master/src/Components/Infrastructure/Persistence/HasSearchPhrase.php"
    click I5 "https://github.com/trustbank-inc/nicoca/blob/master/src/Components/Infrastructure/Persistence/IdGeneratorImpl.php"
    click I6 "https://github.com/trustbank-inc/nicoca/blob/master/src/Components/Infrastructure/Persistence/PaginatorCreatable.php"

    %% Click Events - Use Case Layer
    click UC2 "https://github.com/trustbank-inc/nicoca/blob/master/src/Components/UseCase/CurrentPage.php"
    click UC1 "https://github.com/trustbank-inc/nicoca/blob/master/src/Components/UseCase/InputValidator.php"
    click UC5 "https://github.com/trustbank-inc/nicoca/blob/master/src/Components/UseCase/InvalidInputException.php"
    click UC3 "https://github.com/trustbank-inc/nicoca/blob/master/src/Components/UseCase/LimitPerPage.php"
    click UC4 "https://github.com/trustbank-inc/nicoca/blob/master/src/Components/UseCase/SearchPhrase.php"

    %% Click Event - Component Service Provider
    click S "https://github.com/trustbank-inc/nicoca/blob/master/src/ComponentServiceProvider.php"
```
