Setup Data Model

Purpose

This page explains how Setup information is stored. It is a module-level view: each epic provides the fields and process rules for its own screens.

Setup owns the institute structure and reusable academic definitions required by operational modules. It does not own a cohort’s dated phase plan, actual course offerings, posting blocks, timetable, attendance, or student evidence.

Ownership map

Tenant
└── Institute
    ├── Departments
    │   └── Department units (optional)
    ├── Facilities and learning sites
    ├── Faculty academic associations
    ├── Institute programmes
    ├── Course catalogue
    ├── Curriculum versions
    │   ├── Stages
    │   ├── Course placements
    │   │   └── Course delivery components
    │   ├── Competencies
    │   ├── Clinical-posting requirements
    │   ├── Assessment definitions
    │   └── Phase progression rules
    ├── Curriculum delivery mappings
    └── Academic calendars and period templates

External regulators, universities, counselling authorities, and separately owned hospitals remain outside the tenant hierarchy. Setup connects them to institute-owned records through typed, effective-dated relationships.

Common record fields

The following fields are used where applicable and are not repeated in every epic:

Field	Purpose
`id`	Stable UUID
`tenant_id`	Enforces tenant isolation
`institute_id`	Identifies the institute that owns the record
`code`	Stable business code inside its owning scope
`status`	Current lifecycle state
`valid_from`, `valid_to`	Business-effective period
`version_no`	Business version
`row_version`	Prevents one editor from overwriting another editor’s change
`source_reference_id`	Notification, regulation, order, or local approval evidence
`created_by`, `created_at`	Creation history
`updated_by`, `updated_at`	Latest draft change

Schema areas

Namespace	Responsibility
`identity`	Sign-in identity
`iam`	Memberships, core and functional roles, capabilities, scope, and access history
`org`	Tenant, institutional hierarchy, external organisations, authority relationships, units, and appointments
`facility`	Campuses, buildings, rooms, affiliated learning sites, and location capabilities
`people`	Faculty profile references and designation history
`academic`	Institute programmes, courses, curricula, calendars, delivery mappings, and faculty academic associations
`setup`	Programme-pack installation, identifier policies, source tracking, comparisons, and readiness results
`reference`	Controlled reference values and external code mappings
`workflow`	Review, approval, publication, and exceptions
`audit`	Immutable business and access history

Identity and access records

Record	Important relationships
`identity.user`	One identity may have memberships in permitted tenants
`iam.tenant_membership`	Connects a user to a tenant without granting working access
`iam.role_definition`	Defines the seven stable core roles
`iam.role_label_override`	Changes a tenant’s display label without changing the role code
`iam.role_grant`	Connects a user and role to an organisation entity scope
`iam.capability_definition`	Defines a single permitted action
`iam.role_capability`	Connects base role capabilities to a role
`iam.functional_role_definition`	Defines work such as Admission Officer or Academic Registrar
`iam.functional_role_grant`	Connects a tenant member to a functional role, scope, target, and validity period
`iam.access_event`	Records access grants, changes, reviews, support use, and revocations

These records are explained fully in Roles and Access.

Identifier policy records

setup.identifier_policy
setup.identifier_policy_version
setup.identifier_policy_component
setup.identifier_sequence_definition
setup.identifier_sequence_counter
student.cohort_identifier_policy
student.student_identifier
audit.identifier_allocation_event

Setup owns the policy, format components, sequence rules, and allocation controls. Student and Cohort Management owns the cohort-policy link and issued student identifier. A published policy version is immutable, and a cohort pins the applicable version before it becomes available to Admissions.

The effective policy is resolved from an applicable institute override and then the tenant fallback. Number templates use supported typed variables; they never contain user-authored executable code.

Organisation records

org.tenant
org.entity
org.entity_version
org.institute_profile
org.external_organisation
org.authority_relationship
org.department_unit_profile
org.unit_person_assignment
org.person_appointment

org.entity provides the stable identity of the tenant, optional governing organisation, institute, department, or department unit. org.entity_version stores the effective-dated name, parent, and LTREE path.

Programmes, people, and facilities do not become LTREE nodes. They connect to the owning institute, department, or unit through separate records.

Facility records

facility.site
facility.node
facility.capability
facility.node_capability
facility.external_site_agreement
facility.unit_location_allocation

facility.node stores the containment tree from campus or site down to a room, laboratory, ward, OPD, or another schedulable location. facility.unit_location_allocation connects a location to a department unit for an effective period without moving that location into the organisation tree.

Facility capability describes what a location can support. Actual bookings and scheduled use belong to Academic Planning and Delivery.

Faculty academic records

people.faculty_profile
people.designation_master
people.faculty_designation_assignment
academic.faculty_institute_placement
academic.faculty_department_association
academic.faculty_unit_association
academic.faculty_academic_assignment

Setup references the verified person and employment identity supplied by the relevant source system. It stores the academic relationships MedCES needs: institute placement, lead and additional departments, unit association, designation, and standing academic assignments.

Head of Department and Unit Head are appointments, not faculty designations. System access is assigned separately through IAM.

Programme packs and institute ownership

A programme pack is an immutable, versioned application asset. It is released and tested with MedCES rather than edited in the user interface.

Pack in application code
  -> installation transaction
  -> institute programme
  -> institute courses
  -> institute curriculum draft

An installed record stores its source pack key, version, item key, and original-value fingerprint. There is no runtime foreign key from an institute programme, course, or curriculum to a shared global curriculum row.

setup.pack_installation
setup.pack_item_origin
setup.pack_comparison
setup.pack_conflict_decision

The installation process is safe to retry and cannot create a second copy of the same pack item in the same installation.

Programme and course records

academic.institute_programme
academic.programme_authority_relationship
academic.programme_intake_approval
academic.institute_course
academic.course_department
academic.course_classification

An institute programme represents a programme the institute runs, such as MBBS. A course belongs to the institute, has one lead department, and may have several contributing departments.

A course is not tied to one curriculum version. The same institute course can be placed differently in successor curricula.

Curriculum records

academic.curriculum
academic.curriculum_version
academic.curriculum_stage
academic.curriculum_course_placement
academic.competency
academic.course_competency_link
academic.competency_completion_rule
academic.logbook_requirement_definition
academic.logbook_requirement_competency
academic.competency_verifier_designation
academic.competency_certifier_designation
academic.clinical_posting_requirement
academic.posting_course_link
academic.assessment_definition
academic.assessment_course_link
academic.assessment_outcome_contract
academic.curriculum_phase_transition
academic.progression_condition_group
academic.progression_condition

Competency completion rules distinguish Teaching Exposure, Assessment, Faculty Observation, Repeated Performance, Logbook Evidence, and Combined evidence. A rule states whether certification is required, how many successful performances are needed, which context may verify an entry, and which faculty designations may certify.

Named faculty do not belong to the curriculum. Competency and Logbook later resolves the actual reviewer from Faculty role, designation, department or unit association, academic assignment, learner scope, and effective dates.

Attendance at a conducted session may provide Teaching Exposure when the competency was actually covered. It never creates competency certification by itself.

Assessment definitions

An assessment definition belongs to one curriculum version and one phase. It establishes the stable academic record that later examination occurrences and student outcomes use.

Curriculum version
└── Phase I
    └── First Professional MBBS assessment definition
        ├── linked curriculum courses or subjects
        └── final outcome contract

The definition stores identity, phase, type, authority, academic coverage, permitted outcome values, finality, and whether progression may consume the overall outcome. It does not store an examination date, student mark, eligibility decision, attempt, or result.

Changing a published assessment definition or outcome contract requires a successor curriculum version.

Phase progression definitions

Progression is stored as a transition from one curriculum phase to another.

academic.curriculum_phase_transition
└── root academic.progression_condition_group
    ├── typed academic.progression_condition
    └── nested AND or OR group

The common condition stores its category, place in the logical tree, comparator, required value, missing-data behaviour, and source. Category-specific extension records store the fields for assessment, course, competency, posting, logbook, longitudinal, duration, decision, or blocker conditions.

Progression rules have no separate business version. They are immutable parts of the published curriculum version.

Courses and clinical postings are independent

A curriculum version contains course placements and clinical-posting requirements as sibling records:

Curriculum version
├── Course placements
└── Clinical-posting requirements

academic.posting_course_link provides an optional many-to-many relationship. It can explain that a Medicine posting supports one or more courses, but the posting does not belong to a course and the course does not own the posting.

This separation supports the two later delivery flows:

Course placement
  -> course delivery components
      -> cohort course offering
          -> course sessions
               <-> timetable allocations

Clinical-posting requirement
  -> delivery mapping
  -> cohort posting plan
  -> dated posting blocks

The course placement, its delivery components, and the clinical-posting requirement belong to Setup. The dated cohort records belong to Academic Planning and Delivery.

Curriculum delivery records

academic.course_delivery_mapping
academic.posting_delivery_mapping
academic.delivery_site_eligibility
academic.delivery_unit_eligibility
academic.facility_requirement
academic.delivery_assignment_requirement
academic.delivery_capacity_rule

Delivery mappings define which departments, units, sites, and capabilities are eligible to deliver a curriculum requirement. They may include capacity and supervisor-assignment requirements.

They do not choose actual dates, learner groups, rooms, units, or faculty. Those choices are made when the institute creates a phase plan, course offering, and schedule for a cohort. The Departmental Teaching Schedule is a workspace inside the offering rather than a compulsory record that must be completed before scheduling begins.

Academic calendar records

academic.calendar
academic.calendar_period
academic.working_day_rule
academic.holiday
academic.period_template
academic.calendar_exception

Setup defines reusable academic years, working-day rules, holidays, and teaching-period templates. A cohort’s actual stage dates, course dates, posting blocks, and weekly timetable belong to Academic Planning and Delivery.

Readiness records

setup.readiness_definition
setup.readiness_evaluation
setup.readiness_result
setup.readiness_blocker
setup.readiness_assignment

Readiness is calculated from published Setup records. A user can resolve the underlying blocker, but cannot manually change a failed rule to Passed.

Record lifecycles

Versioned academic and institutional records normally use:

Draft -> Under Review -> Approved -> Published -> Superseded -> Archived

Access grants normally use:

Pending -> Active -> Suspended, Expired, or Revoked

Effective-dated relationships may be Draft, Active, or Ended. The owning epic defines which lifecycle applies.

Published curriculum versions are read-only. A change creates a successor version. Programme-pack updates never silently change a published institute curriculum, and later operational records remain connected to the exact version selected for them.

Process-layer responsibilities

The Setup process layer must:

enforce tenant and institute ownership;
validate institutional and facility hierarchies without mixing them;
keep external authorities outside the access-inheritable LTREE;
install a programme pack in one repeatable transaction;
validate stages, course placements, course delivery components, competencies, postings, and progression rules;
validate competency completion methods, logbook requirements, evidence relationships, designation eligibility, and certification authority;
validate assessment identity, authority, course coverage, and outcome contracts;
validate phase transitions, typed condition categories, thresholds, and explicit AND/OR groups;
understand supported requirement types such as duration, course completion, posting, competency, logbook, decision, and sign-off;
reject a pack requirement whose behaviour the running application cannot interpret;
preserve independent course-placement and clinical-posting records;
resolve, validate, version, and safely preview identifier policies;
pin the applicable student-number policy to a cohort and allocate unique values atomically;
keep published versions immutable;
require a successor curriculum version for any published assessment or progression-definition change;
calculate impact before structural closure, curriculum publication, or pack update;
recalculate only the readiness checks affected by a change;
record source, approval, version, and audit history for every material change.

Module boundaries

Setup supplies definitions to later modules. It does not create:

planned cohorts or cohort membership;
admission cycles, seat matrices, rounds, allotments, or candidate cases;
dated phase plans or learner groups;
cohort course offerings, departmental teaching schedules, or course sessions;
clinical-posting plans or posting blocks;
timetabled sessions or room bookings;
attendance, assessment results, competency evidence, or logbook entries.