# jitterted/ensembler architecture

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

- Interactive diagram: https://gitdiagram.com/jitterted/ensembler
- Repository: https://github.com/jitterted/ensembler

## Overview

##### Main Components

a) External Interfaces:
- GitHub OAuth2 Authentication
- SendGrid Email Service
- Zoom API Integration
- Pushover Notification Service
- WebSocket Communication

b) Core Application Layers (following Hexagonal Architecture):
- Web Adapters (Controllers)
- Application Core (Domain & Services)
- Infrastructure Adapters (Repositories & External Services)

##### Architectural Pattern Representation

- Center: Domain Core (com.jitterted.mobreg.domain)
- Domain entities: Ensemble, Member, Timer
- Domain services and business logic

- Inner Ring: Application Layer (com.jitterted.mobreg.application)
- Port interfaces
- Application services
- Use cases

- Outer Ring: Adapters (com.jitterted.mobreg.adapter)
- Incoming adapters (Web controllers)
- Outgoing adapters (Repositories, External services)

##### Component Relationships

**[External Users] → [GitHub OAuth] → [Web Controllers]**
- ↓
**[Web UI] ←→ [Controllers] → [Application Services] → [Domain Layer]**
- ↓
- [Infrastructure Adapters]
- ↓
- [Database, Email, Zoom, Notifications]

##### Key Elements to Highlight

a) Authentication Flow:
- GitHub OAuth2 integration
- Member registration process
- Authorization checks

b) Core Features:
- Ensemble management
- Timer functionality
- Member registration
- Notification system

c) Data Flow:
- Repository patterns
- External service integration
- WebSocket communication

##### Technical Details

- Database: PostgreSQL (shown by migration files)
- Web Framework: Spring Boot
- Frontend: Thymeleaf templates with Tailwind CSS
- Real-time: WebSocket implementation
- Testing: Comprehensive test coverage with TestContainers

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Services
    subgraph External["External Services"]
        GitHub["GitHub OAuth"]
        SendGrid["SendGrid Email"]
        Zoom["Zoom API"]
        Pushover["Pushover Notifications"]
    end

    %% Web Layer
    subgraph WebLayer["Web Layer"]
        WebUI["Web UI"]
        WebSocket["WebSocket"]:::websocket
        Controllers["Web Controllers"]:::controllers
        Security["Security Config"]:::security
    end

    %% Application Layer
    subgraph AppLayer["Application Layer"]
        AppServices["Application Services"]:::appservices
        Ports["Application Ports"]:::ports
    end

    %% Domain Layer
    subgraph DomainLayer["Domain Core"]
        Ensemble["Ensemble Entity"]:::domain
        Member["Member Entity"]:::domain
        Timer["Ensemble Timer"]:::domain
    end

    %% Infrastructure Layer
    subgraph InfraLayer["Infrastructure Layer"]
        DbRepo["Database Repositories"]:::infra
        EmailAdapter["Email Adapter"]:::infra
        ZoomAdapter["Zoom Adapter"]:::infra
        NotifAdapter["Notification Adapter"]:::infra
        WSBroadcaster["WebSocket Broadcaster"]:::infra
    end

    %% Relationships
    GitHub --> Security
    Security --> Controllers
    WebUI <--> Controllers
    WebSocket <--> WSBroadcaster
    Controllers --> AppServices
    AppServices --> Ports
    Ports --> DomainLayer
    AppServices --> DomainLayer
    
    EmailAdapter --> SendGrid
    ZoomAdapter --> Zoom
    NotifAdapter --> Pushover
    
    DbRepo --> DomainLayer
    WSBroadcaster --> Timer

    %% Click Events
    click Controllers "https://github.com/jitterted/ensembler/tree/master/src/main/java/com/jitterted/mobreg/adapter/in/web/"
    click Security "https://github.com/jitterted/ensembler/blob/master/src/main/java/com/jitterted/mobreg/WebSecurityConfig.java"
    click AppServices "https://github.com/jitterted/ensembler/tree/master/src/main/java/com/jitterted/mobreg/application/"
    click Ports "https://github.com/jitterted/ensembler/tree/master/src/main/java/com/jitterted/mobreg/application/port/"
    click DomainLayer "https://github.com/jitterted/ensembler/tree/master/src/main/java/com/jitterted/mobreg/domain/"
    click Timer "https://github.com/jitterted/ensembler/blob/master/src/main/java/com/jitterted/mobreg/domain/EnsembleTimer.java"
    click DbRepo "https://github.com/jitterted/ensembler/tree/master/src/main/java/com/jitterted/mobreg/adapter/out/jdbc/"
    click EmailAdapter "https://github.com/jitterted/ensembler/blob/master/src/main/java/com/jitterted/mobreg/adapter/out/email/SendGridEmailer.java"
    click ZoomAdapter "https://github.com/jitterted/ensembler/blob/master/src/main/java/com/jitterted/mobreg/adapter/out/zoom/ZoomScheduler.java"
    click NotifAdapter "https://github.com/jitterted/ensembler/blob/master/src/main/java/com/jitterted/mobreg/adapter/out/notification/pushover/PushoverNotifier.java"
    click WSBroadcaster "https://github.com/jitterted/ensembler/blob/master/src/main/java/com/jitterted/mobreg/adapter/out/websocket/WebSocketBroadcaster.java"

    %% Styles
    classDef external fill:#68a5ff
    classDef controllers fill:#98fb98
    classDef security fill:#98fb98
    classDef websocket fill:#98fb98
    classDef appservices fill:#fff59d
    classDef ports fill:#fff59d
    classDef domain fill:#ff8a80
    classDef infra fill:#e1bee7

    %% Legend
    subgraph Legend
        ExtLegend["External Services"]:::external
        WebLegend["Web Layer"]:::controllers
        AppLegend["Application Layer"]:::appservices
        DomLegend["Domain Layer"]:::domain
        InfLegend["Infrastructure Layer"]:::infra
    end
```
