# kamblega/dis-final-gale architecture

> Architecture diagram of the GitHub repository kamblega/dis-final-gale, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kamblega/dis-final-gale
- Repository: https://github.com/kamblega/dis-final-gale

## Overview

##### Project type and purpose
- This is a full-stack, backend-centric Spring Boot application that implements the Gale–Shapley stable matching algorithm to allocate students to projects (and staff to supervise) based on preferences.
- It exposes REST API endpoints, serves a set of static HTML/CSS “frontend” pages, persists data in PostgreSQL (or H2 for tests), and uses Apache Kafka for asynchronous, non-blocking matching jobs.

##### File structure
- Top-level:
- pom.xml + mvnw wrappers → Maven-based Spring Boot project
- HELP.md, README.md → documentation
- src/main/java/gale/shapley packages:
- controller/ → REST controllers (MatchingController, StudentController, ProjectController, LeaderController)
- service/ → core business services (GaleShapleyService, CsvProcessingService, PdfGenerationService, EmailService, FileStorageService, StudentService)
- repository/ → Spring Data JPA repositories (StudentRepository, ProjectRepository, etc.)
- model/ → JPA entities (Student, Project, Preferences, etc.)
- dto/ → request/response data transfer objects
- kafka/ → producer & consumer configs and payload (asynchronous matching jobs)
- aspect/ → AOP logging (LoggingAspect)
- PreferenceService.java → encapsulates preference-related logic
- src/main/resources:
- application.properties → DB, Kafka, other configs
- schema.sql & data.sql → database schema & seed data
- static/ → single-page HTML/CSS “frontend”
- src/test → unit tests for core logic and services

##### README for additional insights
- Architecture patterns: layered architecture (Controller → Service → Repository), CQRS (read vs write flows are separated), asynchronous processing via Kafka (non-blocking job queue), AOP for centralized logging.
- Features: REST API, PDF/CSV report generation, email notifications (phase 2), Swagger UI, resilience (Resilience4j).
- Data flow: Clients upload CSV → KafkaProducerService publishes MatchingJobPayload → MatchingJobConsumer consumes, runs Gale–Shapley → results persisted, PDF/CSV generated → clients download or receive via email.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend"
        direction TB
        Frontend["Static HTML/CSS"]:::frontend
    end

    %% API Layer
    subgraph "API Controllers"
        direction TB
        MC["MatchingController"]:::api
        SC["StudentController"]:::api
        PC["ProjectController"]:::api
        LC["LeaderController"]:::api
        SW["Swagger UI"]:::api
    end

    %% Business Services
    subgraph "Business Services"
        direction TB
        GS["GaleShapleyService"]:::service
        CSV["CsvProcessingService"]:::service
        PDF["PdfGenerationService"]:::service
        EMS["EmailService"]:::service
        FSS["FileStorageService"]:::service
        STS["StudentService"]:::service
        PREF["PreferenceService"]:::service
    end

    %% Messaging Layer
    subgraph "Messaging (Kafka)"
        direction TB
        KPC["KafkaProducerService"]:::async
        TOP["MatchingJob Topic"]:::async
        MJC["MatchingJobConsumer"]:::async
    end

    %% Persistence Layer
    subgraph "Persistence"
        direction TB
        DB["PostgreSQL Database"]:::persistence
        subgraph "Repositories"
            direction TB
            PR["ProjectRepository"]:::persistence
            SR["StudentRepository"]:::persistence
            SPR["SupervisorRepository"]:::persistence
            SPRF["StudentPreferenceRepository"]:::persistence
            STF["StaffPreferenceRepository"]:::persistence
        end
        subgraph "Domain Model"
            direction TB
            DM["JPA Entities"]:::persistence
        end
    end

    %% Cross-cutting
    subgraph "Cross-cutting"
        direction TB
        LOG["LoggingAspect"]:::cross
        RES["Resilience4j"]:::cross
    end

    %% External Systems
    subgraph "External Integrations"
        direction TB
        SMTP["SMTP Server"]:::external
        FS["External File Storage"]:::external
        KCL["Kafka Cluster"]:::external
    end

    %% Connections - Synchronous CRUD
    Frontend -->|"HTTP calls"| MC
    Frontend -->|"HTTP calls"| SC
    Frontend -->|"HTTP calls"| PC
    Frontend -->|"HTTP calls"| LC

    MC -->|"invoke"| GS
    MC -->|"invoke"| CSV
    SC -->|"invoke"| STS
    PC -->|"invoke"| FSS
    LC -->|"invoke"| PREF

    SC -->|"persist"| SR
    PC -->|"persist"| PR

    %% Asynchronous matching pipeline
    MC -->|"upload CSV"| KPC
    KPC -->|"publish MatchingJobPayload"| TOP
    TOP -->|"stream"| MJC
    MJC -->|"run algorithm"| GS
    GS -->|"save results"| PR
    GS -->|"save results"| SR

    %% Report generation and email
    MJC -->|"trigger"| CSV
    CSV -->|"read results"| DB
    CSV -->|"write CSV"| FS
    CSV -->|"invoke"| PDF
    PDF -->|"write PDF"| FS
    EMS -->|"send email via SMTP"| SMTP

    %% Cross-cutting
    MC --> LOG
    SC --> LOG
    PC --> LOG
    LC --> LOG
    GS --> LOG
    CSV --> LOG
    PDF --> LOG
    EMS --> LOG

    %% Dependencies
    SR --> DB
    PR --> DB
    DM --> DB

    %% External integration
    KPC --> KCL
    MJC --> KCL

    %% Click Events
    click Frontend "https://github.com/kamblega/dis-final-gale/tree/master/src/main/resources/static/"
    click MC "https://github.com/kamblega/dis-final-gale/blob/master/src/main/java/gale/shapley/controller/MatchingController.java"
    click SC "https://github.com/kamblega/dis-final-gale/blob/master/src/main/java/gale/shapley/controller/StudentController.java"
    click PC "https://github.com/kamblega/dis-final-gale/blob/master/src/main/java/gale/shapley/controller/ProjectController.java"
    click LC "https://github.com/kamblega/dis-final-gale/blob/master/src/main/java/gale/shapley/controller/LeaderController.java"
    click GS "https://github.com/kamblega/dis-final-gale/blob/master/src/main/java/gale/shapley/service/GaleShapleyService.java"
    click CSV "https://github.com/kamblega/dis-final-gale/blob/master/src/main/java/gale/shapley/service/CsvProcessingService.java"
    click PDF "https://github.com/kamblega/dis-final-gale/blob/master/src/main/java/gale/shapley/service/PdfGenerationService.java"
    click EMS "https://github.com/kamblega/dis-final-gale/blob/master/src/main/java/gale/shapley/service/EmailService.java"
    click FSS "https://github.com/kamblega/dis-final-gale/blob/master/src/main/java/gale/shapley/service/FileStorageService.java"
    click STS "https://github.com/kamblega/dis-final-gale/blob/master/src/main/java/gale/shapley/service/StudentService.java"
    click PREF "https://github.com/kamblega/dis-final-gale/blob/master/src/main/java/gale/shapley/PreferenceService.java"
    click PR "https://github.com/kamblega/dis-final-gale/blob/master/src/main/java/gale/shapley/repository/ProjectRepository.java"
    click SR "https://github.com/kamblega/dis-final-gale/blob/master/src/main/java/gale/shapley/repository/StudentRepository.java"
    click SPR "https://github.com/kamblega/dis-final-gale/blob/master/src/main/java/gale/shapley/repository/SupervisorRepository.java"
    click SPRF "https://github.com/kamblega/dis-final-gale/blob/master/src/main/java/gale/shapley/repository/StudentPreferenceRepository.java"
    click STF "https://github.com/kamblega/dis-final-gale/blob/master/src/main/java/gale/shapley/repository/StaffPreferenceRepository.java"
    click KPC "https://github.com/kamblega/dis-final-gale/blob/master/src/main/java/gale/shapley/kafka/KafkaProducerConfig.java"
    click MJC "https://github.com/kamblega/dis-final-gale/blob/master/src/main/java/gale/shapley/kafka/MatchingJobConsumer.java"
    click TOP "https://github.com/kamblega/dis-final-gale/blob/master/src/main/java/gale/shapley/kafka/payload/MatchingJobPayload.java"
    click DB "https://github.com/kamblega/dis-final-gale/blob/master/src/main/resources/application.properties"
    click LOG "https://github.com/kamblega/dis-final-gale/blob/master/src/main/java/gale/shapley/aspect/LoggingAspect.java"

    %% Styles
    classDef frontend fill:#e0f7fa,stroke:#0288d1
    classDef api fill:#bbdefb,stroke:#1976d2
    classDef service fill:#c8e6c9,stroke:#388e3c
    classDef async fill:#ffe0b2,stroke:#f57c00
    classDef persistence fill:#dcedc8,stroke:#558b2f
    classDef cross fill:#f0f4c3,stroke:#afb42b
    classDef external fill:#eeeeee,stroke:#757575
```
