# Madrasah OS ### AI Project Constitution > An internal ERP platform for managing educational institutions. # Vision Madrasah Operating System (MOS) is an internal ERP platform designed to become the **Single Source of Truth** for all administrative, academic, financial, and operational activities within a Madrasah. The primary objective is to replace fragmented Excel-based workflows with a centralized, integrated, secure, and auditable platform. MOS is **not** an LMS, Payroll system, or public SaaS. It is built exclusively for internal institutional operations and is intended to evolve incrementally through modular expansion. --- # Business Philosophy Every design and implementation decision must follow these principles: - **Entity-Centric** — Business entities are permanent and never recreated. - **History-Preserving** — Business history must never be overwritten. - **Organization-Driven** — Organizations manage identities, memberships, and permissions. - **Workflow-Oriented** — Features exist to support business processes, not the other way around. - **Single Source of Truth** — Every piece of business data has one authoritative source. - **MVP First** — Build the smallest solution that delivers measurable business value. --- # Core Domains - Student Lifecycle - Teacher Management - Academic Structure - Student Billing - Finance - Administration --- # Foundation Capabilities Every module shares these platform capabilities: - Identity & Access Management - Organization Management - User Provisioning - Role & Permission - Master Data - Dashboard - Notification Center - File Management - Immutable Audit Trail - Data Exchange Framework --- # Identity & Organization Model Authentication is independent from business entities. ``` User │ Membership │ Organization │ Business Entity ``` Definitions: - **User** → Login identity. - **Membership** → Relationship between User and Organization. - **Business Entity** → Student, Teacher, Staff, Guardian, etc. Rules: - Users are not automatically Teachers or Staff. - Business entities may exist without login accounts. - One User may belong to multiple organizational units. - Roles are assigned by the organization. - Users never assign their own permissions. --- # User Provisioning The platform follows an invitation-based onboarding model. Default workflow: 1. Administrator creates an invitation. 2. Invitation defines Organization, Unit, and initial Role. 3. User accepts invitation. 4. User completes profile and credentials. 5. Membership becomes active. Self-registration is intentionally excluded from the MVP. --- # Authorization Model MOS uses a hybrid authorization model. ``` User ↓ Membership ↓ Role ↓ Permissions ↓ Policies (Attributes) ↓ Accessible Data ``` Where: - **Role** defines who the user is. - **Permission** defines what actions are allowed. - **Policy** defines which data those actions apply to. Policies may include: - Organization - Unit - Department - Assigned Class - Academic Year - Data Ownership Avoid role explosion by expanding policies instead of creating new roles. --- # Data Model Principles Data is categorized into four layers. ## Master Data Permanent business entities. Examples: - Student - Teacher - User - Subject - Department - Chart of Accounts --- ## Reference Data Configurable operational references. Examples: - Academic Year - Semester - Grade - Class - Billing Template --- ## Operational Data Historical activities. Examples: - Enrollment - Class Membership - Teacher Assignment - Student Status History - Certificate Distribution --- ## Transaction Data Business transactions. Examples: - Invoice - Payment - Income - Expense - Budget - Transfer Historical data is append-only. Never overwrite previous records. --- # Academic Year Philosophy Academic Year is contextual. It is **not** the backbone of the system. Permanent entities remain unchanged throughout their lifecycle. Instead of recreating data every year, create new historical records. Examples: - Enrollment - Teacher Assignment - Class Membership - Billing Plan Reports are filtered by Academic Year instead of duplicating data. --- # Audit Trail Every significant business action records: - WHO - WHEN - WHAT - FROM - TO - WHY - HOW Audit logs are immutable, append-only, searchable, and permission protected. Every import, financial transaction, permission change, and business mutation must generate an Audit Trail entry. --- # Dashboard Philosophy Dashboards are workflow-oriented, not role-oriented. The dashboard is composed of reusable widgets. Widget visibility depends on permissions and policies rather than hardcoded roles. Dashboard priorities: - Alerts - Today's Work - Key Metrics - Notifications - Quick Actions Business users focus on operational activities. Platform administrators focus on system management. --- # Workspace Model The platform provides two workspaces. ## Business Workspace Operational modules. - Students - Teachers - Billing - Finance - Administration - Events ## Administration Workspace Platform management. - Organizations - Users - Memberships - Invitations - Roles - Permissions - Audit Trail - System Settings Workspace visibility is permission-based. --- # Data Exchange Framework Import and Export are shared platform capabilities. ## Import Purpose: - Excel migration - Bulk create - Bulk update Requirements: - Downloadable templates - Validation - Duplicate detection - Preview - Error reporting - Import history - Audit Trail - Background processing ## Export Purpose: - Reporting - Backup - Offline access - Spreadsheet analysis Requirements: - Excel & CSV - Respect filters - Permission-aware - Export history for sensitive modules Business validation rules must be identical between manual input and imported data. --- # MVP Modules ## Student Management - Enrollment - Student Profile - Guardian - Academic Status - Promotion - Graduation - Alumni ## Teacher Management - Teacher Profile - Assignment - Attendance - Performance - Employment Status ## Student Billing - Billing Plans - Invoice Generation - Discounts - Subsidies - Payments - Outstanding Balance ## Finance - Chart of Accounts - Income - Expense - Transfer - Budget - Cash Flow - Reports ## Event Management - Calendar - Google Calendar Integration - Reminders ## Letter Management - Incoming Letters - Outgoing Letters - Disposition ## Certificate Management - Certificate Registry - Distribution Tracking --- # Planned Modules Designed for future expansion without changing the architecture. - Library - Student Attendance - Student QR Card - Extracurricular - Teacher Portal - Parent Portal - Inventory & Asset Management - Dormitory Management - Procurement - Assessment & Gradebook - Curriculum Planning - Mobile Application - Payment Gateway - AI Assistant - AI Analytics Future modules must reuse existing entities instead of creating duplicate databases. --- # Global Design Principles Always: - Understand the business problem first. - Extend existing capabilities whenever possible. - Preserve historical integrity. - Reuse existing entities. - Keep MVP intentionally simple. - Document assumptions explicitly. - Evaluate Permission, Audit Trail, Dashboard, Notification, Reporting, and Import/Export impacts for every new feature. Never: - Duplicate business entities. - Overwrite historical records. - Introduce unnecessary modules. - Generate implementation before validating business rules. - Optimize for hypothetical future requirements. Business correctness always takes priority over implementation speed. --- # Language Convention The application UI, forms, validation messages, and all user-facing content must use **Bahasa Indonesia**. Source code, architecture, database schema, APIs, documentation, variables, naming conventions, and business terminology must consistently follow **English best practices** to maximize maintainability and AI-assisted development.
Madrasah OS (MOS) adalah platform ERP internal terpusat untuk madrasah yang menggantikan proses Excel terfragmentasi dengan satu sumber kebenaran untuk administrasi, akademik, keuangan, dan operasional. Produk ini membantu staf, guru, dan administrator bekerja lebih cepat, lebih akurat, dan lebih transparan melalui workflow berbasis izin, audit trail immutable, dan model data historis yang tidak menimpa catatan lama.
Mengurangi ketergantungan pada spreadsheet manual dan file tersebar hingga 80% dalam 12 bulan pertama implementasi.
Meningkatkan akurasi data operasional dan keuangan minimal 95% melalui validasi, master data terpusat, dan audit trail.
Mempercepat proses administrasi inti seperti pendaftaran siswa, penagihan, dan pelaporan hingga 50% dibanding proses manual.
Meningkatkan visibilitas manajemen terhadap status akademik dan finansial melalui dashboard operasional terpusat dengan adopsi aktif dari minimal 70% pengguna internal.
Memposisikan MOS sebagai fondasi digital internal madrasah yang siap diperluas ke modul masa depan tanpa rework arsitektur besar.
Memungkinkan staf administrasi mengelola data siswa, guru, tagihan, dan dokumen dalam satu sistem tanpa mencari file di banyak tempat.
Membantu pimpinan melihat status operasional harian, keterlambatan pembayaran, dan aktivitas penting secara cepat dan akurat.
Memudahkan input data dengan template impor, validasi otomatis, dan notifikasi kesalahan yang jelas.
Memberikan jejak histori yang dapat dipercaya sehingga pengguna bisa melacak siapa mengubah apa, kapan, dan alasannya.
Mengurangi pekerjaan berulang dan kebingungan antar bagian dengan workflow yang jelas dan role-based access.
MOS bukan Learning Management System untuk pembelajaran, tugas kelas, atau materi ajar.
MOS bukan sistem payroll karyawan lengkap dan tidak menangani penggajian end-to-end pada MVP.
MOS bukan platform publik multi-tenant SaaS untuk dijual ke umum; fokusnya adalah penggunaan internal institusi.
MOS tidak mendukung self-registration pengguna pada MVP; onboarding harus berbasis undangan administrator.
Bertanggung jawab atas data siswa, guru, surat, dan koordinasi administrasi harian. Sangat bergantung pada ketepatan data dan ingin mengurangi pekerjaan berulang.
As an Administrator Operasional, I want to membuat undangan pengguna berdasarkan organisasi dan unit, so that saya bisa mengaktifkan akses tanpa membuat akun manual satu per satu.
As an Administrator Operasional, I want to mengimpor data siswa dan tagihan dari Excel dengan validasi dan preview, so that saya bisa memigrasikan data lama tanpa merusak kualitas data.
As an Administrator Operasional, I want to melihat dashboard pekerjaan hari ini dan notifikasi masalah data, so that saya bisa memprioritaskan tugas yang paling mendesak.
Mengelola invoice, pembayaran, pendapatan, pengeluaran, dan pelacakan saldo. Membutuhkan data yang konsisten dan mudah diaudit.
As a Petugas Keuangan, I want to membuat invoice berdasarkan billing plan dan status siswa, so that proses penagihan berjalan konsisten dan cepat.
As a Petugas Keuangan, I want to mencatat pembayaran dan melihat histori transaksi yang tidak bisa diubah, so that saya dapat memastikan setiap transaksi dapat diaudit.
As a Petugas Keuangan, I want to mengekspor laporan ke Excel atau CSV sesuai filter, so that saya bisa melakukan analisis lanjutan dan rekonsiliasi.
Tidak melakukan input detail setiap hari, tetapi membutuhkan pandangan ringkas, aman, dan akurat untuk pengambilan keputusan.
As a Kepala Madrasah, I want to melihat ringkasan siswa aktif, tunggakan, dan aktivitas penting di dashboard, so that saya bisa memahami kondisi madrasah dalam satu layar.
As a Kepala Madrasah, I want to meninjau audit trail untuk perubahan sensitif, so that saya bisa memastikan kepatuhan dan akuntabilitas.
As a Kepala Madrasah, I want to membatasi akses berdasarkan organisasi dan kebijakan data, so that informasi sensitif hanya terlihat oleh pihak yang berwenang.
Menyediakan fondasi autentikasi dan otorisasi berbasis organisasi untuk semua modul MOS, terpisah dari entitas bisnis seperti siswa atau guru.
Sistem harus mendukung User, Membership, Organization, dan Role sebagai model inti otorisasi.
Administrator harus dapat mengundang pengguna ke organisasi, unit, dan role tertentu melalui workflow berbasis invitation.
Role harus mendefinisikan hak tindakan, sedangkan policy harus membatasi cakupan data berdasarkan organisasi, unit, departemen, kelas, tahun ajaran, atau kepemilikan data.
Pengguna tidak boleh dapat mengubah hak akses mereka sendiri dan semua perubahan permission harus tercatat di audit trail.
Sistem harus mendukung satu user memiliki beberapa membership pada organisasi atau unit berbeda.
Menyediakan pengelolaan data inti dan referensi yang menjadi sumber kebenaran untuk semua modul, dengan validasi dan relasi yang konsisten.
Sistem harus menyimpan entitas permanen seperti Student, Teacher, Guardian, Subject, Department, dan Chart of Accounts sebagai master data.
Sistem harus menyediakan reference data seperti Academic Year, Semester, Grade, Class, dan Billing Template.
Perubahan pada master data harus mengikuti prinsip history-preserving, sehingga nilai lama tidak ditimpa jika relevan secara historis.
Form input manual dan data impor harus menggunakan aturan validasi yang sama untuk mencegah perbedaan perilaku.
Sistem harus mencegah duplikasi entitas inti melalui deteksi data ganda dan pengecekan identitas dasar.
Mendukung siklus hidup siswa dari pendaftaran hingga alumni, termasuk status akademik historis dan relasi keluarga.
Sistem harus mendukung pendaftaran, profil siswa, data guardian, status akademik, promosi, kelulusan, dan alumni.
Enrollment dan status siswa harus disimpan sebagai data historis append-only agar riwayat akademik tetap utuh.
Sistem harus memungkinkan pencarian siswa berdasarkan identitas, kelas, status, dan tahun ajaran aktif.
Perubahan penting seperti promosi atau kelulusan harus menghasilkan audit trail dan notifikasi bila diperlukan.
Sistem harus menautkan siswa ke kelas dan tahun ajaran tanpa menggandakan entitas siswa.
Menyediakan penagihan siswa dan pencatatan keuangan dasar dengan histori transaksi yang aman dan dapat diaudit.
Sistem harus mendukung billing plan, invoice generation, discount, subsidy, payment, outstanding balance, income, expense, transfer, budget, dan cash flow.
Invoice dan payment harus bersifat historis dan tidak boleh di-overwrite setelah disahkan.
Sistem harus menghitung saldo terutang berdasarkan transaksi yang tercatat dan konteks akademik yang dipilih.
Setiap transaksi keuangan harus menghasilkan audit trail yang memuat WHO, WHEN, WHAT, FROM, TO, WHY, dan HOW.
Sistem harus mendukung ekspor laporan keuangan sesuai filter dan hak akses pengguna.
Menyediakan pengalaman kerja berbasis widget dan kemampuan impor-ekspor untuk migrasi, operasional, dan reporting.
Dashboard harus menampilkan widget reusable seperti alerts, today's work, key metrics, notifications, dan quick actions.
Widget visibility harus dikendalikan oleh permission dan policy, bukan hardcoded role.
Sistem harus menyediakan template impor, preview, validation error report, duplicate detection, import history, dan background processing.
Sistem harus mendukung ekspor Excel dan CSV dengan filter aktif dan kontrol izin yang sesuai.
Sistem harus mengirim notifikasi untuk tugas operasional, perubahan data sensitif, dan hasil proses impor atau export sensitif.
Pengguna login melalui halaman autentikasi internal yang sederhana.
Setelah login, sistem menampilkan workspace yang sesuai dengan membership dan izin pengguna.
Pengguna melihat dashboard berbasis widget berisi tugas hari ini, notifikasi, dan shortcut tindakan utama.
Pengguna memilih tindakan seperti tambah siswa, buat invoice, atau impor data dari panel quick action.
Saat pertama kali aktif, pengguna dipandu melalui onboarding singkat berbasis peran dan organisasi.
Pengguna hanya melihat data yang diizinkan oleh membership, role, dan policy aktif.
Jika user memiliki beberapa membership, sistem meminta pilihan organisasi/unit saat masuk.
Jika akses tidak cukup, sistem menampilkan pesan yang jelas dalam Bahasa Indonesia.
Perubahan akses memicu audit trail otomatis.
Workspace administrasi hanya muncul untuk pengguna dengan izin yang sesuai.
Admin membuat undangan, pengguna menerima akses, lalu melengkapi profil dan kredensial.
Admin memilih organisasi, unit, dan role saat membuat invitation.
Undangan memiliki status seperti pending, accepted, expired, atau revoked.
Setelah menerima undangan, user diminta mengatur password dan melengkapi profil dasar.
Sistem memvalidasi keunikan email/identitas dan mencegah akun ganda.
Pengguna menambahkan data siswa, guru, atau transaksi melalui form yang konsisten dan tervalidasi.
Form menampilkan aturan wajib, format tanggal, dan relasi yang diperlukan.
Jika terjadi kesalahan, sistem menandai field spesifik dan memberikan pesan error yang mudah dipahami.
Data penting tidak bisa disimpan jika melanggar aturan bisnis utama.
Setiap penyimpanan sukses mencatat siapa yang melakukan dan perubahan apa yang terjadi.
Pengguna mengunduh template, mengisi data, lalu mengunggah untuk diproses secara terkontrol.
Template disesuaikan per modul dan berisi contoh format.
Sistem melakukan duplicate detection, preview baris, dan validasi sebelum commit.
Jika ada error, pengguna melihat daftar baris bermasalah beserta alasan dan perbaikannya.
Proses impor besar berjalan di background dan hasilnya tersimpan di history.
Pengguna memanfaatkan dashboard untuk melihat prioritas kerja dan mengambil tindakan tanpa berpindah layar berulang kali.
Widget menampilkan tunggakan, tugas hari ini, dan aktivitas terbaru.
Quick action memungkinkan akses langsung ke pembuatan invoice, pencarian siswa, atau pencatatan pembayaran.
Notifikasi hanya ditampilkan sesuai izin dan relevansi operasional.
Pengguna dapat menyaring tampilan berdasarkan akademik year, unit, atau kategori kerja.
Filter lintas tahun ajaran tanpa menggandakan data inti.
Audit trail searchable untuk menelusuri perubahan sensitif.
Permission-aware export untuk data finansial dan personal.
Penanganan status data historis seperti alumni, mutasi, promosi, dan pembatalan transaksi sesuai aturan append-only.
Pengelolaan beberapa membership untuk satu user di organisasi berbeda.
Kontrol privasi untuk dokumen dan lampiran sensitif per role dan policy.
Seluruh teks pengguna memakai Bahasa Indonesia yang konsisten dan formal-operasional.
Desain fokus pada task completion dengan navigasi sederhana dan komponen reusable.
Dashboard menampilkan prioritas kerja, bukan daftar menu panjang.
Aksesibilitas mencakup kontras warna cukup, dukungan keyboard, label form yang jelas, dan pesan error yang spesifik.
Performa harus terasa cepat untuk pencarian, dashboard, dan form utama agar staf tetap produktif saat jam sibuk.
Setiap pagi, Ibu Rina biasanya membuka beberapa file Excel berbeda untuk memeriksa data siswa baru, status pembayaran, dan surat masuk. Sering kali ada versi file yang tidak sinkron, nama siswa yang dobel, atau kolom yang terisi tidak lengkap. Pekerjaan yang seharusnya selesai dalam hitungan menit berubah menjadi proses cek ulang yang memakan waktu dan penuh risiko kesalahan. Setelah MOS diterapkan, Ibu Rina masuk ke dashboard dan langsung melihat tugas hari ini, notifikasi data yang belum lengkap, dan shortcut untuk membuat invoice atau mengimpor data. Saat ada file baru dari bagian pendaftaran, ia mengunggah template, memeriksa hasil validasi, dan memperbaiki baris yang bermasalah sebelum data masuk ke sistem. Kini, kepala madrasah bisa melihat data yang sama secara real time, bagian keuangan punya histori transaksi yang dapat diaudit, dan Ibu Rina bekerja dengan percaya diri karena semua pihak melihat satu sumber kebenaran yang sama.
Tingkat penyelesaian tugas utama harian di dashboard mencapai minimal 75% dalam 3 bulan.
Waktu rata-rata input data siswa baru turun minimal 50% dibanding proses manual.
Tingkat keberhasilan impor data tanpa error kritis mencapai minimal 90%.
Skor kepuasan pengguna internal mencapai minimal 4.2/5 untuk workflow administrasi utama.
Adopsi aktif mingguan dari staf administrasi dan keuangan mencapai minimal 70% pengguna target.
Jumlah komplain akibat data tidak sinkron turun minimal 60% setelah implementasi.
Pengurangan biaya operasional manual terkait pengolahan data dan rekap laporan minimal 30%.
Penurunan kesalahan penagihan atau rekap pembayaran minimal 50%.
Peningkatan kecepatan penyusunan laporan manajemen bulanan minimal 40%.
Tingkat penggunaan platform oleh fungsi inti mencapai minimal 80% dari proses administratif yang didefinisikan.
MOS menjadi fondasi digital utama untuk ekspansi modul masa depan tanpa perubahan arsitektur besar.
Waktu respons rata-rata untuk halaman dashboard utama di bawah 2 detik.
Uptime sistem minimal 99.5% pada jam operasional.
100% transaksi finansial, perubahan permission, dan impor data menghasilkan audit trail.
Tingkat kegagalan job impor background di bawah 2% per bulan dengan retry dan alert yang jelas.
Track user_logged_in untuk mengukur aktivasi dan frekuensi akses.
Track invitation_created dan invitation_accepted untuk memantau funnel onboarding.
Track student_created, student_updated, dan student_imported untuk melihat adopsi modul siswa.
Track invoice_generated, payment_recorded, dan balance_viewed untuk mengukur penggunaan billing dan finance.
Track export_requested dan export_completed untuk memantau kebutuhan reporting.
Track audit_log_viewed untuk memahami kebutuhan transparansi dan investigasi.
Track validation_error_shown untuk mengidentifikasi titik friksi pada form dan impor.
Frontend web application berbasis komponen modular untuk dashboard, form, dan workspace administrasi.
Backend API terstruktur untuk domain student, teacher, billing, finance, audit, dan identity.
Relational database yang mendukung referential integrity, transaksi, dan histori append-only.
Background job processing untuk impor besar, notifikasi, dan pembuatan laporan.
Search capability untuk audit trail, data master, dan histori operasional.
Permission and policy engine untuk evaluasi akses berbasis role, organisasi, unit, dan atribut data.
File storage terpisah untuk lampiran, template impor, dan dokumen resmi.
Email atau messaging service untuk undangan, notifikasi, dan reminder.
Identity provider atau internal auth service untuk login dan manajemen sesi.
Spreadsheet export/import pipeline untuk Excel dan CSV.
Google Calendar integration untuk modul event dan reminder.
Optional document storage or object storage service untuk file dan arsip.
Enkripsi data at rest dan in transit wajib diterapkan.
Akses ke data sensitif harus dibatasi dengan permission dan policy, bukan hanya role.
Audit trail harus immutable, append-only, dan dapat ditelusuri per aksi.
Ekspor data sensitif harus tercatat dan hanya dapat dilakukan oleh pengguna berwenang.
Sistem harus menyiapkan kebijakan retensi data dan dukungan kepatuhan privasi yang relevan seperti GDPR/CCPA bila dibutuhkan konteks operasional.
Gunakan pemisahan read-heavy dashboard dari proses tulis transaksi bila beban meningkat.
Impor besar harus diproses asynchronous agar UI tetap responsif.
Caching dapat diterapkan pada reference data yang sering dibaca seperti semester, kelas, dan role.
Monitoring harus mencakup latency API, antrian background jobs, error rate, dan storage growth.
Migrasi dari Excel yang beragam formatnya dapat memunculkan data duplikat dan kualitas data rendah; solusinya adalah template standar, preview, dan duplicate detection.
Kebutuhan permission yang kompleks bisa memicu role explosion; solusinya adalah memakai policy berbasis atribut sebagai pelengkap role.
Pengguna non-teknis mungkin menolak perubahan dari file manual ke sistem terpusat; solusinya adalah onboarding bertahap dan layar yang fokus pada workflow harian.
Integritas histori dapat terganggu jika perubahan data tidak dirancang append-only; solusinya adalah membedakan master data, operational data, dan transaction data sejak awal.
Kinerja dashboard dan laporan bisa menurun saat data bertambah; solusinya adalah indexing, job background, dan pemisahan query reporting.