Rebuilding the software infrastructure schools run on

1. Introduction & System Overview

Parthnex ERP is a multi-tenant, mobile-first (and web-responsive) school management platform built to run the full daily operating cycle of a school: enrolment records, staffing, class and section structuring, subject-teacher mapping, attendance capture, scheduling, communication, academic content distribution, homework tracking, the academic events calendar, and a cross-school 'Extras Vault' of exam and reference material.

The product is explicitly multi-tenant: a single deployed application serves many schools, each isolated behind a numeric School Code (e.g. 18484) entered at login. This is the architectural pattern built toward — one Flutter codebase and one NestJS + PostgreSQL backend serving every school as a distinct tenant, with row-level isolation rather than separate deployments per school.

Three first-class roles are modelled end-to-end in the UI: Principal/Admin, Teacher, and Student. Each role gets its own navigation rail, its own permitted actions, and — critically — the same shared screens (Attendance, Study Materials, Notices) render differently depending on who is looking at them. This document walks through every module visible in the application, explains the UI structure, the underlying workflow, the role-based behavioural differences, and the implicit data model each screen depends on.

The system supports both Light and Dark themes, Admin ("A" avatar) and Teacher ("T" avatar, Ms. Kavitha Reddy) sessions, and a three-step authentication flow (role selection → credential entry → school-code validation). Throughout this document, admin-only affordances are called out separately from teacher-visible affordances so the access-control boundary is unambiguous.

Reading this document:

Each module section follows the same structure: Purpose, Screen Layout, Step-by-step Workflow, Role Behaviour, and Data & Edge-Case Notes.

2. Authentication, Multi-Tenancy & Onboarding

Before any dashboard is reachable, the app runs a two-stage gate: first the tenant is resolved via a School Code, then the individual is authenticated within that tenant via a role-scoped login form.

2.1 School Code Validation ('Welcome Back' screen)

The very first screen a returning user sees is a gradient hero card reading 'Welcome Back' with a single numeric input labelled SCHOOL CODE. A hint line offers a demo code ('Try: 18484 · superadmin') so evaluators can self-serve without a real tenant. Submitting calls a 'Validate School Code' action.

• Purpose: resolves which tenant's data partition the subsequent session should be scoped to — this is the multi-tenancy boundary made visible to the end user.
• Behind the scenes this maps to a lookup against a `schools` table keyed by a short numeric code, returning a `school_id` (or `tenant_id`) that is attached to every subsequent API call and used to enforce Row Level Security (RLS) at the database layer.
• Dark theme is available on this screen too (top-right toggle), and the choice persists into the next screen, indicating the theme preference is stored client-side before any authenticated session exists.

2.2 Role Selection & Credential Entry

After the school code resolves, the user lands on a role-scoped login card headed 'MULTI-TENANT SCHOOL ERP' with the resolved school's name ('Parthnex ERP') and a green 'Verified — 18484' badge confirming the tenant lookup succeeded.

Three pill-shaped tabs — Principal, Teacher, Student — sit above the email/password fields. Selecting a tab swaps both the placeholder email (Admin@school.in / Teacher@school.in / Student@school.in) and, implicitly, which role claim will be issued on successful login. A persistent helper line at the bottom offers a working teacher demo credential (kavitha@rvsh.edu / any password) so the flow can be exercised without provisioning a real account.

2.3 Why This Matters for the Data Model

The two-step flow (tenant, then identity) implies that user accounts are tenant-scoped rather than global — the same email could theoretically exist under two different school codes as two distinct rows, which is the standard pattern for multi-tenant SaaS. It also means password/credential resets, first-login flows, and MPIN-based quick login all need the school code as part of their lookup key, not just the email.

3. School Dashboard

The Dashboard is the landing screen after login for both Admin and Teacher roles, and is the clearest example in the app of a single screen rendering two different data slices for two different audiences while sharing the exact same visual language.

3.1 Layout

A left-hand vertical navigation rail (icon-only on wide screens, icon + label in the expanded/mobile drawer) sits beside a scrollable content pane. The header repeats the school name and the current academic year plus today's date ('Academic Year 2026-27 · Thursday, 2 July 2026'), so every screen in the app is self-orienting even mid-scroll. A bell icon with a red dot indicates unread notifications, and a circular avatar (initial 'A' for Admin, 'T' for Teacher, with the teacher's full name 'Ms. Kavitha Reddy' shown alongside it) anchors the top-right corner.

3.2 Admin Dashboard Metrics

The Admin sees school-wide KPI cards, each following the same visual pattern: an icon chip, a large numeral, a label, and a small trend/context line underneath in a secondary colour:

• Total Students — 520, broken down as '12 sections', with a green ↑4% trend badge.
• Total Teachers — 41, broken down as '8 departments', with a green ↑2% trend badge.
• Today's Attendance — 87%, with '452 present' and a red ↓3% trend badge, showing day-over-day comparison.
• Total Classes — 10, with '32 sections'.
• Pending Fees — ₹1.2L, with '38 students' owing, rendered in an amber accent to draw financial attention.
• A 'Weekly Attendance Trend' bar chart spans Mon–Fri (91%, 88%, 93%, 86%, 87% for the week of Jun 2–6, 2026), colour-coded green for days at/above a threshold and amber below it.
• Recent Notices and Upcoming Events are rendered as two side-by-side condensed lists, each with a 'View all →' / 'Calendar →' deep link into the full module.

3.3 Teacher Dashboard

The Teacher's dashboard reuses the identical card and chart components as the Admin's — proof that the KPI cards are a shared, data-driven component rather than role-specific screens — but the numbers shown are the same school-wide figures in the screenshots captured, suggesting teachers see the same aggregate visibility as admins for headline metrics, even though their sidebar is dramatically pared down (Dashboard, Attendance, Timetable, Notices, Study Materials only — no Students, Teachers, Classes, Subjects, Fee Ledger).

Design implication: The dashboard's KPI cards are built as a single reusable widget that accepts a data payload, with the backend deciding (via role-aware query scoping) whether school-wide or teacher-scoped numbers are returned — avoiding duplicated UI code between panels.

4. Student Management

Accessible only from the Admin sidebar (the icon resembling two overlapping head-and-shoulders silhouettes), this module is the system of record for the pupil roster.

4.1 Screen Composition

4.2 Workflow

The default view lists every enrolled student across all classes; applying the Class and Gender filters narrows the table without a page reload, and the enrolled-count in the header updates to match. Tapping a row opens a detail/edit view, consistent with the CRUD pattern used elsewhere (Teachers, Classes, Subjects).

Because bulk import is a backend capability, the Add Student flow offers both a single-record form and a CSV/XLSX bulk-upload path.

4.3 Data & Edge Cases

• Roll numbers are scoped per class-section, not globally unique (Roll #1 exists independently in Class 1-A and any other section).
• A student record must reference class_id, section_id, and (implicitly) a guardian/parent contact set for fee and notice delivery.
• Multi-tenancy means every query here is implicitly filtered by the resolved school_id from the login step.

5. Teacher Management

A card-based roster of the teaching staff, reflecting that teacher records carry richer, more heterogeneous metadata than the flat student roll.

5.1 Screen Composition

The header shows '4 faculty members' (a filtered/paged subset of the school-wide 41 shown on the dashboard) with an 'Add Teacher' CTA. Each teacher renders as an individual card with:

• A coloured initial avatar (e.g. purple 'M' for Dr. Meera Nair, purple 'S' for Mr. Suresh Iyer) — generated from the name when no photo is uploaded.
• Full name in bold.
• Subject specialism and qualification line (e.g. 'Mathematics · M.Sc, B.Ed', 'Physics · M.Sc Physics').
• The list of class-sections they are attached to (e.g. 'Class 9-A, Class 9-B, Class 10-A').
• A 'View →' button opening the full teacher profile.

5.2 Relationship to Other Modules

This module is the anchor for two downstream features: Subject assignment (a subject lists its teacher, e.g. Mathematics → Dr. Meera Nair) and Attendance Configuration mode (Class Teacher vs Subject Teacher), both of which read from the teacher-to-class-section mapping established here. Any change to a teacher's assigned sections cascades into who is permitted to mark attendance for those sections, which is exactly the 'Restricted' badge behaviour observed in the Teacher Panel.

The underlying schema stores a `teachers` table with a `department` foreign key (matching the dashboard's '8 departments' rollup) plus a many-to-many `teacher_class_sections` join table for the assignment list.

6. Classes Management

This screen is the structural backbone of the entire system: every other module (Students, Attendance, Timetable, Subjects, Study Materials) references a class and, within it, a section.

6.1 Screen Composition

A table lists every class the school runs with columns for:

6.2 Attendance Mode Lives on the Class

It is significant that the Attendance Mode column appears directly on the Classes table and is repeated, with full detail, on the dedicated Attendance Configuration screen. This tells us att_mode is a property of the class record itself (or of each class-section), not a global school setting — junior classes (1–3) default to 'Class Teacher' mode where only the homeroom teacher can mark attendance, while senior classes (9–10) default to 'Subject Teacher' mode where any subject teacher assigned to that period can mark it, reflecting how secondary schools operate with period-wise subject teachers.

6.3 Workflow

An 'Add Class' button creates a new grade; sections are then added and reordered within a class-edit view. Deleting or renaming a section here cascades carefully — existing attendance records, timetable entries, and student assignments all key off the class-section pair, so this uses a soft-delete pattern rather than a hard delete.

7. Subjects Management

A compact card list mapping subjects to the class they belong to and the teacher who owns them.

7.1 Screen Composition

The header reads '4 subjects' with an 'Add Subject' CTA. Each card shows a two-to-three-letter subject code chip (MTH, PHY, ENG, BIO) in a tinted square, the full subject name, a 'Class X · Teacher Name' descriptor line, a Core/Elective badge, and an Edit button.

• Mathematics — Class 9 · Dr. Meera Nair · Core
• Physics — Class 9 · Mr. Suresh Iyer · Core
• English — Class 1 · Ms. Kavitha Reddy · Core
• Biology — Class 10 · Mr. Ajay Sharma · Elective

7.2 Core vs Elective

The Core/Elective badge is more than cosmetic — it drives whether the subject is compulsory in exam-mark-entry and report-card generation (the 'n-column marks entry' feature already built for Examinations) versus optional. A student's report card generator treats elective subjects differently when computing aggregate/overall percentage.

7.3 Relationship to Timetable

Every subject defined here becomes a selectable option in the Timetable Manager's period dropdowns, so Subjects acts as the lookup table that both Timetable and Examinations depend on. Deleting a subject that already has timetable periods or exam records attached is blocked or requires reassignment.

8. Timetable Manager

A period-by-period weekly schedule grid, editable per class-section, that is horizontally scrollable on mobile given how many periods a typical day has.

8.1 Screen Composition

Two dropdowns at the top — Class (e.g. 'Class 9') and Section ('A') — scope the grid being edited; a 'Save' button commits changes. The grid itself is Day (rows: Monday–Saturday) × Period (columns: P1 08:00 through P6 11:40, each with its start time baked into the column header), and every cell is a dropdown pre-populated with the subject already scheduled (Physics, Chemistry, Mathematics, English, Biology, P.T.).

8.2 Observed Pattern in the Sample Data

In the captured Class 9-A timetable, each subject occupies the same period every day of the week (Physics is always P1, Chemistry always P2, and so on) — a simplified schedule. Whether the system supports different subjects per day per period is confirmed by the grid structure itself (each cell is independently editable), even though this sample happens to be repetitive.

8.3 Workflow & Validation Considerations

• Changing a cell's dropdown selects a different subject for that day/period and stays in a 'dirty' local state until 'Save' is pressed.
• The implementation validates that a teacher is not double-booked across two different class-sections in the same period at save time — this is the conflict prevention check.
• The period list (P1–P6 with fixed clock times) is shared with the Attendance module's 'AUTO period' feature, which auto-assigns the period slot based on the current time.

9. Attendance Management

The most operationally detailed module in the app, spanning summary metrics, per-section take/view/manage actions, a marking workflow with two input methods, and a full edit history.

9.1 Attendance Landing Screen

Admin sees three KPI cards up top: '16 Classes Today', '6 Records Saved', and a partially-visible '87%' rate card, followed by a scrollable list of every class-section with three action buttons — Take, View, and (for Admin only) Manage.

9.2 Per-Section Status Chips

9.3 Take Attendance Flow

Tapping 'Take' opens a dedicated screen headed 'Take Attendance — Class 1 / A' with a subtitle confirming the active mode ('Class Teacher Mode · AUTO Period'). A date field defaults to today (02/07/2026) and a Period field, when in AUTO mode, is locked and pre-filled ('Period 6') with an inline info banner: 'Auto-mode: period is set automatically. Content is locked after saving.' This is a deliberate anti-fraud/anti-error guardrail — once an AUTO-period record is saved, its period slot can no longer be altered.

Two bulk-action buttons, 'All Present' and 'All Absent', pre-fill every student's status in one tap, following which the teacher fine-tunes individual students. A secondary text-based entry mode is also offered: two comma-separated input fields, 'Present Roll Numbers' and 'Absent Roll Numbers' (e.g. 'e.g. 1,' / 'e.g. 6,'), with an 'Apply' button — useful for a teacher calling out roll numbers quickly rather than tapping each row.

Below that, live-updating summary tiles show Present / Absent counts and a computed Percentage, followed by the per-student table with P/A toggle pairs per row, and a rolled-up 'PRESENT (3): 1, 2, 3' / 'ABSENT (0): —' confirmation strip directly above the Save Attendance button. A secondary 'PDF' button sits beside Save, letting the teacher export the just-taken register immediately.

9.4 View Attendance

The View screen ('View Attendance — Class 1 / A') lists every saved period as its own card: 'Period 1 — 2026-07-02', the teacher who recorded it ('Teacher: Admin'), the exact save timestamp ('Saved: 11:20:12'), and per-card Present/Absent/Rate figures (2 Present, 1 Absent, 67% Rate for Period 1; 0 Present, 3 Absent, 0% Rate for Period 2), with the actual present/absent roll numbers listed underneath each card. This provides a full period-by-period audit history.

9.5 Manage Attendance (Admin-Only Correction Flow)

The 'Manage' button — visible only in the Admin's action row, absent from the Teacher's — opens a screen with the same per-period cards as View, but each card now carries Edit and Delete icon buttons. Tapping Edit switches that card into an inline editor: a 'Save Changes' / 'Cancel' pair appears at the top, and the student table becomes tappable, showing a student's status flipped as a live example of a correction in progress.

The subtitle 'Admin can edit or delete any saved record' is an explicit, user-facing statement of the authorization rule: once attendance is saved, only an Admin can retroactively change it — teachers cannot edit past submissions themselves, forming a coherent integrity story: teachers submit once, corrections require administrative oversight.

10. Attendance Configuration (Admin-Only)

A settings screen, admin-exclusive, that lets the school define — per class — how attendance is captured, decoupling policy from the day-to-day Take/View/Manage workflow.

10.1 Screen Composition

A table lists every class with its sections and two mutually-exclusive toggle buttons for Attendance Type: 'Class Teacher' and 'Subject Teacher' (a third column for Period Mode — AUTO vs SELECT — configures auto-assignment locks).

10.2 The Explanatory 'How it works' Panel

Uniquely among the modules, this screen ships with a built-in help panel spelling out the business rules directly in the product:

• Class Teacher mode: Only the assigned class teacher can mark attendance for that class-section.
• Subject Teacher mode: Any subject teacher assigned to that class-section can mark attendance for their period.
• AUTO period: The system auto-assigns the next available period for the day, and it cannot be edited once chosen.
• SELECT period: The teacher manually picks which period they are recording attendance for.

10.3 Why This Screen Exists Separately

Although the Classes table (Section 6) already displays each class's current Att. Mode as a read-only pill, this dedicated configuration screen is where that mode is actually changed, and it is intentionally gated to Admin — separating structural views from configuration changes.

11. Notice & Circular Desk

A broadcast-communication module for school-wide or targeted announcements, available to both Admin and Teacher roles.

11.1 Notice Card Anatomy

Each notice renders as a left-border-accented card, the border colour keyed to priority (amber for HIGH, red for URGENT, green for NORMAL), and contains:

• A priority badge and an audience line ('To: Entire School', 'To: Class 10', 'To: Class 9, Class 10').
• A publish date.
• A bold title ('Summer Vacation Notice 2026', 'Board Examination Schedule', 'Parent-Teacher Meeting').
• A short body/message summarising the announcement.
• A 'By: <issuing office>' attribution line (Principal Office, Exam Cell, Library Department, Admin Office).

11.2 Compose Notice Flow

The compose form captures: Title, Message (multi-line), a Target dropdown, and a Priority dropdown.

11.3 Targeting & Fan-out

Because notices can target the entire school or specific sections, the backend uses a `notice_targets` join table rather than a single foreign key, allowing notices to fan out to arbitrary class scopes or user roles.

12. Study Materials & Homework

A two-tab module bundling academic resource distribution (Study Materials) with assignment tracking (Homework) under one screen, available to both Admin and Teacher.

12.1 Study Materials Tab

A tab switcher sits above a row of type filters: ALL, SYLLABUS, PYQ, NOTES, BOOK, EXTRA. Each material entry shows a type icon, category badge, class-subject tags, title, and attached filename with a download anchor.

An 'Upload Material' button opens a form for Title, Material Type dropdown, Class and Subject dropdowns, and a drag-and-drop-styled attachment zone accepting PDF, DOCX, XLSX, PPTX, and images.

12.2 Homework Tab

Switching to Homework reveals an 'Assign Homework' CTA and a running count, with each assignment rendered as a red-accented card indicating the class section, the due date pill, and a trash icon to delete the assignment if authorized.

13. Events Calendar

A month-view academic calendar paired with a chronological 'Upcoming Events' list, available from the Admin sidebar and reachable to teachers.

13.1 Screen Composition

A compact month grid marks dates with a colored dot when an event falls on them. Beside the grid, an 'Upcoming Events' list shows each event as an icon-tile, title, and date (e.g. Summer Vacation Begins, Annual Sports Day, Science Exhibition) with visually distinct category indicators.

13.2 Relationship to Notices

Some events appear as both a Notice and a Calendar entry, and the system is designed to allow the admin to publish notices and add calendar events in tandem to simplify announcements.

14. Extras Vault

A platform-wide (cross-tenant) supplementary resource library, distinguished from Study Materials by its explicit subtitle: 'Platform-wide extra study resources'.

14.1 Screen Composition

Filter chips mirror the Study Materials taxonomy, confirming that both modules share the same underlying 'resource' entity, differing only in a scope flag (school-specific vs platform-wide). Each entry card shows a type icon, class standard targets, and download hooks.

Centralizing exam-prep content (JEE question banks, CBSE PYQs, standard reference textbooks) that is identical in value across every school on the platform avoids each of potentially hundreds of tenant schools separately uploading the same files. This reduces storage duplication and provides rich shared materials.

15. Access Control Boundary — Teacher Panel

The system defines a clear operational boundary between Administrator and Teacher roles to protect secure data.

15.1 Sidebar Differences

15.2 'My Classes' Concept

Unique to the Teacher sidebar is an expandable 'My Classes' section listing each class-section the teacher is attached to, along with their role in that specific class (e.g. Class Teacher vs. Subject Teacher). This serves as a personalized navigation shortcut.

15.3 The 'Restricted' Badge

The most precise access-control signal appears on the Teacher's Attendance list: Class sections where the teacher does not hold class teacher rights display a disabled 'Take' button paired with a red 'Restricted' badge. This lets teachers understand why a control is missing rather than wondering if the class disappeared.

16. Theming — Light & Dark Mode

Every screen captured has a matching Light and Dark rendition, toggled via a switch item pinned to the bottom of the sidebar.

• Light mode: white/near-white card backgrounds, dark navy text, and the purple brand accent for primary buttons and active nav items.
• Dark mode: near-black (#0B0B14) backgrounds, off-white text, and the same purple accent preserved for active states.
• Status colours (green for present/positive trends, red for absent/restricted, amber for pending) are preserved identically across both themes for accessibility.

17. Cross-Cutting UI Patterns

Several interaction and layout conventions repeat across all modules to maintain a cohesive user experience:

• The 'Header + Primary CTA' Pattern: Every management screen follows an identical header shape: a bold title, a one-line count subtitle, and a single gradient-purple primary action button pinned to the top-right.
• The 'Compose/Upload Form' Pattern: Every creation form shares the same shape: Title field, description textarea, classification dropdowns, and a two-button footer.
• Card-List vs Table Choice: The app consistently chooses tables for dense, homogeneous, sortable/filterable data, and cards for heterogeneous or richly-attributed entities.

18. Module Availability by Role — Summary Matrix

19. Observations & Recommendations

• Consolidate Notices and Calendar creation: Given events appear in both notices and calendar tabs, link notice creations to calendar updates to avoid duplicate actions.
• Expose Restriction Reasons: Add tooltip guides explaining attendance restriction states and who holds homeroom rights.
• Shared Forms: Consolidate form widgets to reduce frontend code size.

20. Glossary of Terms Used in the App

School Code: A short numeric tenant identifier entered before login to resolve database connection scopes.

CT / Class Teacher mode: Attendance policy where only the homeroom teacher assigned to a section may mark its attendance.

Subject Teacher mode: Attendance policy where any teacher assigned to teach a subject in that section may mark attendance for their period.

AUTO period: The system automatically determines and locks the current period when attendance is taken.

Extras Vault: A platform-wide shared reference resource library.