User Manual
Complete guide to setting up and operating the Edu Stack Information System.
Local Development
How to set up the development environment on your local machine.
Clone the repository from GitHub.
Install dependencies using `npm install` in the root directory.
Configure environment variables in `.env` files for both frontend and backend.
Start the development server with `npm run dev`.
System Setup
Initializing the system for the first time.
Seed Data (Recommended)
Quickly populate the system with demo schools, users, and schedules using the `npm run db:seed` command.
From Scratch
Start with an empty database and create your first System Administrator through the CLI.
User Authentication
Methods to access the system.
Login Helper
A developer tool on the login screen to quickly switch between demo identities without passwords.
Email & Password
Standard secure authentication using hashed passwords in the D1 database.
SSO Integration
Enterprise-grade login support for Google, GitHub, and Microsoft accounts.
Standard Secure Login
Technology Stack
The Edu Stack IS is built on a modern, robust, and highly scalable cloud-native infrastructure.
NestJS
A progressive Node.js framework for building efficient, reliable and scalable server-side applications. It uses TypeScript and combines elements of OOP, FP, and FRP.
React
A JavaScript library for building component-based user interfaces. It enables efficient rendering and reactive state management.
Cloudflare D1
A fully managed relational database based on SQLite, designed for edge computing within the Cloudflare Workers ecosystem.
Model Context Protocol (MCP)
An open protocol that enables AI models to have secure and standardized access to local or remote data and tools.
Next.js
The React framework for the web, enabling server-side rendering and static site generation for optimal performance and SEO.
Tailwind CSS
A utility-first CSS framework for rapidly building modern websites without ever leaving your HTML.
Application Modules
The system is designed as a modular platform where each component serves a specific pedagogical or administrative purpose.
System Administration
A set of core services for multi-tenant school lifecycle management, global configuration, and security auditing.
Enables global platform orchestration, secure tenant isolation, and centralized resource management.
Auth & SSO
Secure authentication layer with support for traditional credentials and enterprise SSO (Google, GitHub, Microsoft).
Ensures data integrity and robust Role-Based Access Control (RBAC) across the entire platform.
School Registry
Core database module for managing students, staff, classes, and physical building structures.
Serves as the central 'Source of Truth' for all other educational and administrative modules.
Interactive Scheduling
Sophisticated engine for timetable creation with real-time conflict detection and substitution management.
Automates the most complex school administrative tasks and eliminates scheduling human errors.
Grading & Evaluation
Comprehensive system for tracking marks, weighted averages, and complex verbal evaluations.
Provides immediate academic transparency for teachers, students, and parents.
Pedagogical AI Assistant
Deep integration of LLMs into teacher workflows for lesson planning, material generation, and report polishing.
Significantly reduces administrative burden on teachers while bringing modern AI tools to the classroom.
MCP API (AI Integration)
A standardized bridge that connects external AI agents with live system data through a secure tool-based interface.
Allows students and developers to experiment with building autonomous AI agents on top of school data.
System Roles
Comprehensive guide to specific procedures and features for each system identity.
System Administrator
The ultimate orchestrator. This role encompasses both global platform infrastructure and school-specific technical management.
Core Functions
Multi-tenant school lifecycle (create/delete), global and local user management, SSO & AI configuration, system auditing, and administrative support through secure impersonation.
Detailed Workflows
School & Infrastructure Management
Create school tenants and configure their global identity (SSO) and AI resources.
Navigate to 'Schools' in the sidebar to create a new tenant.
Configure SSO providers (Google/GitHub/MS) for the school instance.
Define AI token limits and manage provider API keys.
Monitor global platform health and per-school token analytics.
Registry & User Orchestration
Manage the school registry and perform bulk user operations.
Use the CSV Import tool to onboard large groups of students or staff.
Assign roles and permissions within the specific school context.
Manage classroom groups and physical building structures.
Perform secure user impersonation to troubleshoot account issues.
Compliance & Security Auditing
Ensure the system operates securely through detailed log analysis.
Access the 'Audit Log' to review all high-impact actions.
Filter by user or action type to investigate specific changes.
Utilize GDPR tools for data anonymization or export requests.
Manage system-wide backups and automated recovery schedules.
Platform Core Gallery
System Dashboard
A high-level overview of the entire platform, showing global metrics, active schools, and recent system activities at a glance.
School Management
Centralized hub for managing all school tenants within the system, allowing administrators to monitor status and access specific school configurations.
New School Tenant
Step-by-step interface for onboarding new educational institutions, defining their basic identity and initial resource allocations.
School Configuration
Detailed settings for existing schools, where administrators can modify metadata, contact information, and specific instance behaviors.
Secure Impersonation
A powerful administrative tool that allows system admins to access the system as a specific user for troubleshooting and direct support.
Global User Directory
Management interface for users with system-wide privileges, ensuring only authorized personnel can access the platform core.
User Provisioning
Simple form for creating new system-level accounts and assigning global administrative roles.
AI Resource Orchestration
Control center for AI integration, where token limits are defined and provider API keys (OpenAI, Anthropic, etc.) are securely managed.
Identity Providers
Overview of configured Single Sign-On methods, supporting enterprise authentication through major providers.
SSO Configuration
Technical setup for new identity providers, including client IDs, secrets, and endpoint mappings.
System Health & Analytics
Real-time monitoring of platform performance and detailed analytics on AI resource consumption across all tenants.
Global Parameters
Configuration of system-wide constants and feature flags that affect the behavior of the entire Edu Stack ecosystem.
Demo Data Factory
Development tool for quickly generating realistic demo data (users, classes, schedules) for testing and presentation purposes.
Data Lifecycle Management
Robust tools for manual database backups and restoring the system state to ensure data integrity and disaster recovery.
School Administrator
The local operational manager responsible for the technical configuration and user management of a specific school instance.
Core Functions
School-specific user onboarding, role assignments, classroom and building structure management, and local system configuration.
Interface Screenshot
Detailed Workflows
Local User Management
Onboard and manage students, teachers, and staff within the school.
Use the CSV Import tool to bulk upload student and staff records.
Assign appropriate roles (Teacher, Student, Parent) to imported users.
Manage user account status and reset passwords when necessary.
Verify user access to specific school modules.
Interface Screenshot
Educational Structure
Define the physical and organizational layout of the school.
Create building structures and define individual classrooms.
Set up class groups and assign students to their respective grades.
Configure school periods and lesson timings.
Maintain the registry of active subjects and departments.
Interface Screenshot
Module Configuration
Fine-tune system features for local school needs.
Enable or disable specific modules like 'AI Assistant' or 'Community'.
Configure local grading scales and weighting systems.
Set up school-wide notification preferences.
Review local audit logs for security and compliance.
Interface Screenshot
Headmaster
Pedagogical and organizational leader of the school. Focuses on overview and school-wide communication.
Core Functions
Access to high-level school dashboard and statistics, School-wide event planning, Public community announcements and broadcasts, Monitoring of educational quality and teacher performance.
Interface Screenshot
Detailed Workflows
Strategic Oversight
Monitor real-time statistics and school-wide KPI.
View the 'Principal Dashboard' for high-level summaries.
Analyze grade distributions across different departments.
Check attendance percentages for the current semester.
Identify classes or subjects with abnormal patterns for review.
Interface Screenshot
School Communications
Post official announcements and manage bulletins.
Navigate to the 'Community' module.
Click 'New Announcement' and select the target audience (All, Staff, or Students).
Write the content and pin critical messages to the top.
Publish and verify notification delivery.
Interface Screenshot
Academic Calendar
Oversee and approve the yearly plan.
Open the 'School Events' calendar.
Add key milestones like holidays, exams, or meetings.
Set visibility permissions for each event.
Sync with the public school dashboard for parents and students.
Interface Screenshot
Deputy Principal
Operational manager focusing on the technical organization of the educational process.
Core Functions
Academic year and semester setup, Classroom and building management, Subject and curriculum (SVP) design, Complex schedule planning and collision detection, Substitution management, Class registry oversight.
Interface Screenshot
Detailed Workflows
Interactive Schedule Planning
Plan the timetable with collision detection.
Open the 'Schedule Planner' module.
Select a class and drag subjects into available time slots.
The system will flag red markers for teacher or room collisions.
Resolve collisions and publish the final version for the school.
Interface Screenshot
Substitution Management
Handle daily absences and reassignments.
Check the 'Absence List' for teacher notifications.
Go to 'Substitutions' and select the affected lessons.
Assign a substitute teacher or change the room/subject.
Save to instantly update the affected users' personal schedules.
Interface Screenshot
Curriculum Design (SVP)
Define subjects and curriculum outputs.
Navigate to 'School' -> 'Curriculum'.
Create subject templates and define hours per week per grade.
Map competencies (RVP) to specific subjects.
Activate the curriculum version for the upcoming academic year.
Interface Screenshot
Teacher
The educational core of the system. Direct interaction with students and educational data.
Core Functions
Grade book management (marks, categories, weights), Attendance tracking and excuse management, Class book entries and signing, Thematic plans and lesson preparations, AI Teaching Assistant (lesson generation, report card polishing).
Interface Screenshot
Detailed Workflows
Grade Book Management
Enter grades and manage weighted averages.
Select a subject from your 'Teaching Overview'.
Choose 'Add Grade' and define the category (e.g., 'Big Test').
Input grades for the students and add optional comments.
Verify that the weighted average is calculated automatically.
Interface Screenshot
Digital Class Book
Sign lessons and track attendance.
Open the 'Class Book' during your active lesson.
Mark student attendance (Present, Absent, Late).
Record the lesson topic according to the thematic plan.
Digitally sign the entry to finalize the record.
Interface Screenshot
AI Pedagogical Assistant
Use AI to generate plans and polish reports.
Open the 'AI Assistant' from the lesson preparation page.
Provide a topic and target grade for the lesson plan.
Review the generated structure and export to your preparations.
Use AI to improve the language of verbal report card evaluations.
Interface Screenshot
Parent
The guardian overseeing the educational journey of their children.
Core Functions
Monitoring grades and academic progress, Electronic absence excuse submission, Communication with teachers and school management, Viewing child's personalized schedule and substitutions.
Interface Screenshot
Detailed Workflows
Academic Oversight
Stay informed about your child's performance.
Select your child's profile from the dashboard switcher.
Open the 'Grades' module to see all recent assessments.
Review weighted averages and teacher comments for each subject.
Set up email notifications for new grade entries.
Interface Screenshot
Absence Management
Officially excuse your child's missed lessons.
Navigate to the 'Attendance' module.
Click 'New Excuse' and select the date range.
Provide the reason for the absence (e.g., 'Medical').
Submit the request and monitor its approval status by the teacher.
Interface Screenshot
Direct Communication
Engage with the school community effectively.
Use the 'Messages' module to start a thread with a teacher.
Participate in school polls and respond to event invitations (RSVP).
Read pinned announcements on the school bulletin board.
Check the schedule for upcoming Parent-Teacher meetings.
Interface Screenshot
Student
The primary user of educational services. Focuses on personal progress and daily organization.
Core Functions
Personal dashboard with grade overview, Interactive daily and weekly schedule, Community messaging and polls, Access to teaching materials, AI Study Partner for educational support.
Interface Screenshot
Detailed Workflows
Personal Progress Tracking
View grades and teacher feedback.
Check the 'Dashboard' for recent grades and announcements.
Open the 'Grades' module to see a subject-by-subject view.
Click on any grade to read specific teacher comments.
Monitor your overall average and predicted final grade.
Interface Screenshot
Interactive Timetable
Access your schedule and substitution info.
Go to the 'Schedule' module.
Toggle between Daily and Weekly views.
Substitution changes will be highlighted in orange.
Click on a lesson to see the assigned room and teacher.
Interface Screenshot
AI Study Partner
Get help with concepts and summaries.
Open the 'AI Study Partner' chat drawer.
Ask a question about your current subject topics.
The AI uses school context to provide relevant answers.
Request summaries of teaching materials or practice quiz questions.
Interface Screenshot