Ubiquitous language
These terms define the shared language for all code, documentation, and conversations in Baseleg. Using the correct term in the right context prevents ambiguity and keeps the codebase aligned with the domain.
When a new term is introduced in code or documentation, update this page.
People context
Person
An individual formally associated with the organisation (e.g. someone registered with the club or enrolled as a student). A Person is the root identity concept — all other types build on it. An individual cannot be a Student or Instructor in Baseleg without first being a Person.
Student
A Person who is receiving instruction or training. Students are associated with training records, lessons, and flight logs. In the UI, student-facing language uses “flights” and “bookings” rather than operational terminology.
Instructor
A Person who is authorised to provide instruction and can be assigned to Bookings and Lessons. An Instructor has authorisations that determine what they can teach.
Staff
A Person who performs operational or administrative functions. Staff may be non-flying. The term covers both office staff and operations personnel.
Admin
A Person with administrative access to Baseleg itself (e.g. managing other People, organisation-wide settings, the permission matrix). Distinct from Staff, which covers day-to-day operational duties rather than system administration.
Type
One of the ways a Person is involved with the organisation: Student, Instructor, Staff, or Admin. A Person can hold more than one Type at once (e.g. an Instructor who is also Staff) — types are additive, not exclusive. Persisted via the people_type reference table and a person_type_assignments join table.
Type vs Role: Type (above) describes organisational involvement and is fully modeled today. Role is meant to be a distinct, separate concept for software permissions — what a Person is allowed to do within Baseleg — decoupled from Type so permissions could eventually be assigned directly to a Person rather than only inherited from their Type. No such decoupled Role system exists yet. As an interim measure,
@baseleg/shared-permissionscomputes permissions directly from a Person’s Types (TYPE_PERMISSIONS,hasPermission) — this is Type-driven permissioning, not a Role system, and should be read as a placeholder for it. Don’t conflate the two terms; existing casual mentions of “role” elsewhere in the docs predate this distinction and haven’t all been reconciled yet.Accepted interim simplification — the retired
super_admintier: an earlier iteration of this permission model (predating the Type taxonomy above) had asuper_admintier aboveadmin, with no equivalent inpeople_type. Rather than reintroduce a fifth Type with no Type-model backing,super_admin’s permission set (configure_permissions,manage_roles, etc.) has been folded intoadmin. This is a deliberate, temporary flattening — not a silent regression — pending the real, Type-decoupled Role system described above, which can reintroduce a distinct top tier without needing a fifth Type. Similarly, that earlier model had no permission tier forinstructor(it didn’t exist as a Type yet);TYPE_PERMISSIONSnow grants instructors booking management and compliance visibility (enough to run lessons) but not fleet or org-wide management — also an interim judgement call, not a carried-over decision.
Aircraft context
Aircraft
An aircraft operated by the organisation that is (or was) available for booking. Aircraft have a registration, type, and operational status.
Registration
The official identifier of an aircraft (e.g. ZK-ABC). Unique within the system. Used as the primary human-readable reference for an aircraft.
Grounded
A state applied to an Aircraft indicating it must not be booked or flown. Grounding requires an explicit reason (maintenance, compliance, administrative). Only authorised personnel can ground or unground an aircraft.
“Grounded” is a domain state, not just a flag. The system enforces it: a Grounded aircraft will be rejected at booking time regardless of other conditions.
Available
The default operational state of an Aircraft — it can be booked and flown subject to other constraints (no conflicts, valid authorisations). Distinct from usageStatus: available (see MeterReading below) — this term describes the administrative/grounded dimension, not the real-time in-use dimension.
MeterReading
A recorded Hobbs or tach value for an Aircraft. Recording a reading updates the Aircraft’s current meter value for that meter type directly; it must not be lower than the previous value. usageStatus (available | in_use) is a separate, real-time operational dimension on Aircraft — orthogonal to the administrative status (available | grounded) — that tracks whether an aircraft is currently checked out, independent of whether it is grounded.
Scheduling context
Booking
A scheduled allocation of an Aircraft (and optionally an Instructor) for a Person over a time range. A Booking is the primary scheduling artefact. It carries the who, what, and when.
A Booking moves through a five-state lifecycle: provisional → confirmed → checked_out →
completed, with cancelled reachable only from provisional or confirmed. In the current
MVP, createBooking produces a confirmed Booking directly — provisional is reserved for a
future self-service/planning flow. checked_out and completed are produced by the Checkout
and Return transactions respectively (see below).
Time range
A start and end time defining the duration of a Booking or other time-bounded event. Conflict detection operates on time ranges.
Conflict
A state where two Bookings attempt to claim the same Aircraft or Instructor over an overlapping time range. The domain rejects conflicting Bookings.
Assignment
The act of attaching an Instructor (or Student) to a Booking. An Instructor assignment is optional; some bookings are solo flights.
Operating hours
The organisation-wide window (open hour, close hour) within which Bookings may be scheduled. A single Operating Hours record applies to the whole organisation in v1 — it is not per-aircraft or per-person.
Flight
The actual operational record of an Aircraft’s use — distinct from a Booking, which represents planned intent. A Flight is created when a Booking is checked out and completed (or marked as a no-flight cancellation) at return. Owned by the Scheduling context; the Training context references it by FlightId rather than holding its own copy. Zero or one Flight exists per Booking.
Checkout
The transaction that turns a confirmed Booking into an active Flight: it revalidates the pilot, instructor, and aircraft; dispatches the aircraft; records start meter readings; and transitions the Booking to checked_out. Distinct from confirmation, which only establishes that a Booking may be planned — checkout is the operational release of the aircraft. See checkoutBooking under Key use cases in scheduling.md.
Return
The transaction that completes an active Flight: it releases the aircraft, records end meter readings, captures whether a defect is being reported (auto-grounding the aircraft if so — no severity triage in this MVP), completes the Flight, and transitions the Booking to completed. The symmetric counterpart to Checkout. See returnBooking under Key use cases in scheduling.md.
Dispatcher
The person who releases an aircraft at checkout — recorded on the Flight as dispatcherPersonId. The return-side counterpart is checkedInByPersonId, the person who checks the aircraft back in at Return. Neither is a formal Type/permission in the system yet (any Person ID may currently be recorded); both are distinct from Instructor, which is a specific assignment on the Booking itself.
Training context
Lesson
A training event — ground or airborne — associated with a Student and typically an Instructor. A Lesson may be linked to a Booking.
Flight
Owned by the Scheduling context (see the Scheduling section above), not Training. Training references the Scheduling-owned Flight by FlightId to link training outcomes — a Lesson’s instructor sign-off, a Student’s flight time record — to the specific operational flight it was conducted on. Training does not hold its own copy of Flight data.
Endorsement
A formal record that an Instructor has certified a Student as competent for a specific operation or rating. Endorsements affect what a Student is authorised to do.
Training progression
The accumulation of Lessons, Flights, and Endorsements that represent a Student’s journey through a training programme.
Compliance context
Currency
A compliance concept meaning “currently valid” for a specific requirement. A Person or Aircraft is current for a requirement when the relevant recency or examination is within its validity period. Examples: flight review currency, medical currency, check ride currency.
The opposite of current is lapsed, not “expired” — prefer “lapsed” in domain language.
Compliance alert
A notification raised when a currency requirement is approaching its validity end date or has already lapsed.
Document expiry
The date after which a certificate, authorisation, or document is no longer valid. Document expiry triggers compliance alerts.
Billing context
Usage event
The raw, unpriced usage fact recorded when a Scheduling Flight completes — hours flown per meter
type (Hobbs and/or tach), written via the UsageEventRecorder port from returnBooking. Not a
Charge Item: it carries no rate, price, or amount — it’s the input a future Billing pass will use
to compute one.
Charge item
A single billable line item representing a fee incurred by a Person. Examples: aircraft hourly rate, instructor time, landing fee. Charge items are the atomic unit of billing.
Invoice draft
An invoice that has been compiled from Charge Items but not yet issued. An Invoice Draft can be edited and recomputed before it is finalised.
Invoice
A finalised, issued billing document sent to a Person. Once issued, an Invoice should not be edited (corrections are handled by credit notes or new invoices).
Notifications context
Notification
A message delivered to a Person via one or more channels (email, SMS, in-app). Notifications are triggered by events raised in other contexts — they do not carry domain logic of their own.
Channel
A delivery mechanism for a Notification. Supported channels: email, SMS, in-app.
Delivery
The act of sending a Notification via a Channel. Delivery outcomes (sent, failed, bounced) may be tracked.
Reporting context
Report
An operational summary computed from data across one or more contexts. Reports are read-only views and do not modify domain state.
Export
A downloadable representation of data (typically CSV or similar). Exports are a special case of Report targeted at data portability.
General / cross-context terms
Organisation
The aviation organisation (flight school or aero club) that Baseleg serves. A single Baseleg instance serves one Organisation in v1. Multitenancy is out of scope.
Use case
A discrete application-layer operation that orchestrates domain logic to fulfil a user intent. Use cases live in packages/application/<context>/. Example: createBooking, groundAircraft.
Port
An interface defined by the application layer that infrastructure implements. Ports keep domain and application code free of infrastructure concerns. Example: BookingRepository is a port; BookingRepositoryD1 is the implementation.
Result
A return type representing either success or a typed domain failure. Preferred over throwing exceptions for expected business rule violations. Implemented in packages/shared/result.