Common/Infrastructure Entities

1. Overview

Common entities provide infrastructure and reference data used across all tenants in the system. These 14 entities support multi-tenancy, user management, and shared reference data.

2. Organisation & User Management

2.1. Organisation

The root entity for multi-tenancy. Each organisation represents a separate tenant with its own events, memberships, and financial records.

Package: za.co.idealogic.event.domain
Repository: event-database

Key Relationships:

  • One-to-many with OrgUser (organisation members)

  • One-to-many with Event (organisation’s events)

  • One-to-many with Membership (organisation memberships)

  • One-to-many with Order (organisation orders)

2.2. OrgUser

Represents a system user account with login credentials for a registration system. Identified by RegistrationSystemId:UserKey combination.

Package: za.co.idealogic.event.domain
Repository: event-database

Key Relationships:

  • Many-to-one with Organisation

  • Many-to-one with User (WordPress legacy - to be replaced with Person)

  • One-to-many with OrgPermission

  • One-to-one with Person (principal person for this account)

  • One-to-many with LinkedPerson (dependent persons managed by this account)

Design Notes:

  • OrgUser does not store user credentials (handled by external registration systems)

  • Identified by RegistrationSystemId + UserKey

  • Each OrgUser can have one principal Person and multiple linked Persons

2.3. Person

Migration Status: To be implemented within 3 months

This entity will replace the WordPress User + UserMeta pattern for representing natural persons.

Planned Entity: Person entity with flattened structure for common attributes.

Package: za.co.idealogic.event.domain (future)
Repository: event-database

Purpose:

Represents a natural person in the system, separate from authentication/login concerns.

Key Attributes (Planned):

  • First name, last name

  • ID number, date of birth

  • Gender, nationality

  • Contact information

  • Physical address

Key Relationships (Planned):

  • One-to-one with OrgUser (when person is principal)

  • Many-to-one with OrgUser via LinkedPerson (when person is dependent)

  • One-to-many with EventParticipant

  • One-to-many with Membership

  • Referenced by RaceNumber, Tag (last assigned person)

Migration Plan:

  • Users with passwords (not @members.wpcycling.com) → OrgUser + Person (principal)

  • Users without passwords → Person only

  • WordPress ManagedBy records → LinkedPerson records

  • Keep Person.id same as User.id (no business entity ID updates needed)

Companion Entity: PersonMeta for flexible additional attributes (similar to UserMeta pattern)

Current Implementation: See User (WordPress legacy)

2.4. OrgPermission

Defines permissions for users within an organisation, controlling access to features and data.

Package: za.co.idealogic.event.domain
Repository: event-database

Key Relationships:

  • Many-to-one with OrgUser

2.5. LinkedPerson

Join table linking an OrgUser to dependent Person records for managing team members, club members, guardians, or family members.

Package: za.co.idealogic.event.domain
Repository: event-database

Key Relationships:

  • Many-to-one with OrgUser (the principal account holder)

  • Many-to-one with Person (the dependent person)

Attributes:

  • Relationship qualifier (anonymous, managed, parent-child, etc.)

  • Permissions (can principal edit dependent’s details?)

Use Cases:

  • Parent registering children for events

  • Team captain managing team members

  • Club administrator managing club members

  • Guardian relationships

  • Anonymous linkage (entered into race, person already linked elsewhere)

  • Managed linkage (principal can edit dependent’s details)

Migration Note:

Replaces WordPress ManagedBy relationship during Person entity migration.

3. Reference Data

3.1. Country

Standard country reference data used throughout the system for addresses and nationality.

Package: za.co.idealogic.event.domain
Repository: event-database

Attributes:

  • Country codes (ISO standards)

  • Country names

  • Regional information

3.2. Discipline

Defines sport disciplines (e.g., Athletics, Swimming, Cycling, Triathlon).

Package: za.co.idealogic.event.domain
Repository: event-database

Key Relationships:

  • Referenced by Events

  • Referenced by Memberships

  • Used for categorization and filtering

3.3. CustomList

Provides configurable dropdown lists and lookup values for dynamic form fields.

Package: za.co.idealogic.event.domain
Repository: event-database

Key Relationships:

  • One-to-many with CustomListValue

Use Cases:

  • Custom event categories

  • Additional participant fields

  • Organisation-specific classifications

3.4. CustomListValue

Individual values within a CustomList.

Package: za.co.idealogic.event.domain
Repository: event-database

Key Relationships:

  • Many-to-one with CustomList

4. File & Attachment Management

4.1. Attachment

Base entity for file attachments throughout the system. Uses JPA inheritance for specialized attachment types.

Package: za.co.idealogic.event.domain
Repository: event-database

Inheritance Strategy: Table per class hierarchy

Subclasses:

  • MembershipAttachment - Membership-specific files (licenses, certificates)

Attributes:

  • File name and path

  • MIME type

  • File size

  • Upload timestamp

Use Cases:

  • Event documents

  • Participant documents (medical certificates, ID copies)

  • Membership certificates

  • Results files

5. Barcode Management

5.1. Barcode

Abstract base entity for various barcode types used in event management. Uses JPA inheritance with a discriminator column.

Package: za.co.idealogic.event.domain
Repository: event-database

Inheritance Strategy: Single table with discriminator

Subclasses:

  • RaceNumberBarcode - Barcodes on race number bibs

  • TagBarcode - Barcodes on timing tags/chips

  • RacePackBarcode - Barcodes on race pack bags (discriminator: "P")

Attributes:

  • Barcode value

  • Barcode type (discriminator)

  • Association to participant/item

Use Cases:

  • Race number assignment and verification

  • Timing tag tracking

  • Race pack collection management

  • Equipment inventory

6. Integration & External Systems

6.1. RegistrationSystem

Represents external registration systems that can integrate with the platform (e.g., RunSignup, Active.com).

Package: za.co.idealogic.event.domain
Repository: event-database

Key Relationships:

  • Referenced by Events

  • Used for import/export configuration

Use Cases:

  • Participant data synchronization

  • Results export to external platforms

  • Cross-platform event registration

6.2. PaymentProcessor

Configuration for payment gateway integrations (e.g., PayFast, Stripe, PayPal).

Package: za.co.idealogic.event.domain
Repository: event-database

Key Relationships:

  • Referenced by Organisation

  • Referenced by Order

Attributes:

  • Processor name and type

  • API credentials (encrypted)

  • Configuration settings

  • Active/inactive status

7. Entity Summary

Entity Primary Purpose Relationships

Organisation

Multi-tenancy root

Users, Events, Memberships

OrgUser

User-organisation membership

Organisation, User, Permissions

OrgPermission

Access control

OrgUser

LinkedPerson

Dependent person management

Users

Country

Geographic reference data

Referenced globally

Discipline

Sport discipline classification

Events, Memberships

CustomList

Configurable lookup lists

CustomListValue

CustomListValue

Lookup list values

CustomList

Attachment

File management (base)

Subclasses

Barcode

Barcode tracking (base)

Subclasses

RegistrationSystem

External system integration

Events

PaymentProcessor

Payment gateway config

Organisation, Orders

8. Related Documentation