Tenant and Institute Setup
Epic summary
The Tenant and Institute Setup workspace establishes who is operating MedCES. A tenant can represent one independent institute or a governance organisation responsible for several institutes.
This epic replaces the legacy College Master with explicit tenant, governance, and institute identities. It does not yet create departments, institute programmes, authority relationships, or facilities.
Before you start
A Platform Admin must first create the tenant shell and bootstrap Tenant Admin grant. Standard institute types, geographical values, and timezones are supplied by the platform. For a multi-institute tenant, the legal or governing organisation should also be identified.
Actors and access
| Access source | Access in this epic |
|---|---|
| Platform Admin | Creates the tenant shell and bootstrap Tenant Admin grant |
| Tenant Admin or Governance Registrar role | Prepares governing-organisation and institute profiles within scope |
| Institute member with Institute Activation Approver role | Confirms institute details and approves activation |
| Auditor role | Reads versions, identifiers, evidence, and approval history |
Screen structure and data captured
The workspace contains Tenant Profile, Governance Details, Institutes, Statutory Identity, Addresses and Contacts, Branding and Localisation, and Activation History.
| Field | Required | Meaning and validation |
|---|---|---|
| Tenant name and code | Yes | Stable MedCES customer identity; code unique platform-wide |
| Operating model | Yes | Single institute or multi-institute governance |
| Legal entity name | Yes | Name supported by legal evidence |
| Governing organisation | Conditional | Required for the multi-institute model |
| Institute name and code | Yes | Unique inside the tenant |
| Institute type | Yes | Medical college, health-sciences university institute, or another governed type |
| Statutory identifiers | Conditional | Institution code, registration, university code, or other recognised identifier |
| Primary address | Yes | Structured address and jurisdiction |
| Official contacts | Yes | Administrative and escalation contacts |
| Timezone and locale | Yes | Used for effective dates, deadlines, and display |
| Effective dates | Yes | Operating validity |
| Status | Yes | Draft, Under Review, Active, Suspended, or Closed |
Use case 1: Create a tenant and operating model
As a Platform Admin
I want to create the tenant shell and select its operating model
So that all later records are isolated and structured correctly.
Acceptance criteria
- The tenant receives a unique immutable identifier and code.
- The operating model identifies whether governance entities are required.
- The bootstrap Tenant Admin is granted at the tenant entity through Users and Access Assignment.
- Creation does not make the tenant operationally ready.
- Tenant isolation is established before any tenant-owned record is accepted.
Use case 2: Register an institute
As a tenant member with Governance Registrar role
I want to register an institute with its verified legal and operating details
So that academic and administrative setup has an accountable owner.
Acceptance criteria
- The registrar records the institute name, code, type, address, contacts, identifiers, and effective dates.
- Duplicate identifiers within the platform are flagged for review.
- A multi-institute tenant assigns the institute to its governing organisation.
- Statutory evidence is attached where the configured institute type requires it.
- The institute remains Draft until approved and activated.
Negative cases and alternate flows
- Missing legal evidence: Allow draft save but block activation.
- Code collision: Reject the duplicate within the tenant.
- Future opening: Permit approval with a future activation date.
Use case 3: Amend or suspend an institute
As an institute member with the required approval responsibility
I want to submit a governed change to institute details or status
So that current operations and historical records remain accurate.
Acceptance criteria
- Material identity changes create a new version with source evidence.
- Suspension requires reason, effective time, scope, and approval.
- Impact analysis identifies active institute programmes, cohorts, cycles, integrations, and users.
- Suspension blocks new operational records after its effective time but preserves read access and history as permitted.
- Closure cannot physically delete the institute.
Business rules
- Every tenant has exactly one tenant-root entity.
- Institute codes are unique within a tenant and stable after activation.
- A tenant may contain one or many institutes.
- Timezone changes never reinterpret timestamps already recorded.
- Legal identity and display branding are stored separately.
- An institute cannot activate until an authorised activation approver is assigned. A Dean or Principal appointment may identify the expected approver, but the appointment does not grant access by itself.
Technical design
Conceptual schema
| Record | Important fields |
|---|---|
org.tenant | id, code, name, operating_model, timezone, locale, status |
org.entity | stable identity for tenant root, governing organisation, and institute nodes |
org.entity_version | entity, current name, parent, LTREE path, validity, source, approval |
org.institute_profile | entity_id, institute_type_id, legal_name, display_name, valid_from, valid_to, version_no |
org.entity_identifier | entity_id, scheme, value, issuer, valid_from, valid_to |
org.entity_address | entity_id, structured geography, address_type, validity |
org.entity_contact | entity_id, contact_type, value, is_primary, validity |
Process-layer responsibilities
- Create the tenant root and enforce tenant isolation in one transaction.
- Validate operating-model parent rules and institute-code uniqueness.
- Validate required fields and evidence by institute type and jurisdiction.
- Calculate the impact of suspension, closure, identity, timezone, or jurisdiction changes.
- Trigger readiness evaluation for the tenant and descendants after publication.
Success outcome
The tenant and each institute have a verified, effective-dated identity that can safely own hierarchy, academic, facility, and operational records.