Applicant Document: Governed Admission File Record

Before You Start (Prerequisites)

• Create the Student Applicant record first.
• Configure required Applicant Document Type records for your organization/school scope.
• Use governed upload/classification flows only; do not use ad-hoc direct file insert patterns.

Applicant Document is the semantic owner of admissions files. It is not a generic attachment row and it is not optional metadata.

Authoritative Admissions Boundary

Applicant Document is the canonical container between applicant lifecycle and file governance:

• Inquiry -> Student Applicant -> Applicant Document -> promotion copy to Student
• admissions files live on Applicant Document
• direct admissions file attachment to Student Applicant or Student is forbidden
• only Student Applicant.applicant_image remains a specific identity-image exception

Non-Negotiable Invariants

1. One logical document slot per applicant/type (student_applicant, document_type).
2. student_applicant and document_type are immutable after insert.
3. Review truth lives on this doctype (review_status, reviewer metadata, review notes).
4. is_promotable is valid only when review_status = Approved.
5. Applicant-side evidence is retained as admissions history; promotion creates student-side copies.
6. Portal users can upload/view only; they cannot review, retype, or delete records.

Capability Boundaries

Actor	Allowed	Forbidden
Admissions Applicant (portal)	list types, list documents, upload document file	approve/reject, edit review fields, change document_type, delete rows
Admission Officer / Admission Manager	create/manage rows, operational follow-up	reviewer-only decisions unless also reviewer role
Academic Admin / System Manager	reviewer decisions and promotion flags	bypassing immutable field rules

Operational Guardrails

Do

• Use one canonical row per (student_applicant, document_type) and treat new uploads as newer evidence for that slot.

• Use reviewer roles (Academic Admin or System Manager) for review_status and is_promotable decisions.

Don't

• Attach admissions evidence directly to Student Applicant or Student.

• Re-link applicant-side File rows to student records during promotion.

Lifecycle and Linked Documents

Applicant Document Authoritative Flow

1

Create Slot

Create or resolve a single Applicant Document for (student_applicant, document_type).

2

Upload Evidence

Upload files through governed admissions endpoints so files attach to Applicant Document only.

3

Review

Reviewer roles set review_status, reviewer metadata, and optional review notes.

4

Set Promotion Semantics

Mark is_promotable only after approval and set promotion_target where applicable.

5

Promote Applicant

Promotion copies approved applicant evidence into new Student files with lineage; applicant-side files remain unchanged.

Promotion Boundary (Applicant -> Student)

Promotion must keep admissions and student ownership separated:

• source files remain attached to Applicant Document
• student receives new file records (copy), never re-linked applicant records
• only approved applicant documents are considered
• non-promotable or rejected evidence stays applicant-side only

This preserves auditability, GDPR-local erasure semantics, and operational traceability.

Validation and Gating Checkpoints

1. Applicant Document.validate

• permission guard (UPLOAD_ROLES + reviewer-only field guard)
• applicant terminal-state lock (Rejected, Promoted)
• immutable anchor guard (student_applicant, document_type)
• uniqueness guard on (student_applicant, document_type)
• review metadata stamping when status changes
• promotion flag guard (is_promotable requires approved + reviewer role)

2. Applicant Document.before_delete

• blocks deletion when files exist
• allows override only for System Manager

3. Portal upload flow (upload_applicant_document)

• applicant identity/scope checks
• document type scope/activity checks
• governed classification with primary_subject_type = Student Applicant
• file attachment target forced to Applicant Document

4. Student Applicant readiness (has_required_documents)

• required doc types must exist and be approved
• approval readiness fails for missing/unapproved required slots

Reporting

• No dedicated Script/Query Report currently declares Applicant Document as ref_doctype.

Related Docs

Related Admissions Evidence Docs

Student Applicant: The Admission Record of Truth

->

Admission

Manage applicant lifecycle from invitation to promotion, with readiness checks, governed files, policy acknowledgements, and portal access.

Applicant Document Type: Authoritative Admissions Evidence Catalog

->

Admission

Define canonical admissions document types and codes that drive portal options, readiness checks, and deterministic file-classification slots.

Applicant Health Profile: Health Disclosure and Clearance

->

Admission

Capture health details, control family/staff editing by applicant status, and feed readiness for admissions decisions.

Applicant Interview: Structured Interview Evidence

->

Admission

Record interview evidence, participants, and outcomes with audit trail comments pushed to the Student Applicant timeline.

Technical Notes (IT)

Latest Technical Snapshot (2026-02-22)

• DocType schema file: ifitwala_ed/admission/doctype/applicant_document/applicant_document.json

• Controller file: ifitwala_ed/admission/doctype/applicant_document/applicant_document.py

• Required fields (reqd=1):

  • student_applicant (Link -> Student Applicant)
  • document_type (Link -> Applicant Document Type)

• Lifecycle hooks in controller: validate, before_delete

• Operational/public methods: get_file_routing_context

• DocType: Applicant Document (ifitwala_ed/admission/doctype/applicant_document/)

• Autoname: hash

• Core field contract:

  • document_label optional override label
  • review_status options: Pending, Approved, Rejected, Superseded (default Pending)
  • is_promotable default 0
  • promotion_target options: Student, Administrative Record

• Routing context contract (get_file_routing_context):

  • root_folder = Home/Admissions
  • subfolder = Applicant/<student_applicant>/Documents/<doc_type_code>
  • file_category = Admissions Applicant Document
  • logical_key = <doc_type_code>

• Portal/API surfaces:

  • governed endpoint: ifitwala_ed/admission/admissions_portal.py::upload_applicant_document
  • portal list endpoints: ifitwala_ed/api/admissions_portal.py::list_applicant_documents, list_applicant_document_types
  • portal upload wrapper: ifitwala_ed/api/admissions_portal.py::upload_applicant_document
  • SPA page: ifitwala_ed/ui-spa/src/pages/admissions/ApplicantDocuments.vue

• Runtime role guards (controller):

  • upload/manage roles: admissions roles + Academic Admin + System Manager + Admissions Applicant
  • reviewer roles: Academic Admin, System Manager
  • review-field mutation is blocked for non-reviewer roles

• Readiness and promotion integration:

  • required-document readiness check in Student Applicant.has_required_documents()
  • promotion copy flow uses approved applicant docs in Student Applicant._copy_promotable_documents_to_student()

Permission Matrix (DocType Permissions)

Role	Read	Write	Create	Delete	Notes
Admission Manager	Yes	Yes	Yes	Yes	Runtime delete guard applies when files exist
Admission Officer	Yes	Yes	Yes	Yes	Runtime reviewer guard still applies
Academic Admin	Yes	Yes	Yes	Yes	Reviewer authority
System Manager	Yes	Yes	Yes	Yes	Reviewer authority + delete override with attached files
Curriculum Coordinator	Yes	Yes	Yes	Yes	Runtime guard limits review semantics
Admissions Applicant	Yes	Yes	Yes	No	Portal-scoped behavior still enforced server-side
Academic Assistant	Yes	Yes	Yes	Yes	Runtime guard limits review semantics

Runtime controller rules are authoritative over DocType matrix permissions.