Component Architecture

1. Overview

This document provides a detailed architectural overview of the Event and Membership Administration System components. It describes the design principles, architectural patterns, and component responsibilities that guide the system’s structure.

2. Architectural Style

The system employs a layered architecture with elements of microservices design:

  • Clear separation between presentation, application, domain, and infrastructure layers

  • Independent deployability of frontend and backend components

  • RESTful API communication between layers

  • Database-per-service pattern (logical separation within shared MySQL instance)

3. System Layers

system-layers

3.1. Presentation Layer

Components: admin-ui, member-ui

Responsibilities:

  • User interface rendering

  • User interaction handling

  • Client-side validation

  • Session management

  • API request/response handling

Technologies:

  • React 18 with functional components and hooks

  • TypeScript for type safety

  • Material-UI component library

  • Axios for HTTP communication

  • React Router for navigation

3.2. Application Layer

Components: admin-service

Responsibilities:

  • Business logic implementation

  • API endpoint exposure

  • Request validation and error handling

  • Transaction management

  • Security and authorization

  • External service integration

Technologies:

  • Spring Boot 2.7+

  • Spring Web MVC

  • Spring Security

  • Spring Data JPA

  • Jackson for JSON serialization

3.3. Domain Layer

Components: event-database, wordpress-database, event-common

Responsibilities:

  • Entity definitions (JPA)

  • Repository interfaces

  • Domain logic and business rules

  • Data access abstractions

  • Shared utility functions

Technologies:

  • Jakarta Persistence API (JPA)

  • Hibernate ORM

  • Spring Data JPA

  • Bean Validation API

3.4. Infrastructure Layer

Components: MySQL databases

Responsibilities:

  • Data persistence

  • Data integrity constraints

  • Query execution

  • Transaction management

  • Backup and recovery

4. Component Descriptions

4.1. Parent POMs

4.1.1. event

The root parent POM that establishes the foundation for all Maven-based components in the system.

Repository: https://github.com/christhonie/event

Maven Coordinates:

<groupId>za.co.idealogic</groupId>
<artifactId>event</artifactId>
<version>${revision}</version>
<packaging>pom</packaging>

Responsibilities:

  • Version Management - Defines versions for all internal components

  • Dependency Management - Manages third-party dependency versions

  • Plugin Configuration - Standardizes build plugin configuration

  • Property Definitions - Defines common properties (Java version, encoding, etc.)

Key Properties:

<properties>
  <revision>1.2.0-SNAPSHOT</revision>
  <java.version>11</java.version>
  <maven.compiler.source>11</maven.compiler.source>
  <maven.compiler.target>11</maven.compiler.target>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  <spring-boot.version>2.7.14</spring-boot.version>
</properties>

Managed Dependencies:

  • Spring Boot BOM

  • Spring Cloud dependencies

  • Database drivers (MySQL)

  • Utility libraries (Lombok, MapStruct, Commons Lang)

  • All internal components (event-common, event-database, etc.)

4.2. Common Libraries

4.2.1. event-common

Shared utility library providing common functionality used across all components.

Repository: https://github.com/christhonie/event-common

Maven Coordinates:

<groupId>za.co.idealogic</groupId>
<artifactId>event-common</artifactId>
<version>${revision}</version>

Package Structure:

za.co.idealogic.event.common
├── constants/          - System-wide constants
├── util/              - Utility classes
│   ├── DateUtils
│   ├── StringUtils
│   └── ValidationUtils
├── exception/         - Common exception classes
│   ├── BusinessException
│   ├── ValidationException
│   └── ResourceNotFoundException
└── dto/               - Shared DTOs
    ├── PageRequest
    ├── PageResponse
    └── ErrorResponse

Key Classes:

  • DateUtils - Date manipulation and formatting utilities

  • StringUtils - String processing utilities (complement to Apache Commons)

  • ValidationUtils - Common validation logic

  • BusinessException - Base exception for business rule violations

  • PageRequest/PageResponse - Pagination DTOs

Design Principles:

  • No business logic - Only utility and infrastructure code

  • Stateless - All utility methods are static

  • Well-tested - High unit test coverage

  • Minimal dependencies - Only essential third-party libraries

4.3. Database Libraries

See Database Components for detailed information about event-database and wordpress-database.

4.4. Backend Services

See Backend Services for detailed information about admin-service.

4.5. Frontend Applications

See Frontend Applications for detailed information about admin-ui and member-ui.

5. Architectural Patterns

5.1. Repository Pattern

All database access is abstracted through Spring Data JPA repositories:

public interface EventRepository extends JpaRepository<Event, Long> {
    List<Event> findByOrganisationId(Long organisationId);

    List<Event> findByStartDateBetween(LocalDate start, LocalDate end);

    @Query("SELECT e FROM Event e WHERE e.status = :status " +
           "AND e.organisation.id = :orgId")
    List<Event> findActiveEventsByOrganisation(
        @Param("orgId") Long orgId,
        @Param("status") EventStatus status
    );
}

Benefits:

  • Abstracts database access details

  • Provides type-safe queries

  • Enables easy testing with repository mocks

  • Supports query method derivation

5.2. Service Layer Pattern

Business logic is encapsulated in service classes:

@Service
@Transactional
public class EventService {
    private final EventRepository eventRepository;
    private final EventCategoryRepository categoryRepository;

    public Event createEvent(EventCreateRequest request) {
        // Validation
        validateEventDates(request);

        // Business logic
        Event event = new Event();
        event.setName(request.getName());
        event.setStartDate(request.getStartDate());
        event.setEndDate(request.getEndDate());

        // Persistence
        return eventRepository.save(event);
    }
}

Benefits:

  • Centralizes business logic

  • Provides transaction boundaries

  • Enables service-level security

  • Facilitates testing with service mocks

5.3. DTO Pattern

Data Transfer Objects separate API contracts from domain entities:

public class EventResponse {
    private Long id;
    private String name;
    private LocalDate startDate;
    private LocalDate endDate;
    private String status;
    private List<CategoryResponse> categories;

    // Getters and setters
}

Benefits:

  • API stability - internal entity changes don’t affect API

  • Security - prevents over-posting and data exposure

  • Performance - allows selective field loading

  • Versioning - supports multiple API versions

5.4. REST API Pattern

All backend services expose RESTful APIs:

@RestController
@RequestMapping("/api/events")
public class EventController {
    private final EventService eventService;

    @GetMapping
    public PageResponse<EventResponse> getEvents(
        @RequestParam(required = false) Long organisationId,
        @PageableDefault Pageable pageable
    ) {
        return eventService.getEvents(organisationId, pageable);
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public EventResponse createEvent(@Valid @RequestBody EventCreateRequest request) {
        return eventService.createEvent(request);
    }

    @GetMapping("/{id}")
    public EventResponse getEvent(@PathVariable Long id) {
        return eventService.getEvent(id);
    }
}

REST Conventions:

  • HTTP methods: GET (read), POST (create), PUT (full update), PATCH (partial update), DELETE (remove)

  • Status codes: 200 (OK), 201 (Created), 204 (No Content), 400 (Bad Request), 404 (Not Found), 500 (Server Error)

  • Resource naming: Plural nouns (/events, /participants)

  • Pagination: Query parameters (page, size, sort)

6. Cross-Cutting Concerns

6.1. Security

Implemented at the application layer using Spring Security:

  • Authentication - JWT token-based authentication

  • Authorization - Role-based access control (RBAC)

  • Multi-Tenancy - Organisation-scoped security

  • Person-Level Security - User-specific data access

See Security Architecture for details.

6.2. Transaction Management

Managed by Spring’s declarative transaction management:

  • @Transactional annotations on service methods

  • Transaction propagation and isolation levels

  • Rollback rules for checked/unchecked exceptions

6.3. Error Handling

Centralized error handling using @ControllerAdvice:

@ControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(BusinessException.class)
    public ResponseEntity<ErrorResponse> handleBusinessException(BusinessException ex) {
        return ResponseEntity
            .status(HttpStatus.BAD_REQUEST)
            .body(new ErrorResponse(ex.getCode(), ex.getMessage()));
    }

    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleNotFound(ResourceNotFoundException ex) {
        return ResponseEntity
            .status(HttpStatus.NOT_FOUND)
            .body(new ErrorResponse("NOT_FOUND", ex.getMessage()));
    }
}

6.4. Logging

Standardized logging using SLF4J with Logback:

  • Structured logging with MDC (Mapped Diagnostic Context)

  • Correlation IDs for request tracing

  • Log levels: ERROR, WARN, INFO, DEBUG, TRACE

  • Separate logs for application, security, and audit events

6.5. Validation

Multi-layer validation strategy:

  • Client-side - React form validation

  • API layer - Bean Validation annotations (@Valid, @NotNull, etc.)

  • Service layer - Business rule validation

  • Database layer - Constraints and triggers

7. Component Communication

7.1. Synchronous Communication

HTTP REST APIs:

  • Frontend → Backend: REST API calls over HTTPS

  • Request/Response pattern

  • JSON payload format

  • Correlation IDs for tracing

Example Flow:

1. User clicks "Create Event" in admin-ui
2. admin-ui sends POST /api/events with JSON payload
3. admin-service validates request
4. admin-service executes business logic
5. admin-service persists data via event-database
6. admin-service returns EventResponse JSON
7. admin-ui displays success message

7.2. Asynchronous Communication

Currently, the system uses synchronous communication only. Future enhancements may include:

  • Message Queue - For background processing (email notifications, reports)

  • Event Bus - For domain events and eventual consistency

  • WebSockets - For real-time updates (live race results)

8. Scalability Considerations

8.1. Horizontal Scaling

Frontend Applications:

  • Stateless design enables easy scaling

  • Can be served via CDN

  • Multiple instances behind load balancer

Backend Services:

  • Stateless REST APIs enable horizontal scaling

  • Session data stored in shared cache (Redis)

  • Multiple instances behind load balancer

8.2. Vertical Scaling

  • Database connection pooling (HikariCP)

  • JVM tuning for optimal memory usage

  • Database query optimization and indexing

8.3. Caching Strategy

Application-Level Caching:

  • Spring Cache abstraction

  • Ehcache for local caching

  • Redis for distributed caching (future)

Database-Level Caching:

  • Hibernate second-level cache

  • MySQL query cache

  • Result set caching for expensive queries

9. Deployment Architecture

Components are deployed as separate artifacts:

  • Frontend - Static files served by Nginx or CDN

  • Backend - Spring Boot executable JAR

  • Database - MySQL server instances

See Deployment Documentation for detailed deployment procedures.

10. Development Environment

10.1. Local Development Setup

Prerequisites:

  • JDK 11 or later

  • Maven 3.8+

  • Node.js 16+ and npm 8+

  • MySQL 8.0+

  • IDE (IntelliJ IDEA, VS Code, Eclipse)

Build Process:

# Clone repositories
git clone https://github.com/christhonie/event
git clone https://github.com/christhonie/event-common
git clone https://github.com/christhonie/event-database
git clone https://github.com/christhonie/admin-service
git clone https://github.com/christhonie/admin-ui

# Build parent and libraries
cd event && mvn clean install
cd ../event-common && mvn clean install
cd ../event-database && mvn clean install

# Build and run backend
cd ../admin-service
mvn spring-boot:run

# Build and run frontend
cd ../admin-ui
npm install
npm start

10.2. Testing Strategy

Unit Tests:

  • JUnit 5 for Java components

  • Jest for React components

  • Mockito for mocking dependencies

  • High code coverage targets (>80%)

Integration Tests:

  • Spring Boot Test for service integration tests

  • Testcontainers for database integration tests

  • REST Assured for API testing

End-to-End Tests:

  • Cypress or Playwright for UI tests

  • Test complete user workflows

  • Run in CI/CD pipeline

11. Related Documentation