# 4. Account Linking

User Type: **Super Administrator**
Source: *Mi Digital Academy - Education CRM Features Document*

---

## 4. Account Linking

### 4.1 Link Parent Accounts to Multiple Children's Accounts
**What it does:** Establishes the parent↔child relationship so a parent account can be associated with one or more minor student accounts. The link enables the parent's visibility and consent role over their children's accounts (progress, communications, and — for minors — the consent relationship), and it is the structural basis for the parental-consent and family-visibility features.

**Sub-features:**
- Link a parent to a child account (one parent to many children; a child to the appropriate guardian(s))
- Link creation at registration (guardian provided during the minor's signup) or afterward (admin-initiated)
- Guardian identity verification before a link is established (see Authentication & Access)
- Consent relationship: the link carries the parental-consent state for the minor
- Parent visibility: the parent sees their linked children's accounts and (per policy) progress/communications
- Unlink with reason (e.g., corrected relationship, guardian change)
- Audit logging of link creation and removal

**Super Administrator User Journey:**
1. A minor registers and provides a guardian's email. The registration flow creates the parent account (or matches an existing one) and proposes the parent↔child link, pending guardian verification.
2. The guardian verifies their identity (OTP) and confirms the relationship; the link is established and the parental consent is captured against the child's account.
3. Super Admin, reviewing a family with three children, opens the parent's record and sees all three linked child accounts, each with its consent state.
4. A parent reports a second child was registered under a different (typo) parent email. Super Admin opens both parent records, verifies the correct guardian's identity, and links the second child to the correct parent account.
5. The duplicate/typo parent account is then handled (merged or deactivated per policy), and the child's consent relationship is confirmed against the correct guardian.
6. A guardian changes (custody update): the parent requests a guardian change. Super Admin verifies the new guardian's identity and authority, updates the link, and re-captures consent from the new guardian per policy.
7. Reviews the link audit entries: each link creation, change, and removal shows the guardian verification method and the acting admin.
8. The parent's visibility (progress, communications) reflects the current links; unlinking removes the visibility immediately.

**Rules & Edge Cases:**
- A link is not established without guardian identity verification; an unverified link is not accepted.
- One parent can link to multiple children; a child links to the appropriate guardian(s) per the relationship.
- The link carries the consent relationship: the minor's consent state is tied to the verified guardian.
- Unlinking requires a reason and, for guardian changes, verification of the new guardian; it is audit-logged.
- Parent visibility is scoped to linked children only; a parent never sees unrelated accounts.
- All link changes are audit-logged with the verification method and the acting admin.

### 4.2 Link Student Accounts to Institute Accounts
**What it does:** Associates a student account with an institute account, establishing the student's enrollment context: which institute the student belongs to, which license seat (if any) they occupy, and the institute's visibility over the student (per the institute's permissions). The link is the structural basis for institute-level management, seat allocation, and institute-scoped data.

**Sub-features:**
- Link a student to an institute (at creation, bulk upload, or afterward)
- One student to one primary institute (with a clear primary-institute rule)
- Seat association: the link can carry the student's license seat under the institute
- Institute visibility: the institute sees its linked students per its permissions
- Re-linking: move a student to a different institute (with seat handling)
- Unlink: remove a student from an institute (with seat release)
- Audit logging of link creation, change, and removal

**Super Administrator User Journey:**
1. An institute bulk-uploads 200 students. Each created account is linked to the institute automatically, and the institute's admin sees the 200 students in its directory.
2. A student transfers between institutes. The new institute requests the transfer. Super Admin opens the student's record, reviews the current institute link and seat, and initiates the re-link to the new institute.
3. The re-link handles the seat: the student's seat is released under the old institute's license and allocated under the new institute's license (subject to the new institute's available seats).
4. The student's data context moves: the old institute no longer sees the student; the new institute does. The student's own progress is preserved on the account.
5. A student leaves an institute (graduates, withdraws). Super Admin unlinks the student from the institute; the seat is released back to the institute's license pool.
6. The student account remains (it is the student's own account); only the institute association is removed.
7. Reviews the link audit entries: each link, re-link, and unlink shows the institutes involved, the seat handling, and the acting admin.
8. The institute's seat count reflects the current links: allocated seats = linked students with seats, available = license total minus allocated.

**Rules & Edge Cases:**
- A student has one primary institute link; re-linking is a move (old released, new allocated), not a duplicate.
- Re-linking and unlinking handle the seat explicitly: a seat is released before or as part of the move, so no seat is double-allocated.
- The student's own account and progress survive institute changes; only the association changes.
- Institute visibility is scoped to linked students; an institute never sees unlinked or other-institute students.
- A re-link to an institute with no available seats is blocked (the seat must be available first).
- All link changes are audit-logged with the institutes, seat handling, and the acting admin.

### 4.3 Link Integrity and Validation
**What it does:** Keeps account links correct and consistent: validates links at creation and change (identity verification, relationship correctness, seat availability), detects and resolves anomalies (duplicate links, orphaned links, broken references), and maintains referential integrity so a link always points to valid, active accounts.

**Sub-features:**
- Validation at link creation: both accounts exist, identity/relationship verified, constraints satisfied (one primary institute, seat available)
- Anomaly detection: duplicate parent↔child links, student linked to two institutes, links to deactivated accounts
- Orphaned-link handling: a link whose target account was deactivated/deleted is flagged and resolved
- Referential integrity: links always resolve to valid accounts; broken references are surfaced, not silently followed
- Link consistency report: counts and anomalies across all link types
- Audit logging of validation outcomes and anomaly resolutions

**Super Administrator User Journey:**
1. Super Admin runs the link consistency report: it shows total links by type and highlights anomalies — 3 duplicate parent↔child links, 1 student linked to two institutes, 2 links pointing to deactivated accounts.
2. Opens the duplicate parent↔child links: a child is linked to two parent accounts (the typo-email case). Verifies the correct guardian, keeps the correct link, and removes the duplicate with a reason.
3. Opens the student linked to two institutes: a re-link that did not release the old link (an edge case). Confirms the correct current institute, releases the stale link, and confirms the seat state is correct (one seat allocated, not two).
4. Opens the links to deactivated accounts: the target accounts were deactivated but the links remained. Resolves each: where the relationship is historical, the link is marked resolved; where it should be active, the account is reviewed for re-activation.
5. Re-runs the consistency report: all anomalies are cleared, and the report shows zero open items.
6. Sets a recurring run of the consistency report so new anomalies are caught promptly.
7. Reviews the resolution audit entries: each anomaly resolution shows the link, the action, and the acting admin.
8. The integrity checks run automatically at link creation/change, so most anomalies are prevented at the source; the report catches the residual.

**Rules & Edge Cases:**
- Validation at creation prevents most anomalies: a second primary-institute link or a link without verification is blocked at the source.
- Anomalies that do occur (edge cases, historical data) are surfaced in the consistency report, not hidden.
- Orphaned links (target deactivated/deleted) are flagged and resolved; they are never silently followed.
- Seat integrity is part of link integrity: a student never holds two seats, and a released seat returns to the pool.
- Anomaly resolutions are deliberate, reason-recorded, and audit-logged.
- The consistency report is recurring, so link health is continuously verified, not only on demand.