# sipman/butterfly-framework architecture

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

- Interactive diagram: https://gitdiagram.com/sipman/butterfly-framework
- Repository: https://github.com/sipman/butterfly-framework

## Overview

##### Main Components

A. Framework Core (Butterfly Library)
- Request/Response Handlers
- Router System
- Application Container
- Annotation System
- Static File Handler

B. Clean Architecture Layers (from Example)
- Presentation Layer (Endpoints & Presenters)
- Application Layer (Use Cases)
- Domain Layer
- Infrastructure Layer (Repositories)

##### Connection and Flow Representation

- Blue: Framework Core Components
- Green: Interface Adapters
- Yellow: Use Cases
- Red: Domain Layer
- Purple: Infrastructure Layer

##### Specific Implementation Details

Concrete examples from the project:
- Task-related endpoints (CreateNewTask, GetTaskById, ListActiveTasks)
- Task domain entity
- Task repository
- Associated use cases and their components

Create distinct sections for:
a) Framework Infrastructure
- How the Application class orchestrates everything
- Demonstrate routing mechanism

b) Clean Architecture Implementation
- Flow from endpoints through use cases to repositories
- Separation of concerns

##### Additional Elements

- Notes about the annotation system (@Body, @Param, @TransferObject)
- How static file serving is integrated

##### Key Relationships to Highlight

- How endpoints connect to use cases
- How presenters format the response
- How repositories implement persistence interfaces
- How the domain model (Task) is used across layers

##### The request/response flow through the system

Remember to maintain a balance between showing the framework's infrastructure and the Clean Architecture implementation, as both are crucial aspects of the system.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Framework Core"
        Router["Router System"]:::core
        ReqHandler["Request Handler"]:::core
        RespHandler["Response Handler"]:::core
        AppContainer["Application Container"]:::core
        Annotations["Annotation System"]:::core
        StaticFiles["Static File Handler"]:::core
        
        AppContainer --> Router
        AppContainer --> ReqHandler
        AppContainer --> RespHandler
        AppContainer --> Annotations
        AppContainer --> StaticFiles
    end

    subgraph "Presentation Layer"
        Endpoints["Endpoints"]:::presentation
        Presenters["Presenters"]:::presentation
        ReqObjects["Request Objects"]:::presentation
        RespObjects["Response Objects"]:::presentation
        MainApp["Main Application"]:::presentation

        CreateTaskEndpoint["Create Task Endpoint"]:::presentation
        GetTaskEndpoint["Get Task Endpoint"]:::presentation
        ListTasksEndpoint["List Tasks Endpoint"]:::presentation
        TaskPresenter["Task Presenter"]:::presentation

        Endpoints --> CreateTaskEndpoint
        Endpoints --> GetTaskEndpoint
        Endpoints --> ListTasksEndpoint
        Presenters --> TaskPresenter
    end

    subgraph "Use Cases Layer"
        CreateTaskUC["Create Task Use Case"]:::usecase
        GetTaskUC["Get Task Use Case"]:::usecase
        ListTasksUC["List Tasks Use Case"]:::usecase
    end

    subgraph "Domain Layer"
        TaskEntity["Task Entity"]:::domain
    end

    subgraph "Infrastructure Layer"
        TaskRepo["Task Repository"]:::infrastructure
    end

    %% Connections between layers
    CreateTaskEndpoint --> CreateTaskUC
    GetTaskEndpoint --> GetTaskUC
    ListTasksEndpoint --> ListTasksUC
    
    CreateTaskUC --> TaskEntity
    GetTaskUC --> TaskEntity
    ListTasksUC --> TaskEntity
    
    TaskRepo --> TaskEntity
    
    CreateTaskUC --> TaskRepo
    GetTaskUC --> TaskRepo
    ListTasksUC --> TaskRepo

    %% Framework connections
    Router --> Endpoints
    ReqHandler --> Endpoints
    RespHandler --> Presenters

    %% Click events for component mapping
    click Router "https://github.com/sipman/butterfly-framework/blob/master/lib/src/router.dart"
    click ReqHandler "https://github.com/sipman/butterfly-framework/blob/master/lib/src/request.dart"
    click RespHandler "https://github.com/sipman/butterfly-framework/blob/master/lib/src/response.dart"
    click AppContainer "https://github.com/sipman/butterfly-framework/blob/master/lib/src/application.dart"
    click Annotations "https://github.com/sipman/butterfly-framework/tree/master/lib/src/annotations/"
    click StaticFiles "https://github.com/sipman/butterfly-framework/blob/master/lib/src/staticFileEndpoint.dart"
    click Endpoints "https://github.com/sipman/butterfly-framework/tree/master/example/application/endpoints/"
    click Presenters "https://github.com/sipman/butterfly-framework/tree/master/example/application/presenters/"
    click ReqObjects "https://github.com/sipman/butterfly-framework/tree/master/example/application/request_objects/"
    click RespObjects "https://github.com/sipman/butterfly-framework/tree/master/example/application/response_objects/"
    click MainApp "https://github.com/sipman/butterfly-framework/blob/master/example/application/todo_application.dart"
    click CreateTaskUC "https://github.com/sipman/butterfly-framework/tree/master/example/use_cases/create_new_task/"
    click GetTaskUC "https://github.com/sipman/butterfly-framework/tree/master/example/use_cases/get_task_use_case/"
    click ListTasksUC "https://github.com/sipman/butterfly-framework/tree/master/example/use_cases/list_active_tasks/"
    click TaskEntity "https://github.com/sipman/butterfly-framework/blob/master/example/domaine/task.dart"
    click TaskRepo "https://github.com/sipman/butterfly-framework/blob/master/example/repositories/task_repository.dart"
    click CreateTaskEndpoint "https://github.com/sipman/butterfly-framework/blob/master/example/application/endpoints/create_new_task_endpoint.dart"
    click GetTaskEndpoint "https://github.com/sipman/butterfly-framework/blob/master/example/application/endpoints/get_task_by_id_endpoint.dart"
    click ListTasksEndpoint "https://github.com/sipman/butterfly-framework/blob/master/example/application/endpoints/list_active_tasks_endpoint.dart"
    click TaskPresenter "https://github.com/sipman/butterfly-framework/blob/master/example/application/presenters/get_task_presenter.dart"

    %% Styling
    classDef core fill:#2196F3,stroke:#1565C0,color:white
    classDef presentation fill:#4CAF50,stroke:#2E7D32,color:white
    classDef usecase fill:#FFC107,stroke:#FFA000,color:black
    classDef domain fill:#F44336,stroke:#D32F2F,color:white
    classDef infrastructure fill:#9C27B0,stroke:#7B1FA2,color:white

    %% Legend
    subgraph Legend
        L1["Framework Core"]:::core
        L2["Presentation Layer"]:::presentation
        L3["Use Cases Layer"]:::usecase
        L4["Domain Layer"]:::domain
        L5["Infrastructure Layer"]:::infrastructure
    end
```
