# lau-r-a/appointment-checker-service architecture

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

- Interactive diagram: https://gitdiagram.com/lau-r-a/appointment-checker-service
- Repository: https://github.com/lau-r-a/appointment-checker-service

## Overview

- API Layer: Highlight the REST Controllers (see packages “service/api”, “service/discord/auth”, “service/discord/bot”). This block handles incoming HTTP requests, performs API routing, and exposes the OpenAPI documentation (Swagger UI at /swagger-ui/index.html) for client interaction.
- Service/Business Logic Layer: Capture the core business logic like the AvailabilityCheckJob, NotificationFacade, UserFacade, and the Provider integrations (e.g., DrLibAgenda and its related controllers). This is where the functionality for checking appointments and sending notifications comes together.
- Data Access Layer (Repositories): Include the repositories (NotificationRepository, NotificationTargetRepository, UserRepository) that abstract database interactions.
- Entities/Data Models: Represent the domain models (found under entities/dto and entities/model) that are used to transfer data within the system.
- Security & Authentication: Distinctly illustrate the OAuth2 configuration section, token validation filters, and any related components for handling security. Since the README details an OAuth2 “security_auth” flow (for example, using Discord for bearer token authentication), this block is key.
- Integration with External Systems:
- Discord Integration: Represent the DiscordBotConfiguration, Discord controllers (both bot and auth), showing the flow from incoming requests to Discord API interactions.
- Provider Integrations: A subcomponent where the service deals with external providers (e.g., DrLib, as indicated by the “drlib” package). Include key elements like DrLibAgenda, DrLibInfoResponse, etc.
- Configuration and Infrastructure:
- Configuration files (application.properties, Dockerfile, docker-compose.yml, example.env) that configure the environment.
- Build and deployment aspects, including Docker and Maven, to show how deployment and continuous integration are handled.

##### Relationships & Interactions
- Interaction between the service and the database via the repository interfaces.
- Communication with external services:
- That the business logic layer coordinates both scheduled tasks (like the AvailabilityCheckJob) and manual API-triggered events to send notifications, forming a feedback loop to the user.

##### Architectural Patterns & Principles
- Separation of Concerns: Clearly separate the API controllers, business logic, and data access layers.
- Microservice/Modular Approach: Even though this is a single service, the existence of distinct packages (for API, security, providers, etc.) supports a modular design.
- Integration Ready: Note how external integrations (e.g., Discord and DrLib) are abstracted, making it easier to extend or modify these interactions in the future.
- Security Best Practices: Use OAuth2 and token validation filters to enforce secure access.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client and External Systems
    Client("Client"):::external
    DiscordAPI("Discord API"):::external
    DrLibService("DrLib Service"):::external

    %% API Layer Subgraph
    subgraph "API Layer"
        apiRest("RestController"):::api
        apiOpen("OpenAPI3Configuration"):::api
    end

    %% Discord Integration Subgraph
    subgraph "Discord Integration"
        discordAuth("DiscordController"):::api
        discordBot("DiscordBotController"):::api
        discordConfig("DiscordBotConfiguration"):::api
    end

    %% Business/Service Logic Layer Subgraph
    subgraph "Business/Service Logic Layer"
        job("AvailabilityCheckJob"):::business
        notifFacade("NotificationFacade"):::business
        userFacade("UserFacade"):::business
    end

    %% Provider Integrations (DrLib) Subgraph
    subgraph "Provider Integrations (DrLib)"
        drlibAgenda("DrLibAgenda"):::provider
        drlibCtrl("DrLibController"):::provider
        drlibInfo("DrLibInfoResponse"):::provider
        drlibDesc("DrLibInfoResponseDeserializer"):::provider
        drlibParams("DrLibParams"):::provider
        drlibResp("DrLibResponse"):::provider
    end

    %% Data Access Layer Subgraph
    subgraph "Data Access Layer"
        notifRepo("NotificationRepository"):::repo
        notifTargetRepo("NotificationTargetRepository"):::repo
        userRepo("UserRepository"):::repo
    end

    %% Entities/Data Models Subgraph
    subgraph "Entities/Data Models"
        dtos("DTOs"):::entity
        models("Models"):::entity
    end

    %% Security & Authentication Subgraph
    subgraph "Security & Authentication"
        oauthConfig("OAuthClientConfiguration"):::security
        tokenFilter("TokenValidationFilter"):::security
        oauthUtils("OAuth2UserAgentUtils"):::security
    end

    %% Configuration and Infrastructure Subgraph
    subgraph "Configuration & Infrastructure"
        appProps("application.properties"):::infra
        dockerfile("Dockerfile"):::infra
        dockerCompose("docker-compose.yml"):::infra
        exampleEnv("example.env"):::infra
    end

    %% Connections from Client to API Layer
    Client -->|"REST_call"| apiRest
    Client -->|"Swagger_UI_access"| apiOpen

    %% API Layer interactions
    apiRest -->|"process_request"| notifFacade
    apiRest -->|"process_request"| userFacade

    %% Discord integration connections
    Client -->|"Discord_OAuth"| discordAuth
    discordAuth -->|"calls"| DiscordAPI
    discordBot -->|"bot_interaction"| DiscordAPI
    discordConfig -->|"configures"| discordBot

    %% Business Layer interactions
    job -->|"triggers"| notifFacade
    notifFacade -->|"notify_user"| userFacade

    %% Provider integration interactions
    notifFacade -->|"fetch_data"| drlibAgenda
    drlibAgenda -->|"calls"| drlibCtrl
    drlibCtrl -->|"interacts_with"| DrLibService
    drlibCtrl --> drlibInfo
    drlibCtrl --> drlibDesc
    drlibCtrl --> drlibParams
    drlibCtrl --> drlibResp

    %% Data Access interactions
    notifFacade -->|"persists"| notifRepo
    userFacade -->|"persists"| userRepo
    notifFacade -->|"uses"| notifTargetRepo

    %% Entities used by layers (logical grouping)
    dtos --- models

    %% Security integration (applied to API and Business)
    apiRest --- oauthConfig
    discordAuth --- oauthConfig
    oauthConfig --- tokenFilter
    tokenFilter --- oauthUtils

    %% Infrastructure connections (deployment aspects)
    appProps --- dockerfile
    dockerfile --- dockerCompose
    dockerCompose --- exampleEnv

    %% Click events for API Layer
    click apiRest "https://github.com/lau-r-a/appointment-checker-service/blob/master/src/main/java/com/appointmentchecker/service/api/RestController.java"
    click apiOpen "https://github.com/lau-r-a/appointment-checker-service/blob/master/src/main/java/com/appointmentchecker/service/api/OpenAPI3Configuration.java"

    %% Click events for Discord Integration
    click discordAuth "https://github.com/lau-r-a/appointment-checker-service/blob/master/src/main/java/com/appointmentchecker/service/discord/auth/DiscordController.java"
    click discordBot "https://github.com/lau-r-a/appointment-checker-service/blob/master/src/main/java/com/appointmentchecker/service/discord/bot/DiscordBotController.java"
    click discordConfig "https://github.com/lau-r-a/appointment-checker-service/blob/master/src/main/java/com/appointmentchecker/service/discord/DiscordBotConfiguration.java"

    %% Click events for Business/Service Logic Layer
    click job "https://github.com/lau-r-a/appointment-checker-service/blob/master/src/main/java/com/appointmentchecker/service/AvailabilityCheckJob.java"
    click notifFacade "https://github.com/lau-r-a/appointment-checker-service/blob/master/src/main/java/com/appointmentchecker/service/facade/NotificationFacade.java"
    click userFacade "https://github.com/lau-r-a/appointment-checker-service/blob/master/src/main/java/com/appointmentchecker/service/facade/UserFacade.java"

    %% Click events for Provider Integrations (DrLib)
    click drlibAgenda "https://github.com/lau-r-a/appointment-checker-service/blob/master/src/main/java/com/appointmentchecker/service/providers/drlib/DrLibAgenda.java"
    click drlibCtrl "https://github.com/lau-r-a/appointment-checker-service/blob/master/src/main/java/com/appointmentchecker/service/providers/drlib/DrLibController.java"
    click drlibInfo "https://github.com/lau-r-a/appointment-checker-service/blob/master/src/main/java/com/appointmentchecker/service/providers/drlib/DrLibInfoResponse.java"
    click drlibDesc "https://github.com/lau-r-a/appointment-checker-service/blob/master/src/main/java/com/appointmentchecker/service/providers/drlib/DrLibInfoResponseDeserializer.java"
    click drlibParams "https://github.com/lau-r-a/appointment-checker-service/blob/master/src/main/java/com/appointmentchecker/service/providers/drlib/DrLibParams.java"
    click drlibResp "https://github.com/lau-r-a/appointment-checker-service/blob/master/src/main/java/com/appointmentchecker/service/providers/drlib/DrLibResponse.java"

    %% Click events for Data Access Layer
    click notifRepo "https://github.com/lau-r-a/appointment-checker-service/blob/master/src/main/java/com/appointmentchecker/service/repositories/NotificationRepository.java"
    click notifTargetRepo "https://github.com/lau-r-a/appointment-checker-service/blob/master/src/main/java/com/appointmentchecker/service/repositories/NotificationTargetRepository.java"
    click userRepo "https://github.com/lau-r-a/appointment-checker-service/blob/master/src/main/java/com/appointmentchecker/service/repositories/UserRepository.java"

    %% Click events for Entities/Data Models
    click dtos "https://github.com/lau-r-a/appointment-checker-service/tree/master/src/main/java/com/appointmentchecker/service/entities/dto"
    click models "https://github.com/lau-r-a/appointment-checker-service/tree/master/src/main/java/com/appointmentchecker/service/entities/model"

    %% Click events for Security & Authentication
    click oauthConfig "https://github.com/lau-r-a/appointment-checker-service/blob/master/src/main/java/com/appointmentchecker/service/security/OAuthClientConfiguration.java"
    click tokenFilter "https://github.com/lau-r-a/appointment-checker-service/blob/master/src/main/java/com/appointmentchecker/service/security/TokenValidationFilter.java"
    click oauthUtils "https://github.com/lau-r-a/appointment-checker-service/blob/master/src/main/java/com/appointmentchecker/service/security/OAuth2UserAgentUtils.java"

    %% No click events for Infrastructure as they are configuration files
    click appProps "https://github.com/lau-r-a/appointment-checker-service/blob/master/application.properties"
    click dockerfile "https://github.com/lau-r-a/appointment-checker-service/tree/master/Dockerfile"
    click dockerCompose "https://github.com/lau-r-a/appointment-checker-service/blob/master/docker-compose.yml"
    click exampleEnv "https://github.com/lau-r-a/appointment-checker-service/blob/master/example.env"

    %% Styles
    classDef api fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef business fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef provider fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef repo fill:#FDEBD0,stroke:#D35400,stroke-width:2px;
    classDef entity fill:#FADBD8,stroke:#922B21,stroke-width:2px;
    classDef security fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef infra fill:#E8DAEF,stroke:#512E5F,stroke-width:2px;
    classDef external fill:#F5CBA7,stroke:#B03A2E,stroke-width:2px;
```
