How kamblega/dis-final-gale works
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.