Architecture

1. Overview

The Registration Portal is built as a JHipster gateway application, providing a single entry point for user interactions while proxying backend operations to the admin-service. This architecture enables authentication, API routing, and a modern Angular frontend.

Repository: https://github.com/christhonie/event-registration-ui

Application Type: JHipster Gateway with Angular frontend

2. Technology Stack

2.1. Frontend

  • Framework: Angular 17+

  • Build Tools: Node.js 18+, npm 9+, Angular CLI

  • Key Libraries: Angular Router, Reactive Forms, RxJS, Bootstrap 5, NgBootstrap

2.2. Backend (Gateway)

  • Framework: Spring Boot 3.1+

  • Key Components: Spring Cloud Gateway, Spring Security

  • Java Version: Java 17+

2.3. Authentication

  • Protocol: JWT tokens via hash-based authentication or OAuth2/OIDC with backend token exchange

  • Token Storage: Server-side HTTP session (never exposed to frontend)

  • Token Refresh: Automatic OIDC token refresh; hash-based tokens require re-authentication

2.4. Database

  • Primary Database: MySQL 8.0+ (via admin-service)

  • Gateway Database: Minimal local storage for session management

3. Architectural Layers

architecture-layers

3.1. Presentation Layer

Responsibilities:

  • User interface rendering

  • User interaction handling

  • Client-side validation

  • State management

  • HTTP client operations

3.2. Gateway Layer

Responsibilities:

  • API gateway routing

  • JWT token validation

  • Tenant resolution and context management

  • Request/response transformation

  • Circuit breaker patterns

3.3. Backend Layer

Responsibilities:

  • Business logic execution

  • Data validation

  • Entity management

  • Process orchestration

Handled by: admin-service (separate repository)

4. Multi-Tenant Architecture

The Registration Portal supports multi-tenant operation where a single application instance serves multiple organizations:

  • URL-based Tenant Determination - Subdomain or X-TENANT-ID header

  • Data Isolation - Each organization’s data is completely isolated

  • Shared Infrastructure - Single application deployment serves all organizations

  • Tenant → RegistrationSystem → Organisation - Tenant resolution flows through RegistrationSystem to Organisation

5. Component Structure

5.1. Frontend Structure

src/main/webapp/app/
├── account/                    # User account management
├── admin/                      # Admin features
├── core/                       # Core services
│   ├── interceptor/           # HTTP interceptors
│   └── services/              # Core business services
│       ├── form.service.ts
│       ├── linked-person-state.service.ts
│       └── membership.service.ts
├── entities/                   # Entity management
│   ├── admin-service/         # Proxied entities
│   ├── linked-person/         # LinkedPerson workflows
│   ├── membership/            # Membership workflows
│   └── registration/          # Event registration
├── layouts/                    # Layout components
├── shared/                     # Shared utilities
└── ui/                         # UI-specific components

5.2. Backend Structure (Gateway)

src/main/java/za/co/idealogic/event/
├── config/                     # Configuration
├── security/                   # Security components
├── web/                        # REST controllers and filters
└── gateway/                    # Gateway-specific components

6. Development Environment

6.1. Prerequisites

  • JDK 17 or later

  • Node.js 18.x or later

  • npm 9.x or later

  • MySQL 8.0 or later

6.2. Running Locally

Backend (Gateway):

# Start MySQL
docker-compose -f src/main/docker/mysql.yml up -d

# Run gateway
./mvnw spring-boot:run

Frontend (Angular):

npm install
npm start

Access:

7. Cross-Cutting Designs

These pages describe contracts that features plug into rather than designing any single feature. They are the architectural rails that event-registration, membership-registration, and future flows build on.

7.1. Navigation & Return-State Architecture

Canonical screen inventory and the three-tier return-state contract that keeps generic screens flow-agnostic:

  • Screen graph (generic vs flow-specific boundaries)

  • Tier 1 in-memory return URL, Tier 2 sessionStorage flow context, Tier 3 org-landing fallback

  • SessionService API and FlowContext type

  • Caller/callee implementation patterns

  • Step-by-step guide for adding a new flow

See Navigation & Return-State Architecture for details.

7.2. Process Flow Integration

The Registration Portal leverages ProcessDefinition entities to create dynamic, sequential form workflows:

  • Sequential steps with back navigation

  • Batch processing for multiple participants

  • ProcessData as a staging area before business-entity creation

  • FormField factory and question-type catalogue

  • Progress tracking

See Process Flow Integration for details.

7.3. Security Implementation

Implementation details for the security architecture:

  • Hash-based authentication endpoint (AuthenticationResource)

  • OIDC authentication with backend token exchange

  • JWT session management and automatic refresh

  • JWT relay filter for backend requests

  • Tenant context handling

See Security Implementation for details.

8. Module Contents

9. Related Documentation

  • Requirements - Functional and non-functional requirements

  • Design - Detailed implementation design