User Manual
Complete guide to setting up and operating the Edu Stack Information System.
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.
Fly.io + SQLite
The backend and MCP server run together on a single Fly.io machine per environment, with the SQLite database stored on a persistent 1 GB volume mounted at /data. better-sqlite3 is used for direct file access.
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.
Data Model
Entity-relationship diagrams derived directly from the production database schema. The schema is split into eight bounded contexts so each diagram fits on one screen. Click any thumbnail to open the full-resolution image.
Tenancy & Identity
Multi-school tenancy, users, roles, parent-student links, SSO identities, and audit log.
Academic Structure & Curriculum
Academic years, semesters, grade levels, student enrollment, curriculum versions, subject templates and instances, RVP competencies.
Workload & Physical Space
Teacher and staff workload, subject assignments, buildings, rooms and room sharing between schools.
Schedule & Class Book
Lesson timetable, substitutions, recurring events, snapshots, and the digital class book with teacher signatures.
Attendance, Absences & Grading
Attendance records, parent absence excuses, grades, report cards, behavior and competency grades, educational measures, commission exams and classification deadlines.
Planning & Teaching Materials
Thematic plans split by week, lesson preparations and uploaded teaching materials linked to subjects and grade levels.
Communication & Community
Conversations, messages and attachments, notifications, bulletin posts, polls with options and votes, calendar events with RSVPs, and school-wide events.
System, AI & Misc
System settings, API key secrets, AI token usage, global config, and ad-hoc user tasks.
Generated from apps/backend/src/database/schema.sql via Mermaid.
The full picture
All ~40 tables, attributes and relationships on a single canvas. Scroll inside the frame to pan, or click to open the full-resolution image in a new tab.
Role Permission Matrix
Authoritative mapping of which user role can perform which operation, sourced from the @Roles decorators in the backend controllers. Operations are grouped by the same eight domains as the data model.
Tenancy & Identity
| Operation | System AdminSys | School AdminAdm | HeadmasterHdm | DeputyDep | TeacherTch | ParentPar | StudentStu |
|---|---|---|---|---|---|---|---|
| Manage schools (create / edit / delete) | |||||||
| Manage system users | |||||||
| Configure SSO providers | |||||||
| View audit log | |||||||
| Invite school users | |||||||
| Suspend / reactivate / remove users | |||||||
| Change user role | |||||||
| View own profile | |||||||
| Edit profile / change password / avatar | |||||||
| Export / delete own data (GDPR) |
Academic Structure & Curriculum
| Operation | System AdminSys | School AdminAdm | HeadmasterHdm | DeputyDep | TeacherTch | ParentPar | StudentStu |
|---|---|---|---|---|---|---|---|
| Manage academic years | |||||||
| Manage semesters | |||||||
| Manage grade levels | |||||||
| Manage subject templates | |||||||
| Manage subject instances | |||||||
| Manage curriculum versions (SVP) | |||||||
| Batch student enrollment | |||||||
| Manage RVP competencies | |||||||
| View white-book / curriculum coverage |
Workload & Physical Space
| Operation | System AdminSys | School AdminAdm | HeadmasterHdm | DeputyDep | TeacherTch | ParentPar | StudentStu |
|---|---|---|---|---|---|---|---|
| Manage classrooms | |||||||
| Manage buildings and rooms | |||||||
| Share rooms across schools | |||||||
| Manage teacher workloads | |||||||
| Manage staff workloads | |||||||
| Assign staff to subjects |
Schedule & Class Book
| Operation | System AdminSys | School AdminAdm | HeadmasterHdm | DeputyDep | TeacherTch | ParentPar | StudentStu |
|---|---|---|---|---|---|---|---|
| View schedule (classroom / teacher / own) | |||||||
| Create / edit schedule events | |||||||
| Bulk schedule operations | |||||||
| Manage substitutions | |||||||
| Validate schedule (collision check) | |||||||
| Fill class book entries | |||||||
| Sign class book entries |
Attendance, Absences & Grading
| Operation | System AdminSys | School AdminAdm | HeadmasterHdm | DeputyDep | TeacherTch | ParentPar | StudentStu |
|---|---|---|---|---|---|---|---|
| Record attendance | |||||||
| View attendance | |||||||
| Submit absence excuse | |||||||
| Review absence excuses | |||||||
| Export attendance (CSV) | |||||||
| Create / edit / delete grades | |||||||
| View classroom grades | |||||||
| View own / child's grades | |||||||
| Behavior grades | |||||||
| Competency grades | |||||||
| Issue report cards | |||||||
| AI polish / translate verbal evaluation | |||||||
| Educational measures | |||||||
| Commission exams |
Planning & Teaching Materials
| Operation | System AdminSys | School AdminAdm | HeadmasterHdm | DeputyDep | TeacherTch | ParentPar | StudentStu |
|---|---|---|---|---|---|---|---|
| Manage thematic plans | |||||||
| Manage lesson preparations | |||||||
| Upload teaching materials | |||||||
| View teaching materials |
Communication & Community
| Operation | System AdminSys | School AdminAdm | HeadmasterHdm | DeputyDep | TeacherTch | ParentPar | StudentStu |
|---|---|---|---|---|---|---|---|
| Send / receive messages | |||||||
| Create bulletin post | |||||||
| View bulletin | |||||||
| Delete bulletin post | |||||||
| Create poll | |||||||
| Vote in poll | |||||||
| Create calendar event | |||||||
| RSVP to event | |||||||
| View notifications |
System, AI & Misc
| Operation | System AdminSys | School AdminAdm | HeadmasterHdm | DeputyDep | TeacherTch | ParentPar | StudentStu |
|---|---|---|---|---|---|---|---|
| Use AI chat | |||||||
| AI-assisted generation (plans / tests / analysis) | |||||||
| AI-seed a classroom | |||||||
| Backup and restore | |||||||
| Generate test data | |||||||
| System monitoring | |||||||
| System settings (AI keys, SSO, params) | |||||||
| MCP tools API |
System Architecture
Application components in ArchiMate notation and a user-perspective view showing which screens and services each role touches.
Application components
Backend modules grouped by domain (Core platform, Education, Communication, Intelligence). The backend + MCP server run on a Fly.io machine with SQLite on a persistent volume; the frontend is built and served from Cloudflare Pages. Cloudflare R2 is used for off-machine backups. REST + MCP are the two public service surfaces; external systems (LLM providers, SSO IdPs, SMTP, MCP clients) are shown separately. The diagram still shows the previous Cloudflare-only layout — see the Deployment section below for the current topology.
User perspective
Seven user roles plus an external MCP/API developer, mapped to the screens or portals they use and the backend services that serve them.
Key processes
Sequence diagrams for representative flows across the system — administration, authentication, AI orchestration, and day-to-day school operations.
Initial system setup
First-run wizard: create the first system admin from scratch, or restore the system from a SQLite backup.
Login (credentials + SSO)
Local credential authentication (Argon2 + JWT cookie) and SSO via Google / GitHub / Microsoft with email-match policy.
Generate test data
System admin seeds an entire school — classes, users, schedule, grades, attendance — optionally using AI for school and student names.
Backup and restore
Three flows in one diagram: the nightly cron backup, an ad-hoc admin backup, and restoring the database from R2.
AI-assisted generation
Teacher requests a thematic plan or report-card polish; backend decrypts the provider key, calls the LLM, and logs token usage.
Schedule substitution
Deputy assigns a substitute teacher/room; collision detector validates against existing schedule before persisting and notifying affected users.
Absence excuse
Parent submits an excuse; homeroom teacher reviews and either approves (attendance reconciled) or rejects with a reason.
Local Development
End-to-end setup of the monorepo on your machine. The frontend has no custom .env — it uses Vite's proxy to forward /api to the backend. All configuration lives in a single .env file at the repo root, consumed by both the NestJS backend and the MCP server.
Prerequisites
Node.js 20+
Runtime for backend, MCP server and the build chain.
npm 10+
Bundled with Node — used to install monorepo workspaces.
flyctl (optional)
Fly.io CLI. Only needed to deploy your own environment. Install: brew install flyctl or curl -L https://fly.io/install.sh | sh.
Quick start
Clone the repository
git clone '<repo>' && cd edu-stack-is-sandboxCopy the env template
cp .env.example .envGenerate the two required secrets
openssl rand -base64 64 # JWT_SECRET
openssl rand -base64 32 # ENCRYPTION_KEYInstall workspaces
npm installInitialise the local SQLite database
npm run db:initStart backend, frontend and MCP server
npm run devDefault URLs after npm run dev
| Web application | http://localhost:5173 |
|---|---|
| Backend REST API | http://localhost:3000 |
| Swagger / OpenAPI | http://localhost:3000/api/docs |
| MailDev web UI (test inbox) | http://localhost:1081 |
| MCP server (SSE endpoint) | http://localhost:3001/sse |
What about the frontend?
The React/Vite app has no .env file. In dev, Vite proxies every /api request to http://127.0.0.1:3000 (see apps/frontend/vite.config.ts), so the only "config" it needs is the backend running on PORT 3000. In production builds the API base URL is read from VITE_API_URL (set by the deploy workflow to https://be-sandbox-N.is-edustack.org) and baked into the bundle Cloudflare Pages serves.
.env reference
Every variable consumed by the backend or MCP server, grouped by concern. Examples in the table are the .env.example defaults; values shown as a shell command should be replaced with the command's output.
Security (required)
| Variable | Default / example | Purpose |
|---|---|---|
JWT_SECRETrequired | openssl rand -base64 64 | Symmetric key used to sign and verify the JWT cookies issued at login. Rotating it logs everyone out. MUST be unique per deployment. |
ENCRYPTION_KEYrequired | openssl rand -base64 32 | AES-256 key used to encrypt sensitive columns (provider API keys in SystemSecret, etc.). Losing it makes encrypted rows unreadable. |
SETTINGS_ENCRYPTION_KEYoptional | openssl rand -base64 32 | Optional separate key used by the legacy SystemSettings table. Falls back to ENCRYPTION_KEY when empty. |
Login helper (dev only)
| Variable | Default / example | Purpose |
|---|---|---|
ENABLE_LOGIN_HELPERoptional | true | When true, the login screen shows a panel with one-click demo users. Always set to false in production. |
LOGIN_HELPER_ROLESoptional | SYSTEM_ADMIN,ADMIN,TEACHER,DEPUTY,PRINCIPAL,STUDENT,PARENT | Comma-separated allow-list of roles the helper surfaces. Lets you hide STUDENT/PARENT in a teacher-only demo, for example. |
DEMO_PASSWORDoptional | "Demo1234!" | Password every seeded demo user is given. Used by the seeder; only relevant when AUTO_SEED is on. |
Database
| Variable | Default / example | Purpose |
|---|---|---|
DB_ADAPTERrecommended | sqlite | Selects the database driver. Keep "sqlite" — better-sqlite3 reads a local file in dev and the Fly volume at /data/edustack.db in production. |
DATABASE_URLrecommended | file:./dev.db | Path to the local SQLite file. Used by Prisma CLI tools (introspection, migrations); the runtime opens the file directly via better-sqlite3. |
Email / SMTP
| Variable | Default / example | Purpose |
|---|---|---|
SMTP_HOSTrecommended | localhost | Hostname of the SMTP server. In local dev this is the bundled MailDev (npm run dev starts it on 1025). |
SMTP_PORTrecommended | 1025 | Port of the SMTP server. 1025 for MailDev, 587/465 for production providers. |
SMTP_USERoptional | — | SMTP username. Empty for MailDev; required for SendGrid / SES. |
SMTP_PASSoptional | — | SMTP password / API key. Always pass via secret manager in production. |
MAIL_FROMrecommended | [email protected] | From: address used on every transactional email (invites, password resets, notifications). |
Services and networking
| Variable | Default / example | Purpose |
|---|---|---|
PORTrecommended | 3000 | Port the NestJS backend listens on. |
MCP_PORTrecommended | 3001 | Port the MCP server listens on. |
CORS_ORIGINrecommended | http://127.0.0.1:5173 | Allowed origin for the REST API. Set to the frontend URL. |
FRONTEND_URLrecommended | http://127.0.0.1:5173 | Public URL of the frontend. Used to build links inside emails (invites, password reset). |
MCP_SERVER_URLrecommended | http://127.0.0.1:3001/sse | Where the backend looks for the MCP server. The /sse suffix is the MCP transport endpoint. |
MCP server hardening
| Variable | Default / example | Purpose |
|---|---|---|
MCP_HOSTrecommended | 127.0.0.1 | Bind address for the MCP server. Default 127.0.0.1 (loopback) means it's unreachable from the network — set to 0.0.0.0 only when fronted by a reverse proxy AND when MCP_AUTH_TOKEN is set. |
MCP_AUTH_TOKENoptional | openssl rand -hex 32 | Shared bearer token. When set, /sse, /message and /v1/chat/completions require Authorization: Bearer '<token>'. The backend forwards it automatically. |
MCP_CORS_ORIGINoptional | — | Comma-separated CORS allow-list. Leave empty to disable CORS (correct for loopback-only deployments). |
AI providers
| Variable | Default / example | Purpose |
|---|---|---|
OPENCODE_BASE_URLoptional | http://127.0.0.1:3001/v1 | Base URL of the OpenAI-compatible OpenCode provider. Defaults to the local MCP server; in production MUST be https://. |
OPENCODE_API_KEYoptional | — | Bearer token for the OpenCode provider (when fronted by an authenticated MCP). |
GOOGLE_AI_API_KEYoptional | — | Google Gemini API key. Either GOOGLE_AI_API_KEY or GEMINI_API_KEY is accepted. |
GEMINI_API_KEYoptional | — | Alias of GOOGLE_AI_API_KEY for historical reasons. |
OPENAI_API_KEYoptional | — | OpenAI API key. Used when the OpenAI provider is selected in system settings. |
ANTHROPIC_API_KEYoptional | — | Anthropic API key. Used when the Anthropic provider is selected. |
Backups (Cloudflare R2)
| Variable | Default / example | Purpose |
|---|---|---|
R2_ENDPOINToptional | https://<account>.r2.cloudflarestorage.com | Cloudflare R2 S3-compatible endpoint URL. Leave empty to fall back to local file backups in BACKUP_DIR. |
R2_ACCESS_KEY_IDoptional | — | R2 access key. Treat as a secret (in production set via flyctl secrets set R2_ACCESS_KEY_ID=… --app edustack-sandbox-N). |
R2_SECRET_ACCESS_KEYoptional | — | R2 secret key. Treat as a secret. |
R2_BUCKET_NAMEoptional | edustack-backups | Name of the R2 bucket to write backups to. |
BACKUP_DIRoptional | data/backups | Filesystem path used when R2_* variables are empty. Created on first backup. |
AUTO_BACKUPoptional | false | If true, the BackupScheduler creates a nightly backup automatically. |
Development and seeding
| Variable | Default / example | Purpose |
|---|---|---|
NODE_ENVrecommended | development | Standard Node environment. Set to "production" outside of local dev. |
AUTO_SEEDoptional | true | If true, the seeder runs on the first start of a fresh database. Creates the demo school and the default System Admin. |
SEED_FILEoptional | — | Path to an alternative seed JSON. Empty uses the bundled default scenario. |
SEED_ADMIN_EMAILoptional | [email protected] | Email of the auto-created System Admin. |
SEED_ADMIN_FIRST_NAMEoptional | System | First name of the auto-created System Admin. |
SEED_ADMIN_LAST_NAMEoptional | Admin | Last name of the auto-created System Admin. |
SEED_ADMIN_PASSWORDoptional | "Demo1234!" | Initial password for the auto-created System Admin. |
Deployment
Sandboxed, per-environment deployments. Each env_id provisions its own Fly.io machine (backend + MCP) with a 1 GB persistent SQLite volume, a sibling Fly.io app running MailDev as the per-env mailbox, an automatically created Cloudflare R2 bucket for database backups, and its own Cloudflare Pages project (frontend) — all wired to is-edustack.org subdomains.
Topology per environment
Backend + MCP server
One Fly.io app per environment (edustack-sandbox-N) runs both Node processes in a single container. A 1 GB volume mounted at /data persists the SQLite database. The MCP server listens on 127.0.0.1:3001 inside the container — only the backend can reach it.
Frontend
One Cloudflare Pages project per environment (edustack-frontend-sandbox-N), built from apps/frontend with VITE_API_URL pointing at the matching backend.
MailDev mailbox
A second Fly.io app per environment (mail-edustack-sandbox-N) runs MailDev. The backend connects to its SMTP on the private 6PN network (mail-edustack-sandbox-N.internal:1025); the web inbox is exposed publicly at mail-sandbox-N.is-edustack.org for demos.
R2 backup bucket
The deploy action creates a Cloudflare R2 bucket per environment (edustack-sandbox-N-backups) and wires the S3-compatible endpoint into the backend. Database backups upload there automatically; if R2 credentials are missing the step is skipped and backups stay on the Fly volume.
Custom domains
Everything lives under is-edustack.org: sandbox-N.is-edustack.org → Cloudflare Pages (frontend), be-sandbox-N.is-edustack.org → Fly.io backend, mail-sandbox-N.is-edustack.org → MailDev. Backend + MailDev get TLS via Fly Let's Encrypt; the frontend is proxied through Cloudflare.
GitHub Actions workflow
Provisioning is driven by .github/workflows/deploy-env.yml. Trigger it from GitHub → Actions → Deploy Environment → Run workflow. Pick an env_id (e.g. 1) and one of the actions below. Every step — Fly apps, R2 bucket, DNS records, Pages project — is idempotent, so you can safely re-run on the same env_id.
deploy
Full provision: create the backend Fly app + 1 GB volume, the MailDev Fly app, the R2 backup bucket, stage secrets, flyctl deploy both apps, attach DNS + TLS, build and push the frontend to Cloudflare Pages. Use for the first run and every subsequent push.
Run workflow → action: deploy, env_id: 1delete
Destroys both Fly apps (backend machines + volume and MailDev), empties and removes the R2 backup bucket, deletes all three CNAMEs, and removes the Cloudflare Pages project. Use when tearing an environment down.
Run workflow → action: delete, env_id: 1GitHub repository secrets
Add these under Settings → Secrets and variables → Actions → New repository secret. The required ones must be present before the first run; the recommended ones get sensible random fallbacks but you should always set them in production. If the R2 keys are missing the deploy step skips bucket provisioning and backups stay on the Fly volume.
| Variable | Purpose |
|---|---|
FLY_API_TOKENRequired | Fly.io API token (account-wide so it can create apps). flyctl auth login, then flyctl auth token. |
CLOUDFLARE_API_TOKENRequired | API token for Pages deploys, DNS edits, and R2 bucket management. Cloudflare → My Profile → API Tokens → Create Token with: Account → Cloudflare Pages: Edit, Account → Workers R2 Storage: Edit, Account → Account Settings: Read, Zone → Zone: Read (is-edustack.org), Zone → DNS: Edit (is-edustack.org), User → User Details: Read. |
CLOUDFLARE_ACCOUNT_IDRequired | Cloudflare account ID. Found in the right sidebar of any Workers / domain overview in the dashboard. |
JWT_SECRETRecommended | Random string (≥ 32 chars) used to sign JWT cookies. Pushed into Fly via flyctl secrets set on every deploy. |
ENCRYPTION_KEYRecommended | AES-256 key — exactly 32 hex characters. Encrypts provider API keys in the SystemSecret table. Losing it makes those rows unreadable. |
MCP_AUTH_TOKENRecommended | Shared bearer token between the backend and MCP server. Generated with openssl rand -hex 32. |
R2_ACCESS_KEY_IDRecommended | S3-compatible access key ID for the R2 backup bucket. Cloudflare → R2 → Manage R2 API Tokens → Create API token (Object Read & Write). Separate from CLOUDFLARE_API_TOKEN. |
R2_SECRET_ACCESS_KEYRecommended | S3-compatible secret access key, returned alongside R2_ACCESS_KEY_ID when you create the R2 API token. Cloudflare shows it once — store it immediately. |
One-time prerequisites
Add the zone is-edustack.org (Websites → Add a site) and point your registrar's nameservers to Cloudflare.
Create a Fly.io account (flyctl auth signup) and confirm your org slug is personal (default for personal accounts). Override FLY_ORG in deploy-env.yml if you use a custom org.
Costs
Each environment is one Fly.io machine (shared-cpu-1x, 512 MB) that auto-stops when idle, plus a 1 GB volume (~$0.15/month) that accrues even while stopped. Fly.io offers a 7-day trial; afterwards a payment method is required. To drop to zero between demos, run the delete action and deploy again later. Realistic cost at demo / low-traffic usage is roughly $1–2 per environment per month. Cloudflare Pages stays on the free tier comfortably.
Full step-by-step in the repository READMEBackend Status & Health
Every backend exposes a public status page, a JSON health endpoint that gates the frontend boot, and full Swagger / OpenAPI documentation. The paths below are relative — prepend them with the backend's base URL for the environment you want to inspect.
https://be-sandbox-1.is-edustack.orgSwap sandbox-1 for any other env_id, e.g. be-sandbox-2.is-edustack.org.Status page
The backend root path renders a lightweight status page that confirms the API is online, names the environment, surfaces the database connection state and Node.js runtime, and links straight into the OpenAPI docs. Use it as a quick "is it up?" check before opening the frontend.
{backendUrl}/Health check & boot gating
The frontend polls GET /api/health on every load and keeps showing the EduStack IS loading screen until the response is healthy. If the backend is cold-starting, mid-migration, or unreachable, the loader stays visible — users never land on a half-booted app. The endpoint also reports uptime, memory, version, commit, and build time so monitoring can scrape it.
{backendUrl}/api/healthSample response
{
"status": "healthy",
"uptime": 7717,
"database": "ok",
"memory": {
"rss": 213,
"heapUsed": 72,
"heapTotal": 78
},
"version": "1.0.0",
"commit": "205ec58b9db0245897b62984e584cb7866ee74c4",
"buildTime": "2026-05-17T15:24:12Z",
"timestamp": "2026-05-17T17:33:30.541Z"
}OpenAPI / Swagger documentation
Every backend ships with interactive Swagger UI covering all modules — auth, init, students, teachers, schools, and the rest. Endpoints are grouped by module, request and response schemas are inferred from DTOs, and you can authorize once via JWT to call live endpoints straight from the browser.
/api/docsSystem Setup
Initialization runs once per environment. Two GitHub Actions deploy toggles decide whether the system bootstraps itself with demo data and whether the login screen exposes a developer helper — the manual System Setup screen only appears when auto-seeding is disabled.
Deploy workflow toggles
Two checkboxes on the Deploy Environment workflow change how the first boot of a sandbox behaves. Both default to ON so a freshly created env_id deploys ready for demos. They have no effect on environments that have already been initialized — re-running the workflow with different values does not rewind the database.
Enable login helper (demo-user picker on login screen) — deploy only
Renders a developer-only picker on the login screen with one-click sign-in for every user.
Auto-seed demo data on first boot — deploy only
Skips the manual System Setup screen and provisions schools, users, schedules, and the System Administrator automatically.
Auto-seeded demo data
When auto-seed is on, the backend bypasses the System Setup screen entirely on first boot and inserts the full demo dataset. A System Administrator account is created automatically and used to bring the rest of the schools online.
Default seed credentials
[email protected]- Password
Demo1234!
Every account generated by the seeder shares the same Demo1234! password. Rotate it (or disable the accounts you don't need) before exposing the environment to real users.
Login helper
While the login helper toggle is on, the login screen renders a picker of every user in the system; clicking a card signs in immediately, no password needed. The shortcut deactivates per-user the moment that user changes their password from their profile — newly hardened accounts fall back to the standard email + password form, even while the helper stays available for everyone else.
Manual first-boot setup
When auto-seed is off, the first request to the frontend lands on the System Setup screen. Pick between a fresh install (create the first System Administrator now) or restoring an existing .sqlite backup.
Fresh install
Create the first System Administrator through the in-app form: name, surname, admin email, password, and confirmation. After submission the system goes live with an empty database — schools and users are then added through the System Administrator console.
Restore from backup
Pick the "Restore from backup" tile and upload a previously exported .sqlite file. The current database is replaced with the contents of the backup; the upload button stays disabled until a file is selected.
User Authentication
The login screen renders four variants — login helper on/off crossed with SSO available or not — plus a password reset flow. Which variant a user sees depends on the deploy-time login helper toggle and on whether the System Administrator has registered any SSO providers.
Login helper
Developer-only picker on the login screen for one-click sign-in as any user. Controlled by the auto-deploy toggle and self-deactivates per user once that user changes their password from their profile.
Email & password
Standard secure authentication using hashed passwords (Argon2) stored in the SQLite database. Always available — even when the helper is on, users can switch to the regular form.
SSO integration
Enterprise-grade login via Google, GitHub, and Microsoft. SSO buttons only appear when the System Administrator has configured at least one provider; otherwise the screen shows email + password only.
Password reset
Three-step forgot-password flow accessible from the login screen. (1) The user requests a reset by entering their email. (2) A tokenized reset link is delivered via the configured SMTP server — MailDev in sandbox environments. (3) Following the link opens a Set New Password form with a new + confirm field. The token is valid for the duration configured in System security.
Helper + SSO
Helper, no SSO
Email & password + SSO
Email & password only
Password reset request
Set new password
Reset email (MailDev)
AI Tutor
Conversational AI assistant embedded in every role. The tutor is grounded by the system prompts (System Administrator → System Prompts) so it stays scoped to school content. Pick a provider/model (Google Gemini, OpenAI, Anthropic Claude, OpenCode.ai — whichever the System Administrator has configured), ask a question, and the answer streams back in the same window. Available to students, parents, teachers, deputies, headmasters, and system admins.
AI Tutor — empty conversation
Pick a provider / model
Ask a question
User Roles
Below is the per-role walkthrough. Permissions overlap heavily in code, but each role uses the system in a different way. The cards below summarize what each role actually does day-to-day.
Headmaster & Deputy
Primary school management — academic year setup, classes and subjects, schedule planner, curriculum, substitutions, bulk user invites. They also have access to everything Teacher does.
Teacher
Active work in the classroom — running lessons, grading (numeric + verbal with AI polish), attendance, class book, lesson preparations, and direct messaging.
Student
View-only consumer — sees their own grades, schedule, materials, attendance, community posts, and chats with the AI Tutor. Nothing they submit changes school state.
Parent
Mostly view-only like the student (sees the child's grades, schedule, messages) plus one active responsibility: submitting absence excuses for the teacher to approve.
System Administrator
The ultimate orchestrator. The sidebar exposes five top-level destinations — Dashboard, Schools, Users, System Settings, and System Prompts — and every administrative action on the platform lives in one of them.
Core Functions
Multi-tenant school lifecycle, system-admin promotion, AI provider keys and usage analytics, SSO identity providers, security hardening, audit log, database backups, AI-driven test data generation, and a read-only catalogue of every prompt the system sends to AI providers.
School management
The Schools panel is the multi-tenant control center. Each row shows a school with headmaster and deputy badges; the row actions cover entering the tenant as any role (system admin, headmaster, or deputy) for support work, editing metadata and the SSO email-match policy, and a type-to-confirm delete that wipes every record tied to the tenant. Creating a school is a single modal that either provisions a brand-new headmaster on the spot or links an existing user.
School tenants list
Create school — new headmaster
Create school — existing user
Edit school metadata
Enter as role popover
Delete school — empty confirmation
Delete school — name typed
System administrators
Lists every user with global system privileges and lets you promote new ones. Adding an admin checks the email — if the user already exists, they are promoted in place; otherwise the form expects first and last name and a fresh account is provisioned. Removal deactivates the account and revokes admin rights.
System admin directory
Promote — new user
Promote — existing user
Remove administrator
System settings
All global configuration lives here under six tabs: AI management, SSO integration, System (security), Monitoring, Backups, and Test data. Each tab is described below.
AI management
Single screen for AI provider keys (Google Gemini, OpenAI, Anthropic Claude, OpenCode.ai) plus current-month usage analytics — total tokens, input/output split, request count, top schools, per-provider breakdown, and daily usage chart. Each provider row links straight to its developer portal so an admin can obtain the key. Keys are encrypted at rest (AES-256) and removed via a confirmation dialog.
AI management dashboard
Delete API key confirmation
SSO integration
Configure OAuth identity providers (Google, GitHub, Microsoft, Apple). The page shows the exact callback URL the backend expects ({backendUrl}/api/auth/callback/[provider]) plus direct links to each provider's developer portal. The edit modal stores Client ID and Client Secret (encrypted), exposes an enable/disable toggle, and lets you delete the configuration entirely.
SSO providers overview
Google OAuth configuration
GitHub OAuth configuration
Delete provider configuration
System security
Three knobs control login hardening: maximum failed attempts before lockout, lockout duration in minutes, and reset-token validity in minutes.
Security parameters
Monitoring & audit log
Live backend status (uptime, database, memory, version, commit, build time) sits above the system audit log. The audit table records every high-impact action — admin promotion, logins, entity edits — and supports filtering by date range, action type, entity, and user id.
Monitoring + audit log
Database backups
Lists every backup of the Cloudflare D1 (SQLite) database stored in the per-environment R2 bucket. Each row exposes download, restore, and delete actions. Manual backups are named via the create modal; restoring replaces the live database with the chosen snapshot.
Backup catalogue
Create a manual backup
Delete backup confirmation
Test data generator
Generates a complete school with realistic test data: pick the school type (1st stage, 1st & 2nd stage, 8-year gymnázium, or 4-year gymnázium), set teacher / student / parent counts split between active and invited, and toggle which modules to seed (subjects, schedule, classification, messages, attendance, report cards, community). The AI button generates a realistic Czech school name. Below sits a Danger zone — wipe a single school's data or the entire system.
Test data generation form
School type picker
Generated school summary
System prompts
Read-only catalogue of every prompt the backend uses to talk to AI models — chat base instruction, chat for system admins, school-name generator, text refinement, thematic plan generator, student recommendations, class performance analysis, and the rest. Each entry shows the identifier, owning service, short description, and full template so admins know exactly what gets sent to providers.
Prompt catalogue
Headmaster & Deputy
Headmaster and Deputy share the same backend permissions and use the same shared classroom toolkit as Teacher (Schedule, Grading, Attendance, Class Book, Messages, Community). Their primary job, though, is running the school — academic year setup, classes and subjects, the schedule planner, curriculum, substitutions — covered in the School Management chapter. The pages below document the shared toolkit; teacher-specific walkthroughs live in the Teacher chapter that follows. Note: 'School Administrator' is not a real role — it's a label the System Administrator can pick when entering a tenant via 'Vstoupit jako…', with the same permissions as Headmaster or Deputy.
Core Functions
Same toolkit as Teacher (schedule, grading, attendance, class book, messages, community) plus the full School Management section (academic year setup, users, classrooms, ŠVP, schedule planner, substitutions, report cards, events).
Role colors — instant identification
Every school-staff role gets its own accent color so you always know which role the current session is in (especially useful when a System Administrator hops between roles via 'Vstoupit jako'). Headmaster and Deputy see a school-wide dashboard — today's attendance, weekly average, pending excuses, total students / classes / teachers / subjects, plus recent members and upcoming events. Teacher gets a leaner, personal dashboard focused on the next lesson, missing class-book entries, and unread messages. The differences are: Headmaster — blue (and the 'School Administrator' override inherits the same blue). Deputy — a lighter sky. Teacher — red.
Headmaster · blue — school-wide overview (attendance, average, students, classes, teachers, recent members, upcoming events)
Deputy · sky — identical school-wide overview, only the accent color differs
Teacher · red — personal view focused on the next lesson, missing class-book entries, and unread messages
Schedule
View-only timetable. Switch tabs to see your own schedule, an entire class, a specific teacher, or a classroom — all filterable by academic year and semester (or 'All' to see both halves).
My Schedule (default tab)
Class timetable (1.A)
Pick a teacher
Teacher timetable
Pick a classroom
Classroom timetable
Academic year switcher
Print-friendly room timetable
Grading
Per-class grade book filterable by academic year, class, and semester. The empty state shows every student × subject cell with a quick '+' to add a grade. The New Grade modal accepts a numeric mark (1–5 with optional weight) plus a written verbal assessment; 'Polish with AI' generates three drafts — formal, encouraging, concise — that the user can accept or regenerate with extra instructions. Clicking a student's name opens their per-subject overview with all grades, weights, dates, and the saved verbal assessments.
Grade book — initial empty state
Grade book with entered grades
Pick another class
New grade — empty form
New grade — filled with verbal text
AI suggestions — generating drafts
AI suggestions — formal / encouraging / concise
Student overview — per-subject grades
Attendance
Record presence per class and date, see per-student statistics, manage parent excuses (approve / reject), and review escalations for chronic absences. The Excuses tab lists pending requests with the parent, dates, and reason; the row turns green when approved or red when rejected.
Pending parent excuses
Excuses after approval / rejection
Class book
Electronic class book wired to the schedule. Pick a class and date to see what was taught each lesson, sign entries, and print the day's records for the chosen range of dates.
Class book — daily records
Messages
1:1 messaging accessible to every role (student, parent, teacher, deputy, headmaster). Search recipients by name or email and start a conversation. Headmaster and Deputy additionally see a 'Hromadná zpráva' (broadcast) button that delivers a single message to an entire class or the whole school.
Empty inbox
New message — recipient picker
Sent conversation
Broadcast — entire school (H/D only)
Broadcast — single class (H/D only)
Inbox after broadcast
Community
School-wide bulletin, polls, and events. Anyone can read; teachers, deputies, and headmasters can create posts. Polls support single- or multi-choice voting with live percentages. Events show YES / MAYBE / NO RSVP counts and can be created with title, description, time range, and location — the new event then appears inline in the events list.
Bulletin board
Single-choice poll
Multi-choice poll
Events calendar — no RSVPs
Events after RSVPs
Create new event (modal)
Events list after creating a new event
School management
Additional toolkit available only to Headmaster and Deputy (and, by extension, a System Administrator using 'Vstoupit jako'). Covers the school-wide configuration that sits behind the daily classroom work — academic year setup, classes and subjects, schedule planner, curriculum, substitutions, and bulk user invitations.
Core Functions
Academic year & semester rollover, class and subject management, curriculum versioning (SVP/RVP mapping), schedule planner with collision detection, substitutions, bulk user invitations.
Academic year setup
Roll the school forward: open a new academic year, define its semesters, and tick which modules should be live for the year.
Academic year setup
Users
Local user directory. Invite teachers, students, and parents one at a time or in bulk via CSV import; open a user's detail to edit profile information, assign classes, and change roles.
User directory
Invite a user
User detail
Assign user to classes
Bulk CSV import
Change user role
Buildings & classrooms
Define the physical layout of the school — buildings, floors, and individual classrooms. Each classroom can be edited with capacity, equipment, and the floor it sits on.
Classrooms list
Create a classroom
Buildings & floors
Classroom detail
Bell schedule
Configure lesson start and end times for the school day. Used by every timetable and class-book view.
Bell schedule configuration
Framework curriculum (RVP)
Browse the national Framework Education Programme (RVP) — domains, competencies, and outputs. Used as the upstream source when building the school's ŠVP and thematic plans.
RVP domains overview
RVP competency detail
School curriculum (ŠVP)
Define the school's own curriculum on top of RVP: which subjects each grade has, with what weekly hour allocation, mapped to RVP competencies. The ŠVP is versioned — you can publish a new version for the upcoming year while keeping the active one untouched.
ŠVP overview
Per-grade subject allocation
Subjects in the ŠVP
ŠVP versions
Curriculum detail
White Book
The ministerial White Book — the strategic document underpinning the Czech educational policy. Surfaced here as reading material for staff designing the ŠVP and thematic plans.
White Book viewer
Schedule planner
Build the school's weekly timetable. Drag subjects onto class / teacher / room slots; the planner flags collisions in real time. The result feeds the read-only Schedule view that every role uses day-to-day.
Schedule planner
Substitutions
Manage daily absences and reassignments. Pick the affected lessons and assign a substitute teacher, change the room, or swap the subject — affected users see the change in their personal schedule immediately.
Substitutions list
Substitution detail
Schedule comparison
Diff two schedule versions side-by-side. Useful when rolling a semester or applying bulk changes — see exactly what moved before publishing the new version.
Schedule comparison overview
Per-class diff
Thematic plans
Per-subject teaching plan for the year. Define topics, hours, and which RVP outputs they cover. Teachers reference the plan from their lesson-prep screen; the progress chart shows how far the actual taught material has advanced against the plan.
Thematic plans list
Create a thematic plan
Plan detail
Plan progress chart
Lesson preparations
Per-lesson teaching notes. A preparation links to a thematic-plan topic and is reused when signing the class book. Optional AI assistant generates a draft preparation from the topic and grade level.
Lesson prep list
Preparation detail
Teaching materials
Shared library of files attached to subjects, thematic plans, or individual preparations. Visible to teachers of the subject; can be exposed to students from a lesson preparation.
Materials library
Material detail
Report cards (vysvědčení)
End-of-semester deliverable. Pick the template, generate report cards for the chosen class, track per-student progress, and export the final PDF batch.
Report-card batches
Choose template
Assign to classes
Generation progress
Export PDFs
Individual report card
Clubs
After-school activities — name, schedule, capacity, leading teacher, and the list of enrolled students. Each club has its own attendance and announcements stream.
Clubs list
Club detail
School events
School-wide calendar (trips, parent meetings, holidays). Create with title, date range, location, and audience; the event then surfaces in the community Events tab for the affected users.
Events list
Create event
Calendar view
Event detail
Disciplinary measures
Record commendations, reprimands, and formal disciplinary measures issued to students. Each entry is attached to a student's profile and shows up in their parent's view.
Disciplinary measures list
Measure detail
School audit log
School-scoped audit log — every action that mutates school data is recorded with actor, timestamp, and entity. Mirrors the system-wide audit log but restricted to this tenant.
School audit log
Teacher
Active classroom worker — uses the same shared toolkit as Headmaster and Deputy (Schedule, Grading, Attendance, Class Book, Messages, Community — see the previous chapter) but focuses on active subject and grade work rather than school-wide configuration. Teachers see a leaner sidebar without the School Management section, and their accent color is red so any active session is instantly recognisable.
Core Functions
Active classroom work: leading subjects, recording grades with AI-polished verbal assessments, signing class-book entries, tracking attendance, communicating with students and parents, contributing to the community feed.
Teacher walkthrough
Walkthrough of the teacher's day-to-day work — schedule across views, grading workflow with the new-grade modal and AI-polished verbal assessment, attendance and parent excuses, class-book entries, messaging, and the community feed. Teachers see a leaner sidebar than Headmaster / Deputy — no 'Správa školy' submenu — but everything they need for running classes is one click away.
Schedule — own weekly timetable
Schedule — switch to a class view
Schedule — pick another teacher
Schedule — classroom view
Grading — class grade book
Grading — pick another class
Grades — overview for the selected student
Attendance — student presence in class
Attendance — daily presence record per class
Class book — sign today's lessons
Messages — write to a student or parent
Parent
Mostly mirrors the Student view of their child — grades, schedule, classification details, community announcements, AI Tutor — but adds one active responsibility: submitting parental excuses for absences. The Teacher / Deputy / Headmaster then approves or rejects each excuse from the Attendance tab.
Core Functions
View child's grades and progress, view personal schedule and substitutions, submit and track parental excuses for absences, message teachers and school management, participate in community polls and event RSVPs.
Parent walkthrough
Walkthrough of the parent's daily flow — children's and teachers' schedules, grade overview, excuse submission, class book, messaging with the school, and community events. The accent color is green so parents instantly recognize their role.
Schedule — parent sees the timetable of the children they are linked to and the teachers' timetables
Schedule — teacher selection detail
Grades — overview with a picker for each child the parent is linked to
Attendance — submit a new parental excuse for the selected child
Class book — overview of activities for the selected day
Messages — module for sending and reading messages between users
Community — overview of planned events with the option to RSVP
Student
View-only consumer of the system. Sees own grades and per-subject classification, personal schedule with substitutions, attendance and disciplinary records, teaching materials, community posts and event RSVPs, and chats with the AI Tutor. Nothing the student submits changes school-side state — even the AI Tutor conversation is local to the student.
Core Functions
Personal dashboard with grade overview, interactive daily and weekly schedule, community messaging and polls, access to teaching materials, AI Tutor for educational support.
Student walkthrough
Walkthrough of the student's view — personal timetable, grade overview, parental-excuse status, class book, messaging, polls, the community feed (read-only for students), and events. The accent color is orange so students instantly recognize their role.
Schedule — student's timetable with subject detail
Grades — overview of the student's academic results
Parental excuses — submitted excuses and teacher approval / rejection status
Class book
Messages — inbox overview plus chat window for talking with other users
Polls — vote and view results
Community — read-only feed of school announcements
Events — invitations with the option to RSVP