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: admin-service

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: admin-service

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: admin-service

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: admin-service

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: admin-service

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: admin-service

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: admin-service

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: admin-service

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.id). On the next event that uses a list with the same metaKey, the stored id is resolved and pre-populated — so riders do not re-enter their club / team / school each event.

Across a seasonal list swap the id is resolved through CustomListValue.derivedFrom, the per-value lineage pointer recorded when the new season’s list is cloned from the previous one. Carry-forward across that boundary is deliberately best-effort: it takes one hop, so a value two generations back, a split, or the unrecorded side of a merge all resolve to nothing, and the rider simply selects again. See Custom Lists: Design and UserMeta Persistence for the full contract, the resolution rule, worked examples, 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: admin-service

Key Attributes:

  • name — human-readable label shown in pickers. Not what is persisted to the Person; see the UserMeta contract under CustomList

  • derivedFrom — optional pointer to one value on a prior generation of this list. Many values may point at the same ancestor. Read by carry-forward across a seasonal list swap

  • 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.id is what the wp_usermeta contract stores (see CustomList above). Cross-generation identity is carried by derivedFrom, not by the name — measured on production, only 8 of 134 values in one season’s school list appeared by name in the next, because the list was re-authored rather than cloned. The pointer points backwards (new value → one old value) because a list may be cloned more than once.

  • 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: admin-service

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: admin-service

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: admin-service

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: admin-service

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