# tn-varunram/athledger architecture

> Architecture diagram of the GitHub repository tn-varunram/athledger, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tn-varunram/athledger
- Repository: https://github.com/tn-varunram/athledger

## Overview

#### Purpose and deployment shape
Athledger is a containerized sports-slot platform: users authenticate, administrators manage sports/slots, users book slots, and notification delivery is event-driven. The operational entry point is `docker-compose.yml`; Kubernetes manifests exist but the README identifies Docker as the working deployment path. Shared MySQL initialization is in `init.sql`; Kafka and MySQL are infrastructure dependencies.

#### Frontend client and edge serving
The React single-page client is rooted at `Frontend/Athledger-UI/src/index.js` and composed from `Frontend/Athledger-UI/src/App.js`. Its main UI paths cover authentication and booking through `Frontend/Athledger-UI/src/Components/header/LoginModal.jsx` and `Frontend/Athledger-UI/src/Components/body/SlotBookingModal.jsx`. API calls are centralized at `Frontend/Athledger-UI/src/api/request.js`. The frontend has a Docker/Nginx delivery boundary in `Frontend/Athledger-UI/Dockerfile` and `Frontend/Athledger-UI/nginx.conf`.

#### Authorization service
A standalone Spring Boot service starts at `Backend/authorization/src/main/java/com/athledger/authorization/AuthorizationApplication.java`. HTTP authentication flows enter through `Backend/authorization/src/main/java/com/athledger/authorization/controller/AuthController.java` and `Backend/authorization/src/main/java/com/athledger/authorization/controller/LoginController.java`, then persist users/roles through `Backend/authorization/src/main/java/com/athledger/authorization/repository/UserRepository.java`. JWT issuance and request filtering establish the security boundary in `Backend/authorization/src/main/java/com/athledger/authorization/utils/JwtUtil.java` and `Backend/authorization/src/main/java/com/athledger/authorization/config/JwtAuthFilter.java`.

#### Slot management service
Slot management is a separate Spring Boot bounded context, entered at `Backend/slotmgmt/src/main/java/com/athledger/slotmgmt/SlotmgmtApplication.java`. `SlotController.java` manages slot APIs while `SportsController.java` manages sport catalog APIs; domain persistence is split between `SlotRepository.java` and `SportRepository.java`. Its `AuthorizationService.java` plus `AuthInterceptor.java` indicate that access checks are performed across the service boundary rather than through a shared backend library.

#### Booking service
Booking starts at `Backend/slotbooking/src/main/java/com/athledger/slotbooking/SlotbookingApplication.java`; `BookingController.java` accepts booking operations and delegates to `BookingService.java`. It owns booking and slot persistence models/repositories, including `BookingRepository.java` and `SlotRepository.java`, making booking availability/state distinct from the management service’s slot catalog. `AuthInterceptor.java` and service security configuration form its protected API boundary.

#### Asynchronous notifications
The authorization service publishes user-related notification events using `Backend/authorization/src/main/java/com/athledger/authorization/kafka/UserEventProducer.java`, configured by `KafkaProducerConfig.java`. The notification Spring Boot process starts at `Backend/notification/src/main/java/com/athledger/notificationservice/NotificationApplication.java`, consumes user and booking events via `UserEventListener.java` and `BookingEventConsumer.java`, and delivers email through `EmailService.java`. Kafka decouples notification side effects from synchronous auth/booking requests.

#### Runtime and infrastructure boundaries
Each backend service has an independent Gradle build and Docker image, for example `Backend/authorization/Dockerfile`, `Backend/slotmgmt/Dockerfile`, and `Backend/slotbooking/Dockerfile`. Runtime configuration is service-local in corresponding `src/main/resources/application.properties` files. Kubernetes definitions provision frontend, MySQL, Kafka, and the three core business services under `k8s/`; notification lacks a visible Kubernetes deployment manifest. CORS is explicitly configured in service web/security configurations, and is a documented deployment risk behind the Kubernetes load balancer.

Main entry points: [`Backend/authorization/src/main/java/com/athledger/authorization/AuthorizationApplication.java`](https://github.com/tn-varunram/athledger/blob/main/Backend/authorization/src/main/java/com/athledger/authorization/AuthorizationApplication.java) (Authorization service), [`docker-compose.yml`](https://github.com/tn-varunram/athledger/blob/main/docker-compose.yml) (Docker Compose), [`Backend/slotbooking/src/main/java/com/athledger/slotbooking/SlotbookingApplication.java`](https://github.com/tn-varunram/athledger/blob/main/Backend/slotbooking/src/main/java/com/athledger/slotbooking/SlotbookingApplication.java) (Booking service), [`Frontend/Athledger-UI/src/api/request.js`](https://github.com/tn-varunram/athledger/blob/main/Frontend/Athledger-UI/src/api/request.js) (API request client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_edge["Nginx frontend image<br/>container edge"]
  node_spa["React SPA<br/>web client<br/>[App.js]"]
  node_client_api["API request client<br/>HTTP client<br/>[request.js]"]
end

subgraph group_services["Spring services"]
  node_auth_service["Authorization service<br/>Spring Boot service"]
  node_auth_api["Auth controllers<br/>HTTP API"]
  node_jwt_security["JWT security boundary<br/>token filter<br/>[JwtAuthFilter.java]"]
  node_user_store[("Users and roles")]
  node_slot_service["Slot management service<br/>Spring Boot service"]
  node_slot_api["Slots and sports API<br/>HTTP API"]
  node_booking_service["Booking service<br/>Spring Boot service"]
  node_booking_api["Booking API<br/>HTTP API"]
  node_booking_logic["Booking service layer<br/>domain service"]
  node_booking_store[("Booking data")]
end

subgraph group_messaging["Notifications"]
  node_notification_service["Notification service<br/>Spring Boot worker"]
  node_notification_consumers["Event consumers<br/>Kafka consumers"]
  node_email_service["Email delivery<br/>notification adapter"]
end

subgraph group_infra["Runtime infrastructure"]
  node_compose["Docker Compose<br/>deployment entrypoint<br/>[docker-compose.yml]"]
  node_kafka["Kafka<br/>event broker"]
  node_mysql[("MySQL<br/>shared database<br/>[init.sql]")]
  node_kubernetes["Kubernetes manifests<br/>alternate deployment"]
end

node_compose -->|"runs"| node_frontend_edge
node_compose -->|"runs"| node_auth_service
node_compose -->|"runs"| node_slot_service
node_compose -->|"runs"| node_booking_service
node_compose -->|"provisions"| node_kafka
node_compose -->|"provisions"| node_mysql
node_frontend_edge -->|"serves"| node_spa
node_spa -->|"uses"| node_client_api
node_client_api -->|"authentication requests"| node_auth_api
node_client_api -->|"slot and sport requests"| node_slot_api
node_client_api -->|"booking requests"| node_booking_api
node_auth_service -->|"exposes"| node_auth_api
node_auth_api -->|"authenticates"| node_jwt_security
node_auth_api -->|"persists"| node_user_store
node_auth_service -->|"publishes user events"| node_kafka
node_slot_service -->|"exposes"| node_slot_api
node_slot_service -->|"checks authorization"| node_auth_service
node_booking_service -->|"exposes"| node_booking_api
node_booking_api -->|"delegates"| node_booking_logic
node_booking_logic -->|"persists"| node_booking_store
node_booking_service -->|"checks authorization"| node_auth_service
node_booking_service -.->|"publishes booking events"| node_kafka
node_notification_service -->|"runs"| node_notification_consumers
node_kafka -->|"delivers events"| node_notification_consumers
node_notification_consumers -->|"triggers"| node_email_service
node_auth_service -->|"stores users"| node_mysql
node_slot_service -->|"stores catalog"| node_mysql
node_booking_service -->|"stores bookings"| node_mysql
node_kubernetes -.->|"defines deployment"| node_frontend_edge
node_kubernetes -.->|"defines deployment"| node_auth_service

click node_compose "https://github.com/tn-varunram/athledger/blob/main/docker-compose.yml"
click node_frontend_edge "https://github.com/tn-varunram/athledger/blob/main/Frontend/Athledger-UI/Dockerfile"
click node_spa "https://github.com/tn-varunram/athledger/blob/main/Frontend/Athledger-UI/src/App.js"
click node_client_api "https://github.com/tn-varunram/athledger/blob/main/Frontend/Athledger-UI/src/api/request.js"
click node_auth_service "https://github.com/tn-varunram/athledger/blob/main/Backend/authorization/src/main/java/com/athledger/authorization/AuthorizationApplication.java"
click node_auth_api "https://github.com/tn-varunram/athledger/blob/main/Backend/authorization/src/main/java/com/athledger/authorization/controller/AuthController.java"
click node_jwt_security "https://github.com/tn-varunram/athledger/blob/main/Backend/authorization/src/main/java/com/athledger/authorization/config/JwtAuthFilter.java"
click node_user_store "https://github.com/tn-varunram/athledger/blob/main/Backend/authorization/src/main/java/com/athledger/authorization/repository/UserRepository.java"
click node_slot_service "https://github.com/tn-varunram/athledger/blob/main/Backend/slotmgmt/src/main/java/com/athledger/slotmgmt/SlotmgmtApplication.java"
click node_booking_service "https://github.com/tn-varunram/athledger/blob/main/Backend/slotbooking/src/main/java/com/athledger/slotbooking/SlotbookingApplication.java"
click node_notification_service "https://github.com/tn-varunram/athledger/blob/main/Backend/notification/src/main/java/com/athledger/notificationservice/NotificationApplication.java"
click node_mysql "https://github.com/tn-varunram/athledger/blob/main/init.sql"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_edge,node_spa,node_client_api toneBlue
class node_auth_service,node_auth_api,node_jwt_security,node_user_store,node_slot_service,node_slot_api,node_booking_service,node_booking_api,node_booking_logic,node_booking_store toneAmber
class node_notification_service,node_notification_consumers,node_email_service toneMint
class node_compose,node_kafka,node_mysql,node_kubernetes toneRose
```

## Components

### Frontend

- [Nginx frontend image](https://github.com/tn-varunram/athledger/blob/main/Frontend/Athledger-UI/Dockerfile): container edge · Builds and serves the SPA. · `Frontend/Athledger-UI/Dockerfile`
- [React SPA](https://github.com/tn-varunram/athledger/blob/main/Frontend/Athledger-UI/src/App.js): web client · `Frontend/Athledger-UI/src/App.js`
- [API request client](https://github.com/tn-varunram/athledger/blob/main/Frontend/Athledger-UI/src/api/request.js): HTTP client · `Frontend/Athledger-UI/src/api/request.js`

### Spring services

- [Authorization service](https://github.com/tn-varunram/athledger/blob/main/Backend/authorization/src/main/java/com/athledger/authorization/AuthorizationApplication.java): Spring Boot service · `Backend/authorization/src/main/java/com/athledger/authorization/AuthorizationApplication.java`
- [Auth controllers](https://github.com/tn-varunram/athledger/blob/main/Backend/authorization/src/main/java/com/athledger/authorization/controller/AuthController.java): HTTP API · Login and authentication flows. · `Backend/authorization/src/main/java/com/athledger/authorization/controller/AuthController.java`
- [JWT security boundary](https://github.com/tn-varunram/athledger/blob/main/Backend/authorization/src/main/java/com/athledger/authorization/config/JwtAuthFilter.java): token filter · Issues and validates protected requests. · `Backend/authorization/src/main/java/com/athledger/authorization/config/JwtAuthFilter.java`
- [Users and roles](https://github.com/tn-varunram/athledger/blob/main/Backend/authorization/src/main/java/com/athledger/authorization/repository/UserRepository.java): repository · `Backend/authorization/src/main/java/com/athledger/authorization/repository/UserRepository.java`
- [Slot management service](https://github.com/tn-varunram/athledger/blob/main/Backend/slotmgmt/src/main/java/com/athledger/slotmgmt/SlotmgmtApplication.java): Spring Boot service · `Backend/slotmgmt/src/main/java/com/athledger/slotmgmt/SlotmgmtApplication.java`
- **Slots and sports API**: HTTP API · Administration of slots and sport catalog.
- [Booking service](https://github.com/tn-varunram/athledger/blob/main/Backend/slotbooking/src/main/java/com/athledger/slotbooking/SlotbookingApplication.java): Spring Boot service · `Backend/slotbooking/src/main/java/com/athledger/slotbooking/SlotbookingApplication.java`
- **Booking API**: HTTP API
- **Booking service layer**: domain service · Owns booking availability and state.
- **Booking data**: repository

### Notifications

- [Notification service](https://github.com/tn-varunram/athledger/blob/main/Backend/notification/src/main/java/com/athledger/notificationservice/NotificationApplication.java): Spring Boot worker · `Backend/notification/src/main/java/com/athledger/notificationservice/NotificationApplication.java`
- **Event consumers**: Kafka consumers · Consumes user and booking events.
- **Email delivery**: notification adapter

### Runtime infrastructure

- [Docker Compose](https://github.com/tn-varunram/athledger/blob/main/docker-compose.yml): deployment entrypoint · Working local deployment path. · `docker-compose.yml`
- **Kafka**: event broker
- [MySQL](https://github.com/tn-varunram/athledger/blob/main/init.sql): shared database · Initialized with shared schema data. · `init.sql`
- **Kubernetes manifests**: alternate deployment · Notification deployment is not visible.

## Connections

- Docker Compose → Nginx frontend image: runs
- Docker Compose → Authorization service: runs
- Docker Compose → Slot management service: runs
- Docker Compose → Booking service: runs
- Docker Compose → Kafka: provisions
- Docker Compose → MySQL: provisions
- Nginx frontend image → React SPA: serves
- React SPA → API request client: uses
- API request client → Auth controllers: authentication requests
- API request client → Slots and sports API: slot and sport requests
- API request client → Booking API: booking requests
- Authorization service → Auth controllers: exposes
- Auth controllers → JWT security boundary: authenticates
- Auth controllers → Users and roles: persists
- Authorization service → Kafka: publishes user events
- Slot management service → Slots and sports API: exposes
- Slot management service → Authorization service: checks authorization
- Booking service → Booking API: exposes
- Booking API → Booking service layer: delegates
- Booking service layer → Booking data: persists
- Booking service → Authorization service: checks authorization
- Booking service → Kafka: publishes booking events
- Notification service → Event consumers: runs
- Kafka → Event consumers: delivers events
- Event consumers → Email delivery: triggers
- Authorization service → MySQL: stores users
- Slot management service → MySQL: stores catalog
- Booking service → MySQL: stores bookings
- Kubernetes manifests → Nginx frontend image: defines deployment
- Kubernetes manifests → Authorization service: defines deployment