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

Organisation-scoped container of configurable dropdown / lookup values used by Event to extend EventParticipant with up to three additional fields (e.g. Club, Team, School).

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

Key Attributes:

  • name — unique internal name (e.g. "WP Clubs 2026")

  • displayName — label shown on-screen and in reports

  • displayCode — Y/N flag for whether the CLV’s short code is shown in pickers

  • metaKey — key into wp_usermeta / future PersonMeta. Drives the persistence contract that carries a rider’s selection across events (see below).

Key Relationships:

  • One-to-many with CustomListValue

  • Many-to-one with Organisation (list is organisation-scoped)

  • Referenced by Event via custom_list_{1,2,3}_id — configures which list backs each of the event’s up to three extra slots

  • Referenced indirectly by wp_usermeta — a UserMeta row whose meta_key matches a CustomList.metaKey stores that person’s current value for the associated concept

UserMeta persistence contract:

A CustomListValue selected on an EventParticipant is also upserted to wp_usermeta as (user_id, meta_key = CustomList.metaKey, meta_value = CustomListValue.name). On the next event that uses a list with the same metaKey, the value is looked up by name and pre-populated — so riders do not re-enter their club / team / school each event, and the value survives seasonal list swaps (a new CustomList PK per season is fine as long as the value name is unchanged). See Custom Lists: Design and UserMeta Persistence for the full contract, worked example, and unmatched-lookup behaviour.

Use Cases:

  • Club affiliation per event

  • Team affiliation per event (overlay on top of club)

  • School affiliation for youth leagues

  • Custom event categories

  • Any organisation-specific classification that should persist on the rider’s profile

3.4. CustomListValue

An individual value within a CustomList — e.g. a single club, team, or school.

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

Key Attributes:

  • name — human-readable label; also the value stored in wp_usermeta.meta_value when a selection is persisted to the Person

  • code — optional short code, shown in pickers when the parent CustomList.displayCode is Y

Key Relationships:

  • Many-to-one with CustomList

  • Referenced by EventParticipant.custom_{1,2,3}_id for the rider’s per-event selection

Design notes:

  • CustomListValue.name is the authoritative identity across list PK changes. The wp_usermeta contract (see CustomList above) stores the name, not the PK, so a new CustomList per season can replace its parent list without breaking the carry-forward.

  • CustomListValue is not directly organisation-secured; it inherits scope from its parent 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