# ameer-hamja/student-club-registration-system architecture

> Architecture diagram of the GitHub repository ameer-hamja/student-club-registration-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ameer-hamja/student-club-registration-system
- Repository: https://github.com/ameer-hamja/student-club-registration-system

## Overview

1. **Overall shape**
   - This is a monorepo with a **React single-page application** in `src/` and a **Spring Boot backend** in `src/main/java`.
   - The architecture is a classic client/API split: the React app renders the UI, and the Java backend exposes REST endpoints for auth, events, users, departments, admin, registration, and transactions.

2. **Frontend presentation layer**
   - The UI is organized around **pages** such as `HomePage`, `EventsPage`, `EventDetailPage`, `DashboardPage`, `AdminPage`, `LoginPage`, and `RegisterPage`.
   - Reusable UI pieces live under `src/components`, including event cards/lists, filters, modals, a navbar, a loading spinner, toast notifications, and a protected-route wrapper.
   - `src/App.js` is the front door of the SPA and likely wires routing between the page-level views.

3. **Frontend state and cross-cutting concerns**
   - `AuthContext` manages client-side authentication state, while `ThemeContext` handles app-wide theme selection.
   - `ProtectedRoute` is the main UI boundary for authenticated pages, keeping unauthenticated users out of dashboard/admin flows.
   - `src/utils/api.js` is the frontend’s API gateway, centralizing calls to the backend instead of letting components talk to HTTP directly.

4. **Frontend business interactions**
   - The visible user flows are centered on **event discovery, event detail viewing, registration/booking, and payment**, with administrative event management alongside them.
   - Components like `DepartmentFilterBar`, `EditEventModal`, and `PaymentModal` indicate the UI supports filtering, editing events, and completing payment-related actions.
   - `Toast` and `LoadingSpinner` are shared feedback mechanisms for async operations.

5. **Backend API layer**
   - Spring controllers are separated by concern: `AuthController`, `EventController`, `DepartmentController`, `UserController`, and `AdminController`.
   - These controllers form the public API surface consumed by the React app.
   - DTO classes such as `AuthRequest`, `AuthResponse`, `EventDTO`, `EventUpdateRequest`, `RegisterRequest`, `RegistrationDTO`, `TransactionDTO`, and `AdminStatsDTO` show the backend avoids exposing entities directly.

6. **Service layer as the main business boundary**
   - The backend business logic is concentrated in services: `EventService`, `RegistrationService`, `PaymentService`, `UserService`, `DepartmentService`, `VenueService`, and `EmailNotificationService`.
   - This layer coordinates validation, domain rules, transaction handling, and side effects such as notifications.
   - `DataSeeder` and `DatabaseSeeder` suggest bootstrap logic for initial data and/or local development setup.

7. **Domain model and persistence**
   - The main persistent entities are `User`, `Event`, `Department`, `Venue`, `Registration`, and `Transaction`.
   - Supporting enums like `Role`, `EventType`, `PaymentStatus`, and `TransactionStatus` define the bounded states the application cares about.
   - Repository interfaces (`UserRepository`, `EventRepository`, `DepartmentRepository`, `VenueRepository`, `RegistrationRepository`, `TransactionRepository`) provide the persistence boundary, likely via Spring Data JPA.

8. **Security architecture**
   - Authentication is JWT-based, implemented with `JwtUtil`, `JwtAuthenticationFilter`, and `CustomUserDetailsService`.
   - `SecurityConfig` is the central policy point for request authorization, protected endpoints, and authentication plumbing.
   - The React side mirrors this with auth context and route protection, so security is enforced both at the API and UI levels.

9. **Registration, booking, and payment flow**
   - The core business flow appears to be: user logs in, browses events, registers for an event, and may complete a payment transaction.
   - `RegistrationService` likely enforces capacity and duplicate-registration rules, supported by custom exceptions such as `DuplicateRegistrationException`, `NoSeatsAvailableException`, and `PaymentFailedException`.
   - `Transaction` plus `TransactionStatus` and `PaymentStatus` indicate the payment lifecycle is tracked explicitly rather than being implicit in registration alone.

10. **Operational concerns and failure handling**
   - `GlobalExceptionHandler` centralizes API error translation into consistent HTTP responses.
   - `application.properties` plus `application-dev.properties` and `application-prod.properties` show environment-specific backend configuration.
   - The presence of `public/` and CRA defaults indicates the frontend is built and served as a standard web client, with a deployed production URL noted in the README.

11. **Likely deployment boundary**
   - The frontend is a CRA-based app, and the README points to a hosted web front end.
   - The backend is a separate Spring Boot runtime with its own configuration and startup entry point in `StudentClubBookingApplication`.
   - For an architecture diagram, the clearest boundary is: **browser → React SPA → Spring Boot REST API → relational persistence and external side effects (email/payment)**.

Main entry points: [`src/main/java/com/example/studentclubbooking/controller`](https://github.com/ameer-hamja/student-club-registration-system/tree/main/src/main/java/com/example/studentclubbooking/controller) (Controllers), [`src/main/java/com/example/studentclubbooking/service`](https://github.com/ameer-hamja/student-club-registration-system/tree/main/src/main/java/com/example/studentclubbooking/service) (Services), [`src/App.js`](https://github.com/ameer-hamja/student-club-registration-system/blob/main/src/App.js) (App shell), [`src/components`](https://github.com/ameer-hamja/student-club-registration-system/tree/main/src/components) (Shared UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend SPA"]
  node_app_shell["App shell<br/>React entry<br/>[App.js]"]
  node_pages["Pages<br/>UI views"]
  node_ui_components["Shared UI<br/>components"]
  node_auth_ctx(("Auth context<br/>client state<br/>[AuthContext.js]"))
  node_theme_ctx(("Theme context<br/>client state<br/>[ThemeContext.js]"))
  node_api_client["API client<br/>HTTP gateway<br/>[api.js]"]
end

subgraph group_backend_api["Backend API"]
  node_controllers["Controllers<br/>REST layer"]
  node_dtos["DTOs<br/>API contracts"]
  node_exception_handler["Errors<br/>exception mapping"]
end

subgraph group_backend_core["Backend Core"]
  node_boot_app["Boot app<br/>Spring Boot entry"]
  node_services["Services<br/>business logic"]
  node_security["Security<br/>JWT auth"]
  node_repositories[("Repositories<br/>persistence")]
  node_models["Domain model<br/>entities"]
  node_seeding["Seed data<br/>bootstrap<br/>[DataSeeder.java]"]
  node_resources["Config"]
  node_external_side_effects{{"External effects<br/>email/payment"}}
end

node_app_shell -->|"routes to"| node_pages
node_app_shell -->|"uses"| node_ui_components
node_app_shell -->|"wraps state"| node_auth_ctx
node_app_shell -->|"wraps theme"| node_theme_ctx
node_pages -->|"composes"| node_ui_components
node_pages -->|"calls"| node_api_client
node_ui_components -->|"reads auth"| node_auth_ctx
node_ui_components -->|"triggers requests"| node_api_client
node_api_client -->|"consumes"| node_controllers
node_boot_app -->|"starts"| node_controllers
node_controllers -->|"exchanges"| node_dtos
node_controllers -->|"delegates to"| node_services
node_controllers -->|"protected by"| node_security
node_services -->|"persists via"| node_repositories
node_services -->|"operates on"| node_models
node_services -->|"invokes"| node_external_side_effects
node_security -->|"loads users"| node_repositories
node_repositories -->|"maps"| node_models
node_seeding -->|"loads data"| node_repositories
node_resources -->|"configures"| node_boot_app
node_exception_handler -->|"handles failures"| node_controllers
node_security -->|"guards"| node_controllers
node_services -->|"throws mapped errors"| node_exception_handler

click node_app_shell "https://github.com/ameer-hamja/student-club-registration-system/blob/main/src/App.js"
click node_pages "https://github.com/ameer-hamja/student-club-registration-system/tree/main/src/pages"
click node_ui_components "https://github.com/ameer-hamja/student-club-registration-system/tree/main/src/components"
click node_auth_ctx "https://github.com/ameer-hamja/student-club-registration-system/blob/main/src/context/AuthContext.js"
click node_theme_ctx "https://github.com/ameer-hamja/student-club-registration-system/blob/main/src/context/ThemeContext.js"
click node_api_client "https://github.com/ameer-hamja/student-club-registration-system/blob/main/src/utils/api.js"
click node_boot_app "https://github.com/ameer-hamja/student-club-registration-system/blob/main/src/main/java/com/example/studentclubbooking/StudentClubBookingApplication.java"
click node_controllers "https://github.com/ameer-hamja/student-club-registration-system/tree/main/src/main/java/com/example/studentclubbooking/controller"
click node_dtos "https://github.com/ameer-hamja/student-club-registration-system/tree/main/src/main/java/com/example/studentclubbooking/dto"
click node_exception_handler "https://github.com/ameer-hamja/student-club-registration-system/blob/main/src/main/java/com/example/studentclubbooking/exception/GlobalExceptionHandler.java"
click node_services "https://github.com/ameer-hamja/student-club-registration-system/tree/main/src/main/java/com/example/studentclubbooking/service"
click node_security "https://github.com/ameer-hamja/student-club-registration-system/tree/main/src/main/java/com/example/studentclubbooking/security"
click node_repositories "https://github.com/ameer-hamja/student-club-registration-system/tree/main/src/main/java/com/example/studentclubbooking/repository"
click node_models "https://github.com/ameer-hamja/student-club-registration-system/tree/main/src/main/java/com/example/studentclubbooking/model"
click node_seeding "https://github.com/ameer-hamja/student-club-registration-system/blob/main/src/main/java/com/example/studentclubbooking/service/DataSeeder.java"
click node_resources "https://github.com/ameer-hamja/student-club-registration-system/tree/main/src/main/resources"

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_app_shell,node_pages,node_ui_components,node_auth_ctx,node_theme_ctx,node_api_client toneBlue
class node_controllers,node_dtos,node_exception_handler toneAmber
class node_boot_app,node_services,node_security,node_repositories,node_models,node_seeding,node_resources,node_external_side_effects toneMint
```

## Components

### Frontend SPA

React client, UI state, and browser-side flows

- [App shell](https://github.com/ameer-hamja/student-club-registration-system/blob/main/src/App.js): React entry · Bootstraps the SPA and routes into the page layer · `src/App.js`
- [Pages](https://github.com/ameer-hamja/student-club-registration-system/tree/main/src/pages): UI views · Top-level screens for browsing, auth, dashboard, and admin · `src/pages`
- [Shared UI](https://github.com/ameer-hamja/student-club-registration-system/tree/main/src/components): components · Reusable presentation pieces such as cards, modals, nav, and feedback · `src/components`
- [Auth context](https://github.com/ameer-hamja/student-club-registration-system/blob/main/src/context/AuthContext.js): client state · Holds login state and auth lifecycle on the client · `src/context/AuthContext.js`
- [Theme context](https://github.com/ameer-hamja/student-club-registration-system/blob/main/src/context/ThemeContext.js): client state · Manages app-wide theme selection · `src/context/ThemeContext.js`
- [API client](https://github.com/ameer-hamja/student-club-registration-system/blob/main/src/utils/api.js): HTTP gateway · Centralized browser-to-backend request layer · `src/utils/api.js`

### Backend API

Spring Boot controllers, DTOs, and request handling

- [Controllers](https://github.com/ameer-hamja/student-club-registration-system/tree/main/src/main/java/com/example/studentclubbooking/controller): REST layer · Public API surface for auth, events, users, departments, and admin · `src/main/java/com/example/studentclubbooking/controller`
- [DTOs](https://github.com/ameer-hamja/student-club-registration-system/tree/main/src/main/java/com/example/studentclubbooking/dto): API contracts · Request and response payload models · `src/main/java/com/example/studentclubbooking/dto`
- [Errors](https://github.com/ameer-hamja/student-club-registration-system/blob/main/src/main/java/com/example/studentclubbooking/exception/GlobalExceptionHandler.java): exception mapping · Translates backend failures into consistent HTTP responses · `src/main/java/com/example/studentclubbooking/exception/GlobalExceptionHandler.java`

### Backend Core

Business services, security, persistence, and domain model

- [Boot app](https://github.com/ameer-hamja/student-club-registration-system/blob/main/src/main/java/com/example/studentclubbooking/StudentClubBookingApplication.java): Spring Boot entry · Main backend startup class · `src/main/java/com/example/studentclubbooking/StudentClubBookingApplication.java`
- [Services](https://github.com/ameer-hamja/student-club-registration-system/tree/main/src/main/java/com/example/studentclubbooking/service): business logic · Coordinates rules, transactions, validation, and side effects · `src/main/java/com/example/studentclubbooking/service`
- [Security](https://github.com/ameer-hamja/student-club-registration-system/tree/main/src/main/java/com/example/studentclubbooking/security): JWT auth · Authentication, authorization, and request filtering · `src/main/java/com/example/studentclubbooking/security`
- [Repositories](https://github.com/ameer-hamja/student-club-registration-system/tree/main/src/main/java/com/example/studentclubbooking/repository): persistence · Data access boundary for Spring Data repositories · `src/main/java/com/example/studentclubbooking/repository`
- [Domain model](https://github.com/ameer-hamja/student-club-registration-system/tree/main/src/main/java/com/example/studentclubbooking/model): entities · Persistent entities and enums for users, events, registrations, and transactions · `src/main/java/com/example/studentclubbooking/model`
- [Seed data](https://github.com/ameer-hamja/student-club-registration-system/blob/main/src/main/java/com/example/studentclubbooking/service/DataSeeder.java): bootstrap · Initial data and database setup routines · `src/main/java/com/example/studentclubbooking/service/DataSeeder.java`
- [Config](https://github.com/ameer-hamja/student-club-registration-system/tree/main/src/main/resources): runtime config · Environment-specific application properties and server templates · `src/main/resources`
- **External effects**: email/payment · Notification delivery and payment processing boundaries

## Connections

- App shell → Pages: routes to · The SPA entry composes page-level screens
- App shell → Shared UI: uses · Shared UI is assembled by the root app
- App shell → Auth context: wraps state · Client auth state is provided across the app
- App shell → Theme context: wraps theme · Theme selection is propagated through the app
- Pages → Shared UI: composes · Pages reuse shared cards, modals, filters, and feedback
- Pages → API client: calls · Screens fetch and mutate backend data through the API layer
- Shared UI → Auth context: reads auth · Protected UI and navigation depend on auth state
- Shared UI → API client: triggers requests · Interactive components initiate backend operations
- API client → Controllers: consumes · Browser requests land on the REST API
- Boot app → Controllers: starts · Spring Boot wires the web layer
- Controllers → DTOs: exchanges · Controllers accept and return structured payloads
- Controllers → Services: delegates to · Request handling is thin and forwards to business services
- Controllers → Security: protected by · API access is governed by JWT security
- Services → Repositories: persists via · Business logic uses repositories for storage access
- Services → Domain model: operates on · Services coordinate the core domain objects
- Services → External effects: invokes · Payment and notification flows cross system boundaries
- Security → Repositories: loads users · Authentication depends on persistent user lookup
- Repositories → Domain model: maps · Repository interfaces are backed by domain entities
- Seed data → Repositories: loads data · Bootstrap routines populate the database through repositories
- Config → Boot app: configures · Runtime properties and templates shape application startup
- Errors → Controllers: handles failures · Controller errors are converted into HTTP responses
- Security → Controllers: guards · Request authorization sits in front of the API surface
- Services → Errors: throws mapped errors · Business rule failures are translated centrally