Requirements

This document defines the functional and non-functional requirements for the multi-tenant School Management System targeting schools in Sudan. It includes the MVP scope to get to market quickly with a high-quality, focused experience.

Goals

  • Deliver a cloud-based, multi-tenant platform for schools with strict data isolation
  • No deadlines: we contribute steadily as a community and ship when useful
  • Arabic-first (RTL) and English, mobile-first, and offline-tolerant UX
  • Keep the stack simple: Next.js, TypeScript, Tailwind, Prisma, Neon, shadcn/ui

Success Signals (non-deadline)

  • Onboarding: school creation and first invites feel easy
  • Usage: staff return frequently to mark attendance and communicate
  • Reliability: stable experience during business hours (Sudan TZ)
  • Community: more contributors, shared ownership, and revenue share traction

Personas

  • School Owner / Principal: oversees operations, billing, reporting
  • Administrator: manages users, classes, schedules, announcements
  • Teacher: marks attendance, views classes, submits grades (basic)
  • Student: views timetable, assignments, announcements
  • Parent/Guardian: views student attendance and announcements
  • Accountant: manages subscription and invoices

MVP Scope (Phase 1)

  • Authentication & RBAC

    • Email/password login, magic link optional later
    • Roles: Owner, Admin, Teacher, Student, Parent, Accountant
    • Basic audit (who did what, when)

  • School Provisioning (Multi-tenant)

    • Create school with unique subdomain
    • Trial period (configurable), subscription setup, plan selection
    • Seed minimal defaults (roles, example classes, subjects)

  • Core Data

    • Students, Teachers, Classes, Subjects
    • Class enrollment (student-to-class mapping)

  • Attendance

    • Daily/period-based attendance by class
    • Basic reports (per student, per class, per day)

  • Timetable (Basic)

    • Weekly schedule per class and teacher

  • Announcements

    • School-wide and class-scoped announcements

  • Parent Portal (Read-only MVP)

    • Attendance and announcements for linked students

  • Settings

    • School profile, logo, timezone (Africa/Khartoum), locale (ar/en)
    • Domain settings (subdomain + custom domain request)

  • Billing (MVP)

    • Plans (Free Trial, Basic, Pro)
    • Per-school subscription record, invoices history
    • Manual payment/receipt upload option for Sudan context; online payments later

  • Internationalization (I18N)

    • Arabic (RTL) and English (LTR) UI, switchable per-user; default per-school

Out of Scope (MVP)

  • Advanced exams/grading engine and transcripts
  • Library, transportation, dormitory, cafeteria
  • HR/payroll, advanced accounting
  • Realtime chat, push notifications, mobile apps
  • Advanced workflow automation and integrations

Non-Functional Requirements

  • Multi-tenant isolation: every record scoped by schoolId; enforce in queries
  • Security: encrypted secrets, hashed passwords, least-privilege policies
  • Performance: p95 page load < 1.5s on 3G-like conditions
  • Accessibility: WCAG AA (keyboard nav, contrast, focus states)
  • Observability: structured logs, basic metrics, error tracking
  • Backups: daily automated database backups; 7/30-day retention
  • Cost: prefer serverless/Neon, scale-to-zero where possible

Data Model Guardrails

// Every business table must include schoolId; all uniqueness is within school scope
@@unique([schoolId, someUniqueField])

Environments

  • Development: feature branches, preview deployments
  • Staging: pre-production smoke tests, data close to prod shape
  • Production: monitored, restricted access

Technical Choices

  • Next.js App Router, Server Actions for mutations where appropriate
  • Prisma ORM with Neon Postgres
  • shadcn/ui + Radix + Tailwind for UI
  • Type-safe forms and validation; prefer Zod

MVP Exit Criteria

  • 3 pilot schools running on subdomains
  • Teachers mark attendance daily; Admins publish announcements; Parents view portal
  • Billing active for at least one school (manual or online)

Context & Constraints (Sudan)

  • Connectivity can be intermittent and low-bandwidth → optimized payloads, caching, offline-tolerant patterns where feasible
  • Payments may be cash/bank transfer heavy → manual billing flows supported from day one
  • Devices: older Android phones are common → test on low-powered devices and 3G conditions
  • Language: Arabic-first with English available; RTL is default for many users

Detailed Functional Requirements (MVP)

  • Authentication & RBAC

    • Create account, login, logout, password reset
    • Role assignment by Admin/Owner; least-privilege defaults
    • Session and device management (view and revoke sessions)

  • School Provisioning

    • Create school: name, locale, timezone
    • Subdomain generation and uniqueness validation
    • Trial period applied automatically; plan selection stored on tenant

  • Data Management

    • Students: create, import CSV, assign to classes
    • Teachers: create, assign to subjects/classes
    • Classes & Subjects: create, update, archive; map timetable slots

  • Attendance

    • Mark present/absent/late per class period
    • Bulk mark for whole class with per-student overrides
    • Reports: per student, per class, per date range; export CSV

  • Timetable

    • Weekly schedule grid per class and teacher
    • Conflict detection on teacher/room

  • Announcements

    • Create announcement (title, body, visibility scope)
    • Scopes: school-wide, role, class; publish/unpublish

  • Parent/Guardian Portal

    • View linked students, attendance, announcements

  • Settings

    • School profile, branding, locale, domain, billing info

  • Billing

    • Track plan, invoices, payment status, trial countdown
    • Manual payment receipt upload and approval workflow

Data Model Overview

  • Core entities: School, User, Role, Class, Subject, TeacherProfile, StudentProfile, Enrollment, TimetableSlot, AttendanceRecord, Announcement, Subscription, Invoice, Domain
  • All business entities include schoolId. Uniqueness is scoped to schoolId.

Security & Compliance

  • Enforce tenant scoping at access boundaries and in every query
  • Passwords hashed with strong algorithm; secrets stored securely
  • Audit log for sensitive actions (billing changes, domain changes)

Performance SLOs

  • p95 TTFB < 500ms for authenticated pages
  • p95 page interactive < 2s on 3G
  • API p95 < 400ms for core endpoints

Reliability & DR

  • Daily automated backups; 7/30-day retention
  • RPO ≤ 24h (MVP), RTO ≤ 4h
  • Restore drill monthly in staging

Observability

  • Structured logs with request ID and schoolId
  • Metrics: signups, active schools, attendance submissions/day, announcement publishes/day
  • Error tracking with release tagging

Testing Strategy

  • Unit: utilities, server actions
  • Integration: Prisma queries with tenant scoping
  • E2E: critical flows (provision school, mark attendance, publish announcements)
  • i18n snapshots for ar/en; RTL and LTR UI navigation

Release & Environments

  • Feature branches → preview → main → production
  • Weekly release cadence; hotfixes as needed
  • Changelog appended to docs on each release

Risks & Mitigations

  • Payment friction → manual flow day-1; online later
  • Connectivity issues → lightweight pages, caching, retry logic for submissions
  • Data errors on import → strict CSV validation and dry runs

Backlog (Post-MVP)

  • Exams and grading, transcript exports
  • Messaging integrations (SMS, WhatsApp, Email)
  • Mobile PWA enhancements and push notifications

Deliverables for Execution Team

  • Domain model ERD and Prisma schema files for: School, User, Role, Class, Subject, Enrollment, TimetableSlot, AttendanceRecord, Announcement, Subscription, Invoice, Domain
  • API contracts for core flows (create school, invite user, mark attendance, publish announcement)
  • Seed scripts with realistic fixtures for staging (3 sample schools)
  • Access control matrix per role and feature
  • i18n content files (ar/en) for primary user flows
  • Operational runbooks: backup/restore, incident response, domain onboarding

Acceptance Criteria (MVP)

  • A new school can be created on a unique subdomain and complete initial setup within 10 minutes
  • Teachers can mark class attendance with per-student overrides; reports export to CSV
  • Parents can view attendance and announcements for linked students
  • Billing shows trial countdown and supports manual receipt upload and approval
  • All data access is tenant-scoped by schoolId; no cross-tenant leakage in tests