Data Model
Purpose
This document defines the logical data model for Chilarai.
It captures:
- Core business aggregates
- Aggregate ownership boundaries
- Cross-domain relationships
- Lifecycle models
- Key business constraints
- Persistence guidelines
This document is intentionally maintained at an architectural level.
Detailed database design, database schemas, repository implementations, and migrations are implementation concerns and are not documented here.
Data Modeling Principles
Aggregate Ownership
Every aggregate has a single owner.
Only the owning module may modify aggregate state.
Other modules may:
- Reference identifiers
- Query through services
- Consume domain events
Other modules must never directly modify another module's aggregate.
References Instead of Ownership
Cross-domain relationships should be modeled using identifiers.
Example:
Student Enrollment references Academic Year, Class and Section.
Student Enrollment does not own Academic entities.
Single Database Strategy
Chilarai uses a single PostgreSQL database.
Modules share the same physical database but retain ownership boundaries.
Transaction Boundaries
Transactions should remain inside aggregate boundaries whenever possible.
Cross-aggregate operations should use application orchestration or domain events.
Event Driven Coordination
Examples:
- Admission Converted -> Create Student -> Create Enrollment
- Enrollment Created -> Generate Fees
- Payment Received -> Send Notification
Audit Strategy
All entities include:
- CreatedAt
- CreatedBy
- UpdatedAt
- UpdatedBy
Archival Strategy
Business records are archived rather than deleted.
Aggregate Overview
School Aggregate
Entities:
- School
- School Address
- School Contact
- School Settings
- School Branding
Rules:
- School code must be unique.
- School owns operational settings and branding.
- Most business entities ultimately belong to a School.
Identity Aggregate
Entities:
- User
- School Membership
- Role
- Permission
- Scope
- Role Permission
Rules:
- Authentication is managed by Keycloak.
- Authorization is managed by Chilarai.
- School Membership is the authorization boundary.
- Users may belong to multiple Schools.
- Roles grant Permission + Scope combinations.
Academic Aggregate
Entities:
- Academic Year
- Class
- Section
- Subject
- Class Subject
- Teacher Assignments
Rules:
- Only one Academic Year may be Active.
- Sections are Academic Year specific.
- Classes and Subjects are School master data.
Student Aggregate
Entities:
- Student
- Student Contact
- Parent Relationship
- Student Enrollment
Core Principle:
Student = Permanent Identity
Student Enrollment = Academic Participation
Student Lifecycle
Enrollment Lifecycle
Admission Aggregate
Entities:
- Admission
- Admission Documents
Rules:
- Admissions are independent of Students.
- Only approved Admissions may be converted.
- Conversion creates Student and Enrollment.
Staff Aggregate
Entities:
- Staff
Rules:
- Staff extends User with employment information.
- Teacher is a role, not a separate entity.
Attendance Aggregate
Entities:
- Attendance
- Attendance Event
Rules:
- Attendance references Student Enrollment.
Assessment Aggregate
Entities:
- Assessment
- Assessment Component
- Assessment Result
Rules:
- Assessment Results reference Enrollment.
Fees Aggregate
Entities:
- Fee Structure
- Fee Component
- Student Fee
- Fee Adjustment
- Fee Charge
- Payment
Rules:
- One active Fee Structure per Academic Year and Class.
Storage Aggregate
Entities:
- Document Metadata
Rules:
- Files stored in MinIO.
- Metadata stored in PostgreSQL.
Cross Domain Relationships
Ownership Matrix
| Aggregate | Owner Module |
|---|---|
| School | School |
| User | Identity |
| School Membership | Identity |
| Student | Student |
| Student Enrollment | Student |
| Admission | Admission |
| Staff | Staff |
| Attendance | Attendance |
| Assessment | Assessment |
| Fees | Fees |
| Storage | Storage |
Key Constraints
- One Membership per User per School
- One Active Academic Year per School
- One Enrollment per Student per Academic Year
- Only Approved Admissions may be Converted
- One Active Fee Structure per Academic Year and Class
Summary
- School is the primary business boundary.
- School Membership is the authorization boundary.
- Student is a permanent identity.
- Student Enrollment is the academic participation boundary.
- Admissions are independent from Students.
- Attendance, Assessment and Fees reference Enrollment.
- Aggregate ownership is explicit.
- PostgreSQL stores business data.
- MinIO stores binary content.