# fiddelis/sher-lock architecture

> Architecture diagram of the GitHub repository fiddelis/sher-lock, 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/fiddelis/sher-lock
- Repository: https://github.com/fiddelis/sher-lock

## Overview

##### Main Components
- API Service – This service (in the api-service directory) is responsible for handling parcel data and operations. It exposes endpoints through various controllers (e.g., ClientController, DrawerController, LockerController, ProductController, RegisterController, SiteController), interacts with a persistence layer (repositories and model classes), and includes producers (MailProducer) for triggering email notifications.
- Mail Service – This service (found under mail-service) subscribes as a consumer (MailConsumer) to messages (likely received via a messaging system or direct integration) and processes email delivery logic. It also handles QR Code generation using a utility (Qrcode), and exposes its own endpoint via a MailController.
- Static Web Frontend – The site-exemplo directory contains a simple HTML/CSS/JS website that serves as an example or entry point for users.
- Database – Although not explicitly named in the service directories, the presence of repository layers in both services and the Docker migration script (docker/migration/docker-database-initial.sql) strongly indicates a relational database (or possibly multiple databases) is used to manage persistent data.
- Docker & Deployment Scripts – The docker folder (with docker-compose.yml) and migration scripts suggest containerization and orchestrated deployment of these components.

##### Relationships and Interactions
- External Entities:
– Logistics Companies will interact with the system by depositing packages into the lockers.
– Customers receive a QR Code via email once a package is deposited.
– Clients / Users (via the static website or another client app) send requests to the API Service.
– API Service handles operations (e.g., registration, locker retrieval, product management) and writes data to or reads data from the Database.
– When a parcel is registered or needs notification, the API Service uses its MailProducer to send a notification message.
– The Mail Service (via its MailConsumer) receives the notification, processes the email (including generating a QR Code) and sends it to the customer.
- Internal Service Communication:
– Each microservice should show its internal layers (Controller → Service → Repository) and how they interact with the Database.

##### Important Architectural Patterns and Technologies
- Microservices Architecture – The separation into distinct services (api-service and mail-service) indicates a design focused on loose coupling and separation of concerns.
- Layered Architecture within each Service – Both services include a clear layering (Controller, Service, Repository, Model, and Utility).
- Messaging / Event-driven Communication – The use of a MailProducer in the API service and MailConsumer in the Mail service suggests an asynchronous messaging pattern to decouple email notifications from core business logic.
- Containerization and Orchestration – The Docker configurations imply the services are containerized, and docker-compose could be used to manage the multi-container deployment (API Service, Mail Service, and the Database).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    subgraph "External Entities"
        EX_LOG["Logistics Companies"]:::external
        EX_CUST["Customers"]:::external
    end

    %% Frontend - Static Website
    subgraph "Static Website"
        STATIC_HTML["index.html"]:::frontend
        STATIC_CSS["CSS (style.css)"]:::frontend
        STATIC_JS["JavaScript (main.js)"]:::frontend
    end

    %% API Service
    subgraph "API Service"
        API_CTRL["API Controllers (Client,Drawer,Locker,Product,Register,Site)"]:::backend
        API_MODEL["Model & Repository"]:::backend
        API_PROD["Mail Producer"]:::backend
    end

    %% Message Broker for asynchronous communication
    MSG_BROKER["Message Broker"]:::backend

    %% Mail Service
    subgraph "Mail Service"
        MAIL_CTRL["Mail Controller"]:::backend
        MAIL_CONS["Mail Consumer"]:::backend
        MAIL_LOGIC["Mail Service Logic"]:::backend
        QR_UTIL["QR Code Utility"]:::backend
        MAIL_MODEL["Mail Model"]:::backend
    end

    %% Database
    subgraph "Database Layer"
        DB["Relational Database"]:::db
    end

    %% Deployment & Containerization
    subgraph "Deployment"
        DOCKER["Docker & Deployment Scripts"]:::deployment
    end

    %% Connections
    EX_LOG -->|"PackageDeposit"| API_CTRL
    STATIC_HTML -->|"HTTPRequest"| API_CTRL

    API_CTRL -->|"DataOperation"| API_MODEL
    API_MODEL -->|"DBQuery"| DB

    API_PROD -->|"TriggerEmail"| MSG_BROKER
    MSG_BROKER -->|"NotificationMsg"| MAIL_CONS

    MAIL_CONS -->|"ProcessEmail"| MAIL_LOGIC
    MAIL_LOGIC -->|"StoreLog"| DB
    MAIL_LOGIC -->|"SendEmail(QRCode)"| EX_CUST
    MAIL_LOGIC -->|"GenerateQR"| QR_UTIL
    QR_UTIL -.-> MAIL_LOGIC

    %% Optional: Expose Mail Service endpoint to external systems
    MAIL_CTRL -->|"EmailAPI"| EX_CUST

    %% Styling
    classDef frontend fill:#f9c74f,stroke:#f9844a,stroke-width:2px;
    classDef backend fill:#90be6d,stroke:#43aa8b,stroke-width:2px;
    classDef external fill:#f94144,stroke:#d90429,stroke-width:2px;
    classDef db fill:#577590,stroke:#4d908e,stroke-width:2px,fill-opacity:0.5;
    classDef deployment fill:#f3722c,stroke:#f9844a,stroke-width:2px;

    %% Click Events for API Service
    click API_CTRL "https://github.com/fiddelis/sher-lock/tree/main/api-service/src/main/java/com/sherlock/apiservice/controller"
    click API_MODEL "https://github.com/fiddelis/sher-lock/tree/main/api-service/src/main/java/com/sherlock/apiservice/repository"
    click API_PROD "https://github.com/fiddelis/sher-lock/blob/main/api-service/src/main/java/com/sherlock/apiservice/producer/MailProducer.java"

    %% Click Events for Mail Service
    click MAIL_CTRL "https://github.com/fiddelis/sher-lock/blob/main/mail-service/src/main/java/com/sherlock/mailservice/controller/MailController.java"
    click MAIL_CONS "https://github.com/fiddelis/sher-lock/blob/main/mail-service/src/main/java/com/sherlock/mailservice/consumer/MailConsumer.java"
    click MAIL_LOGIC "https://github.com/fiddelis/sher-lock/blob/main/mail-service/src/main/java/com/sherlock/mailservice/service/MailService.java"
    click QR_UTIL "https://github.com/fiddelis/sher-lock/blob/main/mail-service/src/main/java/com/sherlock/mailservice/utils/Qrcode.java"
    click MAIL_MODEL "https://github.com/fiddelis/sher-lock/tree/main/mail-service/src/main/java/com/sherlock/mailservice/model"

    %% Click Events for Static Website
    click STATIC_HTML "https://github.com/fiddelis/sher-lock/blob/main/site-exemplo/index.html"
    click STATIC_CSS "https://github.com/fiddelis/sher-lock/blob/main/site-exemplo/css/style.css"
    click STATIC_JS "https://github.com/fiddelis/sher-lock/blob/main/site-exemplo/js/main.js"

    %% Click Event for Database Migration Script
    click DB "https://github.com/fiddelis/sher-lock/blob/main/docker/migration/docker-database-initial.sql"

    %% Click Event for Docker Compose
    click DOCKER "https://github.com/fiddelis/sher-lock/blob/main/docker/docker-compose.yml"
```
