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.

Application Modules

The system is designed as a modular platform where each component serves a specific pedagogical or administrative purpose.

System Administration

NestJSSQLite (Fly volume)AES-256 Encryption
How it's built

A set of core services for multi-tenant school lifecycle management, global configuration, and security auditing.

Core Benefit

Enables global platform orchestration, secure tenant isolation, and centralized resource management.

Auth & SSO

JWTArgon2OAuth2
How it's built

Secure authentication layer with support for traditional credentials and enterprise SSO (Google, GitHub, Microsoft).

Core Benefit

Ensures data integrity and robust Role-Based Access Control (RBAC) across the entire platform.

School Registry

SQLiteBatch SQLCSV Engine
How it's built

Core database module for managing students, staff, classes, and physical building structures.

Core Benefit

Serves as the central 'Source of Truth' for all other educational and administrative modules.

Interactive Scheduling

Collision Detection AlgorithmsReact DnD
How it's built

Sophisticated engine for timetable creation with real-time conflict detection and substitution management.

Core Benefit

Automates the most complex school administrative tasks and eliminates scheduling human errors.

Grading & Evaluation

Weighted Math EnginePDF Export
How it's built

Comprehensive system for tracking marks, weighted averages, and complex verbal evaluations.

Core Benefit

Provides immediate academic transparency for teachers, students, and parents.

Pedagogical AI Assistant

Google GeminiOpenAIAnthropic
How it's built

Deep integration of LLMs into teacher workflows for lesson planning, material generation, and report polishing.

Core Benefit

Significantly reduces administrative burden on teachers while bringing modern AI tools to the classroom.

MCP API (AI Integration)

Model Context ProtocolSSETool-calling
How it's built

A standardized bridge that connects external AI agents with live system data through a secure tool-based interface.

Core Benefit

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.

1

Tenancy & Identity

Multi-school tenancy, users, roles, parent-student links, SSO identities, and audit log.

2

Academic Structure & Curriculum

Academic years, semesters, grade levels, student enrollment, curriculum versions, subject templates and instances, RVP competencies.

3

Workload & Physical Space

Teacher and staff workload, subject assignments, buildings, rooms and room sharing between schools.

4

Schedule & Class Book

Lesson timetable, substitutions, recurring events, snapshots, and the digital class book with teacher signatures.

5

Attendance, Absences & Grading

Attendance records, parent absence excuses, grades, report cards, behavior and competency grades, educational measures, commission exams and classification deadlines.

6

Planning & Teaching Materials

Thematic plans split by week, lesson preparations and uploaded teaching materials linked to subjects and grade levels.

7

Communication & Community

Conversations, messages and attachments, notifications, bulletin posts, polls with options and votes, calendar events with RSVPs, and school-wide events.

8

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.

allowednot allowed
1

Tenancy & Identity

10 operations
OperationSysAdmHdmDepTchParStu
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)
2

Academic Structure & Curriculum

9 operations
OperationSysAdmHdmDepTchParStu
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
3

Workload & Physical Space

6 operations
OperationSysAdmHdmDepTchParStu
Manage classrooms
Manage buildings and rooms
Share rooms across schools
Manage teacher workloads
Manage staff workloads
Assign staff to subjects
4

Schedule & Class Book

7 operations
OperationSysAdmHdmDepTchParStu
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
5

Attendance, Absences & Grading

14 operations
OperationSysAdmHdmDepTchParStu
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
6

Planning & Teaching Materials

4 operations
OperationSysAdmHdmDepTchParStu
Manage thematic plans
Manage lesson preparations
Upload teaching materials
View teaching materials
7

Communication & Community

9 operations
OperationSysAdmHdmDepTchParStu
Send / receive messages
Create bulletin post
View bulletin
Delete bulletin post
Create poll
Vote in poll
Create calendar event
RSVP to event
View notifications
8

System, AI & Misc

8 operations
OperationSysAdmHdmDepTchParStu
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.

1

Initial system setup

First-run wizard: create the first system admin from scratch, or restore the system from a SQLite backup.

2

Login (credentials + SSO)

Local credential authentication (Argon2 + JWT cookie) and SSO via Google / GitHub / Microsoft with email-match policy.

3

Generate test data

System admin seeds an entire school — classes, users, schedule, grades, attendance — optionally using AI for school and student names.

4

Backup and restore

Three flows in one diagram: the nightly cron backup, an ad-hoc admin backup, and restoring the database from R2.

5

AI-assisted generation

Teacher requests a thematic plan or report-card polish; backend decrypts the provider key, calls the LLM, and logs token usage.

6

Schedule substitution

Deputy assigns a substitute teacher/room; collision detector validates against existing schedule before persisting and notifying affected users.

7

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

1

Clone the repository

git clone '<repo>' && cd edu-stack-is-sandbox
2

Copy the env template

cp .env.example .env
3

Generate the two required secrets

openssl rand -base64 64  # JWT_SECRET
openssl rand -base64 32  # ENCRYPTION_KEY
4

Install workspaces

npm install
5

Initialise the local SQLite database

npm run db:init
6

Start backend, frontend and MCP server

npm run dev

Default URLs after npm run dev

Web applicationhttp://localhost:5173
Backend REST APIhttp://localhost:3000
Swagger / OpenAPIhttp://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.

1

Security (required)

VariableDefault / examplePurpose
JWT_SECRET
required
openssl rand -base64 64Symmetric key used to sign and verify the JWT cookies issued at login. Rotating it logs everyone out. MUST be unique per deployment.
ENCRYPTION_KEY
required
openssl rand -base64 32AES-256 key used to encrypt sensitive columns (provider API keys in SystemSecret, etc.). Losing it makes encrypted rows unreadable.
SETTINGS_ENCRYPTION_KEY
optional
openssl rand -base64 32Optional separate key used by the legacy SystemSettings table. Falls back to ENCRYPTION_KEY when empty.
2

Login helper (dev only)

VariableDefault / examplePurpose
ENABLE_LOGIN_HELPER
optional
trueWhen true, the login screen shows a panel with one-click demo users. Always set to false in production.
LOGIN_HELPER_ROLES
optional
SYSTEM_ADMIN,ADMIN,TEACHER,DEPUTY,PRINCIPAL,STUDENT,PARENTComma-separated allow-list of roles the helper surfaces. Lets you hide STUDENT/PARENT in a teacher-only demo, for example.
DEMO_PASSWORD
optional
"Demo1234!"Password every seeded demo user is given. Used by the seeder; only relevant when AUTO_SEED is on.
3

Database

VariableDefault / examplePurpose
DB_ADAPTER
recommended
sqliteSelects the database driver. Keep "sqlite" — better-sqlite3 reads a local file in dev and the Fly volume at /data/edustack.db in production.
DATABASE_URL
recommended
file:./dev.dbPath to the local SQLite file. Used by Prisma CLI tools (introspection, migrations); the runtime opens the file directly via better-sqlite3.
4

Email / SMTP

VariableDefault / examplePurpose
SMTP_HOST
recommended
localhostHostname of the SMTP server. In local dev this is the bundled MailDev (npm run dev starts it on 1025).
SMTP_PORT
recommended
1025Port of the SMTP server. 1025 for MailDev, 587/465 for production providers.
SMTP_USER
optional
SMTP username. Empty for MailDev; required for SendGrid / SES.
SMTP_PASS
optional
SMTP password / API key. Always pass via secret manager in production.
MAIL_FROM
recommended
[email protected]From: address used on every transactional email (invites, password resets, notifications).
5

Services and networking

VariableDefault / examplePurpose
PORT
recommended
3000Port the NestJS backend listens on.
MCP_PORT
recommended
3001Port the MCP server listens on.
CORS_ORIGIN
recommended
http://127.0.0.1:5173Allowed origin for the REST API. Set to the frontend URL.
FRONTEND_URL
recommended
http://127.0.0.1:5173Public URL of the frontend. Used to build links inside emails (invites, password reset).
MCP_SERVER_URL
recommended
http://127.0.0.1:3001/sseWhere the backend looks for the MCP server. The /sse suffix is the MCP transport endpoint.
6

MCP server hardening

VariableDefault / examplePurpose
MCP_HOST
recommended
127.0.0.1Bind 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_TOKEN
optional
openssl rand -hex 32Shared bearer token. When set, /sse, /message and /v1/chat/completions require Authorization: Bearer '<token>'. The backend forwards it automatically.
MCP_CORS_ORIGIN
optional
Comma-separated CORS allow-list. Leave empty to disable CORS (correct for loopback-only deployments).
7

AI providers

VariableDefault / examplePurpose
OPENCODE_BASE_URL
optional
http://127.0.0.1:3001/v1Base URL of the OpenAI-compatible OpenCode provider. Defaults to the local MCP server; in production MUST be https://.
OPENCODE_API_KEY
optional
Bearer token for the OpenCode provider (when fronted by an authenticated MCP).
GOOGLE_AI_API_KEY
optional
Google Gemini API key. Either GOOGLE_AI_API_KEY or GEMINI_API_KEY is accepted.
GEMINI_API_KEY
optional
Alias of GOOGLE_AI_API_KEY for historical reasons.
OPENAI_API_KEY
optional
OpenAI API key. Used when the OpenAI provider is selected in system settings.
ANTHROPIC_API_KEY
optional
Anthropic API key. Used when the Anthropic provider is selected.
8

Backups (Cloudflare R2)

VariableDefault / examplePurpose
R2_ENDPOINT
optional
https://<account>.r2.cloudflarestorage.comCloudflare R2 S3-compatible endpoint URL. Leave empty to fall back to local file backups in BACKUP_DIR.
R2_ACCESS_KEY_ID
optional
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_KEY
optional
R2 secret key. Treat as a secret.
R2_BUCKET_NAME
optional
edustack-backupsName of the R2 bucket to write backups to.
BACKUP_DIR
optional
data/backupsFilesystem path used when R2_* variables are empty. Created on first backup.
AUTO_BACKUP
optional
falseIf true, the BackupScheduler creates a nightly backup automatically.
9

Development and seeding

VariableDefault / examplePurpose
NODE_ENV
recommended
developmentStandard Node environment. Set to "production" outside of local dev.
AUTO_SEED
optional
trueIf true, the seeder runs on the first start of a fresh database. Creates the demo school and the default System Admin.
SEED_FILE
optional
Path to an alternative seed JSON. Empty uses the bundled default scenario.
SEED_ADMIN_EMAIL
optional
[email protected]Email of the auto-created System Admin.
SEED_ADMIN_FIRST_NAME
optional
SystemFirst name of the auto-created System Admin.
SEED_ADMIN_LAST_NAME
optional
AdminLast name of the auto-created System Admin.
SEED_ADMIN_PASSWORD
optional
"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: 1

delete

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: 1

GitHub 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.

VariablePurpose
FLY_API_TOKEN
Required
Fly.io API token (account-wide so it can create apps). flyctl auth login, then flyctl auth token.
CLOUDFLARE_API_TOKEN
Required
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_ID
Required
Cloudflare account ID. Found in the right sidebar of any Workers / domain overview in the dashboard.
JWT_SECRET
Recommended
Random string (≥ 32 chars) used to sign JWT cookies. Pushed into Fly via flyctl secrets set on every deploy.
ENCRYPTION_KEY
Recommended
AES-256 key — exactly 32 hex characters. Encrypts provider API keys in the SystemSecret table. Losing it makes those rows unreadable.
MCP_AUTH_TOKEN
Recommended
Shared bearer token between the backend and MCP server. Generated with openssl rand -hex 32.
R2_ACCESS_KEY_ID
Recommended
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_KEY
Recommended
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 README

Backend 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.

Base URL (example for sandbox-1)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/health

Sample 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/docs

System 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

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