Arrangements

This document explains how the school automation SaaS is organized end-to-end: the public marketing layer, school-specific landing sites, and the core multi-tenant app. It also shows how the database and business logic are centralized while themes and domains are customized per school so each buyer feels like it’s built just for them.

Product Layers

  • Marketing site (public): Visitors learn about the product, compare plans, and sign up.
  • School landing (public per school): A branded page per school and domain where parents/students can learn about the school and start joining.
  • Core app (authenticated): Internal tools for admins, teachers, parents, and students to manage day-to-day operations.

Tenancy Model

  • Central database and logic: All schools share the same database schema and server-side code.
  • Tenant isolation via schoolId: Every domain model row references its schoolId. All queries are scoped by schoolId.
  • Custom domains: Each school uses a unique subdomain (and optional custom domain). Theme, logo, and colors are read from that school’s settings and applied at runtime.

Flow Chart

  1. Discover and Sign Up
  • Visitor lands on the marketing site, reads features and pricing.
  • Creates an account and starts a trial (no credit card for Sudan by default).
  • Language is set from Accept-Language or user choice (Arabic default, English optional).
  1. Create School (Owner)
  • Owner enters school name, preferred subdomain, locale, timezone.
  • System validates subdomain availability and reserves it.
  • A School record is created and linked to the owner; trial countdown starts.
  1. Domain and Branding (Optional early)
  • Subdomain is active immediately (school.hogwarts.app style).
  • Owner can request a custom domain; platform gives CNAME instructions.
  • Logo, colors, and landing content can be set; preview updates instantly.
  1. Seed Defaults (Automated)
  • System seeds core roles and minimal academic structure (example class and subject).
  • Admin can purge demo data later from Settings.
  1. Admin Setup
  • Configure academic structure: years/terms/periods, classes, subjects, rooms.
  • Import CSVs for students and teachers, or add manually.
  • Assign class tutors, subject teachers, and timetable basics.
  1. Invites and Access
  • Admin invites additional Owners/Admins, Teachers, Parents.
  • Emails (or SMS when available) include a secure link with locale-aware copy.
  • Invite acceptance creates or links user accounts to the school.
  1. Teacher Onboarding
  • Teacher accepts invite, sees assigned classes and timetable.
  • Marks attendance daily or per period; can post announcements.
  1. Parent and Student Onboarding
  • Parent accepts invite, verifies contact, and links to student(s).
  • Parent portal shows attendance and announcements; student portal shows timetable and messages.
  1. Billing and Trials
  • Trial countdown is visible on the dashboard with clear remaining days.
  • Admin can upload manual payment receipts for review or upgrade online when available.
  • Invoices and receipts are stored per school; grace period applies on expiry.
  1. Operations and Observability
  • Structured logs include request ID and schoolId; errors are tracked with release tags.
  • Daily backups run; restores are tested periodically in staging.
  1. Maintenance and Change Management
  • Weekly releases; changes documented in the Changelog.
  • Tenant-safe migrations; unique constraints scoped by schoolId.
  1. Exit and Deprovisioning
  • Owner can export core data (CSV) and request deletion.
  • Deletion moves school to a retention queue before permanent removal.

Alternate Paths and Edge Cases

  • Operator-provisioned school: platform staff can create schools for pilots.
  • Subdomain conflict: suggest alternatives (include suffixes like "-edu").
  • Low bandwidth: pages are kept lightweight and forms are resilient to retries.
  • Invite expired: resend and rotate tokens; audit the resend.
  • Multi-lingual: all templates available in Arabic and English; RTL mirrored.

Block Diagram

Public Layer
  • Marketing website
  • School landing per domain
App Layer
  • Core app (role dashboards)
  • Server Actions / API
Shared Core
  • Auth
  • Business logic
  • Prisma + Postgres (tenant scoped)
UI
ThemeshadcnBlocks
Apps
OperatorSchoolMarketing
Landing
Onboarding
CreateInviteSeed
BrandingSetup
Tables
TableFiltersPaging
Auth
AuthGatesSession
I18n
ArabicEnglishLocale
RTL
Domains
SubdomainCustom
Billing
TrialsReceiptsInvoices
Ops
LogsErrorsMetrics
Runbooks
Backups
DailyRetentionRestores
Database
NeonPrismaTenancy
Indexes
Server
ActionsZodRevalidate
Patterns
shadcnESLintpnpm
CI
Community
ContributeConductChangelog
Roadmap
Theme and assets are applied per school domain at runtime; all data remains centrally stored and scoped by schoolId.

Layout Overview

  • Marketing: Hero, features, pricing, testimonials, docs, and onboarding.
  • School Landing: Logo, brand colors, description, contact, CTA to join/apply.
  • Core App:
    • Admin: school setup, users/roles, billing, academic structure (years, terms, periods), departments/subjects, classrooms.
    • Teacher: timetable, classes, attendance, assignments, grading.
    • Parent/Student: profile, enrollments, announcements, submissions, attendance summary.

Centralized Data, Customized Experience

  • One schema, many schools: School, User, Student, Teacher, Class, Subject, Attendance, etc. All rows include schoolId for isolation.
  • Central logic: Shared actions and validation apply the same rules to all schools.
  • Custom theming: Per-school settings fetched at runtime; UI applies logo, palette, and domain assets.

Database and Model Highlights

  • Multi-file Prisma schema, centralized datasource and generator in prisma/schema.prisma with models in prisma/models/*.
  • Enforced tenant scoping in application layer; composite unique keys include schoolId for data integrity.
  • Compatible with Neon (serverless Postgres) and Prisma Client.

Provisioning & Domains

  • On plan purchase, the system creates a School, assigns a subdomain school.myapp.com, and optionally validates a custom domain via CNAME.
  • Certificate automation handled by the hosting platform; settings saved to the School row.

Plans and Billing

  • Plans: Trial, Basic, Pro. Limits like maxStudents, maxTeachers stored on School.
  • Graceful trial handling and upgrade/downgrade paths.

Key Benefits

  • Buyer sees only their data and domain; operations remain centralized.
  • Rapid onboarding for new schools using the same robust core.
  • Lower operations cost and consistent feature rollout.

For schema placement and multi-file setup, see: Prisma multi-file schema docs.