CH 2Basic

Business Architecture

NexusOne is a shared-database, school-scoped multi-tenant SaaS platform. This chapter covers the seven-level platform hierarchy, the permanent NexusOne identity every person receives, the school verification and subscription lifecycle (including the Basic/Elite tier gate used across the whole product), and how Platform Admins and Super Admins oversee schools. All features below are available on the Basic tier — there is no separate Elite tier at the business-architecture layer itself.

Basic Tier Features

Basic

Platform Hierarchy

Basic
  • Seven-level tree: Platform → Super Admin → School → Campus → Academic Year → Class/Section → Student
  • Platform Admin has cross-tenant visibility; every other role is scoped to its own school(s)
  • A Super Admin can own and operate multiple School documents, each independently verified and subscribed
  • Multi-campus support: reporting is available at campus, school, and group level

Multi-Tenant School Model

Basic
  • Shared-database, school-scoped isolation — every document in every collection carries a school (ObjectId) field
  • getSchoolFilter(req) returns {} for platform_admin, { school: { $in: user.schools } } for super_admin, and { school: user.school } for everyone else
  • School lifecycle: verificationStatus pending → verified → rejected, set by Platform Admin
  • registrationType tracks whether a school was self_registered or admin_created

NexusOne ID

Basic
  • Implemented — every user gets a permanent, sequential nexusOneId (format NX-000000001) from the NexusIdCounter model
  • Assigned automatically in the User pre('save') hook on first creation; never reused, never editable
  • Follows the person across school transfers, role changes, and future alumni conversion

Multi-School & Multi-Role Users

Basic
  • school (active/primary) and schools[] (full history) are kept in sync by a pre-save hook
  • belongsToSchool() and validateSchoolAccess() middleware enforce that a user only touches schools in their schools[] array
  • A single user account can hold roles across school history (e.g. teacher who transferred schools) while keeping one NexusOne ID

Subscription & Billing

Basic
  • One Subscription document per school: plan (monthly/quarterly/yearly), tier (basic/elite), status, and a Dodo Payments transaction history
  • 90-day free trial via Subscription.activateTrial() — access remains open until trialEndsAt even if the user cancels mid-trial
  • checkSubscriptionAccess middleware gates every protected route: school must be verified and the subscription must be active, cancelled-but-in-period, or trialing
  • checkEliteTier middleware (runs after checkSubscriptionAccess) additionally requires subscription.tier === 'elite' — this is the actual Basic/Elite gate used across the whole platform
  • Dodo Payments webhook listener is registered at /api/payments before the JSON body parser so signatures can be verified on the raw body

School Branding

Basic
  • Per-school logo, favicon, brand name, color palette (primary/secondary/accent/sidebar), and heading/body fonts stored on School.branding
  • Branding routes require authentication only (no subscription check) so the UI can render correctly even before a school is verified or subscribed

Platform & Super Admin Oversight

Basic
  • Platform Admin dashboard aggregates schools, users, students, teachers, courses, enrollments, and 30-day growth — via a single aggregation pipeline, not per-school queries
  • Platform Admin creates Super Admin accounts and grants/revokes which schools each Super Admin can access
  • Super Admin dashboard: owned schools, school admins, cross-school users, analytics, and school creation
  • Every school verification, role change, and multi-school grant is written to AuditLog / ActivityLog

API Reference — Chapter 2

School Registration & Management

POST/api/school-registration/register

Submit a school for platform verification (public)

GET/api/school-registration/pending

List schools awaiting verification (super_admin, platform_admin)

POST/api/school-registration/approve/:schoolId

Approve a pending school

POST/api/school-registration/reject/:schoolId

Reject a pending school

GET/api/schools/public/:id

Public school info for admission forms

GET/api/schools

List schools (scoped to requesting user)

PUT/api/schools/:id

Update school profile (admin)

Subscription & Billing

GET/api/subscriptions

Get subscription status for the current school

POST/api/subscriptions/trial

Start the 90-day free trial

POST/api/subscriptions/cancel-trial

Cancel trial — retains access until trialEndsAt

POST/api/subscriptions/checkout

Initiate a Dodo Payments checkout session

POST/api/payments

Dodo Payments webhook handler (mounted before the body parser)

Super Admin

GET/api/super-admin/dashboard/stats

Aggregated stats across owned schools

GET/api/super-admin/schools/overview

Owned schools with per-school user counts

GET/api/super-admin/school-admins

List school admins across owned schools

POST/api/super-admin/school-admins

Create a school admin account

GET/api/super-admin/users

List users across owned schools

Platform Admin

GET/api/platform-admin/dashboard

Platform-wide aggregate statistics

GET/api/platform-admin/schools

List all schools across all tenants

PUT/api/platform-admin/schools/:id/verify

Approve or reject a school

GET/api/platform-admin/school-verifications

List schools pending verification

POST/api/platform-admin/super-admins

Create a Super Admin account

POST/api/platform-admin/super-admins/:id/schools

Grant a Super Admin access to a school

DELETE/api/platform-admin/super-admins/:id/schools/:schoolId

Revoke a Super Admin's access to a school

GET/api/platform-admin/subscriptions

View all subscriptions across all schools

Branding

GET/api/schools/:id/branding

Get school branding (logo, colors, fonts) — no subscription check

PUT/api/schools/:id/branding

Update school branding

Frontend Pages

PathRoleDescriptionTier
/register-schoolPublicInformational — self-registration is disabled; directs to Super AdminBasic
/register-platform-adminPublicOne-time bootstrap: creates the platform_admin account when the database has no users yetBasic
/subscriptionAdmin / Super AdminPlan selection, trial start, checkoutBasic
/subscription/successAdmin / Super AdminPost-checkout confirmationBasic
/subscription/trial-successAdmin / Super AdminTrial activation confirmationBasic
/subscription/cancelAdmin / Super AdminCheckout cancelled screenBasic
/dashboard/super-adminSuper AdminMulti-school overview, recent activityBasic
/dashboard/super-admin/schoolsSuper AdminList / create / edit owned schoolsBasic
/dashboard/super-admin/school-adminsSuper AdminCreate and manage school admin accountsBasic
/dashboard/super-admin/school-verificationsSuper AdminTrack verification status of owned schoolsBasic
/dashboard/super-admin/usersSuper AdminUsers across all owned schoolsBasic
/dashboard/super-admin/settingsSuper AdminGroup-level settingsBasic
/dashboard/platform-adminPlatform AdminPlatform-wide statistics and healthBasic
/dashboard/platform-admin/schoolsPlatform AdminAll schools across all tenantsBasic
/dashboard/platform-admin/school-verificationsPlatform AdminApprove or reject pending schoolsBasic
/dashboard/platform-admin/super-adminsPlatform AdminCreate Super Admins, grant/revoke school accessBasic
/dashboard/admin/brandingAdminSchool logo, colors, fontsBasic

Mobile Screens

(platform-admin)/index
Platform Admin home — schools, super admins, health
Basic
(platform-admin)/schools
All schools across all tenants
Basic
(platform-admin)/super-admins
Create and manage Super Admin accounts
Basic
(platform-admin)/school-assignment
Grant/revoke a Super Admin's school access
Basic
(platform-admin)/subscriptions
View subscriptions across all schools
Basic
(admin)/subscription-status
Trial/subscription status for the admin's own school
Basic
← Chapter 1: Executive SummaryChapter 3: Identity, Auth & IAM →
Back to Docs →