# tsimbalar/codemagic-build-monitor architecture

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

- Interactive diagram: https://gitdiagram.com/tsimbalar/codemagic-build-monitor
- Repository: https://github.com/tsimbalar/codemagic-build-monitor

## Overview

##### Main Components

a. External Systems:
- Codemagic CI/CD Platform (external service)
- CatLight Client (consumer)

b. Core Application Components:
- API Layer
- Controllers (BuildInfo, Diagnostics, Example, Index)
- Authentication (Bearer Token)
- Middleware (Error Handling, Logging, Schema Validation)

- Domain Layer
- App Repository Interface
- Workflow Run Repository Interface

- Infrastructure Layer
- Codemagic Integration
- Codemagic Client
- App Repository Implementation
- Workflow Run Repository Implementation
- Caching Layer
- Cached App Repository

- Protocol Layer
- CatLight Protocol Implementation
- Basic Protocol
- Dynamic Protocol
- Shared Components

##### Relationships and Data Flow

- CatLight Client → API Layer (HTTP/REST)
- API Layer → Domain Layer (Internal calls)
- Domain Layer → Infrastructure Layer (Repository pattern)
- Infrastructure Layer → Codemagic API (External HTTP calls)
- Caching Layer ↔ Infrastructure Layer (Cache interaction)

##### Important Architectural Patterns to Highlight

- Clean Architecture pattern (controllers → domain → infrastructure)
- Repository Pattern (IAppRepository, IWorkflowRunRepository)
- Adapter Pattern (converting Codemagic data to CatLight protocol)
- Caching Strategy (CachedAppRepository)
- Dependency Injection (visible in the IoC container setup)

##### Technical Details

- Express.js as the web framework
- TSOA for API documentation and routing
- Bearer token authentication
- Docker containerization
- Port 9902 for the service

##### Implementation Notes

- The flow of authentication (Bearer token)
- Caching mechanism
- Error handling flow
- Request/Response flow

##### External Services Layer (Codemagic CI/CD)

Keep the abstraction level focused on the main architectural components while showing the key interactions that make the system work as a build status adapter between Codemagic and CatLight.

Remember to include the Docker container boundary around the application components to show the deployment context, as this is distributed as a containerized application.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph External["External Systems"]
        CL[CatLight Client]:::external
        CM[Codemagic CI/CD Platform]:::external
    end

    subgraph Container["Docker Container"]
        subgraph API["API Layer"]
            direction TB
            BC["BuildInfo Controller"]:::controller
            DC["Diagnostics Controller"]:::controller
            EC["Example Controller"]:::controller
            IC["Index Controller"]:::controller
            
            subgraph Auth["Authentication"]
                BA["Bearer Auth Provider"]:::auth
                AI["Auth Interface"]:::auth
            end
            
            subgraph MW["Middleware"]
                EH["Error Handling"]:::middleware
                RL["Request Logging"]:::middleware
                SV["Schema Validation"]:::middleware
            end
        end

        subgraph Domain["Domain Layer"]
            AR["App Repository Interface"]:::domain
            WR["Workflow Run Interface"]:::domain
        end

        subgraph Infra["Infrastructure Layer"]
            subgraph CodemagicInt["Codemagic Integration"]
                CC["Codemagic Client"]:::infra
                ARI["App Repository Implementation"]:::infra
                WRI["Workflow Run Implementation"]:::infra
            end

            subgraph Cache["Caching Layer"]
                CAR[("Cached App Repository")]:::cache
            end
        end

        subgraph Protocol["CatLight Protocol Layer"]
            BP["Basic Protocol"]:::protocol
            DP["Dynamic Protocol"]:::protocol
            SP["Shared Protocol"]:::protocol
        end
    end

    %% Connections
    CL --> BC & DC & EC & IC
    BC & DC & EC & IC --> BA
    BC & DC & EC & IC --> AR & WR
    AR & WR --> ARI & WRI
    ARI & WRI --> CC
    CC --> CM
    CAR <--> ARI
    BC & DC & EC & IC --> BP & DP
    BP & DP --> SP

    %% Click Events
    click BC "https://github.com/tsimbalar/codemagic-build-monitor/blob/main/src/api/controllers/BuildInfoController.ts"
    click DC "https://github.com/tsimbalar/codemagic-build-monitor/blob/main/src/api/controllers/DiagnosticsController.ts"
    click EC "https://github.com/tsimbalar/codemagic-build-monitor/blob/main/src/api/controllers/ExampleController.ts"
    click IC "https://github.com/tsimbalar/codemagic-build-monitor/blob/main/src/api/controllers/IndexController.ts"
    click BA "https://github.com/tsimbalar/codemagic-build-monitor/blob/main/src/api/auth/BearerAuthenticationProvider.ts"
    click AI "https://github.com/tsimbalar/codemagic-build-monitor/blob/main/src/api/auth/IAuthentication.ts"
    click EH "https://github.com/tsimbalar/codemagic-build-monitor/blob/main/src/api/middleware/error-handling.ts"
    click RL "https://github.com/tsimbalar/codemagic-build-monitor/blob/main/src/api/middleware/request-logging.ts"
    click SV "https://github.com/tsimbalar/codemagic-build-monitor/blob/main/src/api/middleware/schema-validation.ts"
    click AR "https://github.com/tsimbalar/codemagic-build-monitor/blob/main/src/domain/IAppRepository.ts"
    click WR "https://github.com/tsimbalar/codemagic-build-monitor/blob/main/src/domain/IWorkflowRunRepository.ts"
    click CC "https://github.com/tsimbalar/codemagic-build-monitor/blob/main/src/infra/codemagic/CodemagicClient.ts"
    click ARI "https://github.com/tsimbalar/codemagic-build-monitor/blob/main/src/infra/codemagic/AppRepository.ts"
    click WRI "https://github.com/tsimbalar/codemagic-build-monitor/blob/main/src/infra/codemagic/WorkflowRunRepository.ts"
    click CAR "https://github.com/tsimbalar/codemagic-build-monitor/blob/main/src/infra/caching/CachedAppRepository.ts"
    click BP "https://github.com/tsimbalar/codemagic-build-monitor/blob/main/src/catlight-protocol/basic.ts"
    click DP "https://github.com/tsimbalar/codemagic-build-monitor/blob/main/src/catlight-protocol/dynamic.ts"
    click SP "https://github.com/tsimbalar/codemagic-build-monitor/blob/main/src/catlight-protocol/shared.ts"

    %% Styling
    classDef external fill:#f9f,stroke:#333,stroke-width:2px
    classDef controller fill:#afd,stroke:#333
    classDef auth fill:#fda,stroke:#333
    classDef middleware fill:#daf,stroke:#333
    classDef domain fill:#dfd,stroke:#333
    classDef infra fill:#fdd,stroke:#333
    classDef cache fill:#ddd,stroke:#333
    classDef protocol fill:#ddf,stroke:#333

    %% Legend
    subgraph Legend
        E1[External Systems]:::external
        C1[Controllers]:::controller
        A1[Authentication]:::auth
        M1[Middleware]:::middleware
        D1[Domain]:::domain
        I1[Infrastructure]:::infra
        CA1[Cache]:::cache
        P1[Protocol]:::protocol
    end
```
