Architecture & Infrastructure

Architectural principles

• Simple by default. One deployable process; no container orchestration, no message brokers, no microservices at this scale.
• Provider-agnostic. Stack runs on any Linux VPS, cloud VM, or on-prem appliance; no proprietary cloud lock-in.
• Modular seams. Content source, AI provider, email, and persistence are isolated modules, so each can be swapped independently.
• Stateless app, stateful DB. All durable state lives in PostgreSQL; the Node process holds no session state in memory.
• Secrets outside the repo. All credentials come from an environment file that is never committed.

At a glance

Frontend

• React SPA built by Vite to static assets, served by the same Node process — no separate web server or CDN required.
• AuthContext holds the logged-in user; the API is called with credentialed fetch (session cookie).
• Four-language UI (sr/en/fr/pt) via static translation modules.

Backend

• Routers mount under /api, one per audience — auth, student, teacher, school administrator, platform administrator — plus a /health endpoint for uptime checks.
• Business logic lives in service modules (LLM, Sheets, email, auth, DB) — routers stay thin.
• The interview state machine (next question, scoring, summary) lives server-side; the AI never drives flow.
• Statistics are a fourth layer, deliberately separated. stats/rules.js holds the decisions and touches nothing — which window a period means, what it compares against, when a cohort is too small to publish — so they are testable as functions rather than as fragments of a query. db/stats.js is only SQL. stats/report.js runs them together. One router mounts twice, at /api/platform/statistics and /api/admin/statistics, and takes its scope from the actor rather than the request.

Tenancy

• organizations — slug, name, country, default language, and a status that blocks sign-in when suspended.
• users.org_id — required for every role except super_admin, which must have none. Both directions are a CHECK constraint, not a convention.
• user_invitations.org_id — an invitation carries the organisation it was issued for, so accepting a link cannot place someone in a school nobody chose.
• groups, group_teachers, group_students — classes within a school. Built and deliberately empty. Scoping is additive: a teacher with no group assignment sees their whole school, so an empty table behaves exactly as if groups were switched off.
• org_settings — one row per school, created lazily: the paragraphs of the privacy notice only a school can supply (controller identity, data protection officer, lawful basis, retention periods, supervisory authority) and the support contact its students are shown. Kept off organizations deliberately — that row is read on every request through loadActor, and a data protection officer's telephone number has no business being carried through all of them to serve a page opened twice a year.
• platform_settings — a single row, enforced by a boolean primary key with a CHECK, holding what every school inherits: the interview limits and the platform's own support address. A school overrides a limit by setting its own; NULL means "whatever the platform says".
• users.status — active or suspended. Two values and not three: to the person holding the account, it is either usable or it is not.

Content

• org_content_source — which spreadsheet a school imports from, and the result of the last connection test. No credentials are stored: access is granted by sharing the sheet with the platform's service account.
• content_versions — one row per import, at most one current per school.
• content_scenarios, content_questions, content_rubrics — keyed by version. An import never overwrites; it adds a version and makes it current, so reverting a bad import is a flag, not a reconstruction.
• interview_sessions.content_version_id — the pin, ON DELETE RESTRICT.

Accountability & rights

• audit_log — every staff read of a student's record: actor, action, subject, time. It holds no content, and survives the deletion of the account it describes, so an erasure cannot quietly erase the evidence that the data was read. Its CHECK-constrained action now also admits suspend and reactivate: suspension is done to a data subject and nothing else would record who did it. Reactivation is logged for the same reason — an account suspended and quietly restored is the shape of a mistake.
• data_requests — erasure requests as rows with a stored due date, because Article 12(3) starts a one-month clock and an inbox has neither a due date nor evidence.
• answer_criterion_scores — per-competency scores as rows rather than inside the JSON, so reporting is a query and the numbers survive encryption of the prose.
• answer_feedback.answer_char_count — kept outside the text it measures, for the same reason.

Supporting

• session — the connect-pg-simple cookie-session store, auto-created. Note it stores sess as json, not jsonb, which is why ending somebody's open sessions matches on sess ->> 'userId' and never ->: there is no equality operator against jsonb.
• password_resets — single-use, one-hour tokens, stored as a hash. The only self-service recovery route in the platform, and therefore the reason an account on an address that receives no mail cannot recover itself.
• transcription_calls — one row per dictation sent to Whisper: model, audio seconds, and the cost, CO₂ and water estimates that go with it. No audio and no transcript. The recording is held in memory for one upstream call and dropped, so there is no recording of a minor's voice anywhere in this system — which is what makes the privacy notice for that feature short.
• Per-message llm_model, token, cost, CO₂ and water columns — the foundation for cost & sustainability reporting. Costs are estimates from the retail catalogue, never billed amounts, and carry the rate-table version that produced them.

Integrity & performance

• Enumerations enforced by CHECK constraints (role, status, language, sender, message_type).
• Cascade deletes keep sessions, messages, and feedback consistent when a user is removed.
• Composite indexes on (student_id, started_at) and (session_id, created_at) for the common list/replay reads, and (student_id, scenario_id) for the interview-limit check that runs on every attempt to start one.

Scaleway — LLM

• Qwen instruct model via the OpenAI-compatible chat API, in JSON-object mode.
• Output validated against Zod schemas (feedback & summary); one repair retry with the specific validation errors on failure.
• Low temperature for reproducible scoring; model + token usage recorded per call.

Google Sheets — Authoring & import

• A spreadsheet is the human-friendly surface where school staff write scenarios, questions, and rubrics.
• An admin-triggered import reads the sheet (service-account JWT via google-auth-library), validates rows with Zod, and upserts them into PostgreSQL.
• After import the app serves all content from the database — the Sheets API is never called during a student or teacher request, so a Sheets outage cannot affect live sessions.

Email — Resend or SMTP

• Sends transactional invitation and password-reset mail with a hashed, single-use token link.
• Two transports, and MAIL_TRANSPORT chooses. A host may legitimately carry the configuration for both, so the choice is declared rather than inferred from which variables happen to be set — inference is how a host ends up sending through the transport nobody meant to use, with two plausible explanations and only one of them looked at.
• SMTP, through the school’s own mailbox. That address both sends and receives, which is what an invitation telling a fifteen-year-old to click a link needs: somewhere the reply goes to a person. Resend remains supported and unused — kept as the second option for a school with no mail server of its own, not as the default. The privacy notice names only the providers that actually hold data, so it no longer lists a mail service at all: the mailbox belongs to the same provider as the servers.

Resilience posture

• The live request path depends on only the database and the LLM; content is local, so a Sheets outage cannot affect sessions.
• LLM failures surface as clean API errors, not crashes; a timeout and bounded retry prevent a slow upstream from hanging a request.
• Import failures are isolated to the admin import action and never reach end users.
• Secrets for all integrations are injected via the environment file, never in code.

Filesystem layout

• /opt/apps/rise/current — the deployed Git checkout (working tree).
• /opt/apps/rise/shared/.env — secrets & config, outside the repo.
• frontend/dist — the built SPA served by Node.
• /var/log/rise/app.log — combined stdout/stderr.

Process supervision (systemd)

• Runs as the unprivileged deploy user; Restart=always with a 5s backoff.
• Graceful shutdown on SIGINT with a 20s stop timeout.
• Config injected via EnvironmentFile — the same file the deploy script sources for migrations.

In place today

• TLS termination at nginx; app binds to loopback only.
• bcrypt-hashed passwords; opaque, httpOnly, secure, SameSite cookies.
• Server-side authorization with per-resource ownership checks.
• Invitation-only registration via hashed single-use tokens.
• Secrets in an environment file outside the repository; service-account keys git-ignored.
• Parameterised SQL throughout (no string-built queries).
• Request body size capped at the proxy (10 MB).

Added since — built

• Audit log of every teacher read of a student record, holding no content and surviving the deletion of the account it describes.
• GET /api/me/export — a person downloads their own data immediately. No administrator can export anyone else's; that endpoint was removed.
• Erasure requests as a queue with a stored due date, and a guarded delete that counts what it destroys without showing any of it.
• Privacy notices in the product, versioned in git, separate texts for students and staff.
• Organisation isolation — a teacher reaches only their own school's students.
• A DPIA (DPIA.md) and a transfer pack drafted for the three schools' advisers.
• Database access logging, so a maintenance session at the psql level is evidenced too — the application log cannot see it.
• Account suspension — reversible, destroys nothing, enforced at sign-in and on every request, and audited in both directions.
• Self-service password reset — single-use hourly tokens, and a response that does not differ between a known and an unknown address.
• A teacher's invitation cannot carry a role. Enforced by the shape of the schema rather than by validating a value: the field is simply absent, and because z.object strips what it does not declare, a body carrying "role": "admin" arrives at the handler without it. A test fails if the field is ever added — validating it would let a teacher mint an administrator of their own school with nothing on screen looking different.
• Per-student interview limits — attempts per scenario, a total, and a per-scenario waiting period, each a platform default a school may override. A cost ceiling as much as a pedagogical one: every answer is two model calls.
• The privacy notice is completed by the school rather than shipping with <placeholder> text visible to students — see the data model note on org_settings.

Still outstanding

• Encryption at rest for student_answer and feedback prose. Unblocked — the scores and answer length were moved out of the JSON so they survive it — and scheduled after the infrastructure migration, so a key that must never be lost is not introduced during a database move.
• Retention. The periods are no longer outstanding: each school now sets them itself, on the privacy notice page, and the notice states them in its own language. What is still outstanding is the deletion job that reads them — nothing expires today, and a period on that page is a published promise the platform does not yet keep on its own.
• Scheduled backups. Designed, not built. Dumps are taken by hand before releases and at no other time — the most urgent item in the project.
• Row-level security behind the application scoping.
• Minors' safeguards: a feedback safety check for the model's tone. Not consent — the lawful basis is Article 6(1)(e), public task, which is what makes Article 8's digital age of consent inapplicable.

Today

• Health. GET /health returns a simple OK for uptime checks and proxy probes.
• Logs. Combined stdout/stderr appended to /var/log/rise/app.log; deploy output visible via journalctl.
• LLM accounting. Model and token counts recorded per AI message for cost visibility.
• Recovery. systemd auto-restart; stateless app means a restart is always safe.

Recommended for launch

• Log rotation for app.log (logrotate) to bound disk use.
• Automated PostgreSQL backups with off-host retention + a tested restore.
• External uptime monitoring on /health with alerting.
• Post-deploy health check with automatic rollback on failure.
• Error aggregation / structured logging as volume grows.

Known bottlenecks

• Synchronous LLM calls in the request path dominate latency and hold a connection open for the duration — the single external dependency on the hot path.
• Single Node process and a co-located database share one host's resources.

Growth path

• Run the LLM call asynchronously (job + polling / websockets) so requests return fast.
• Scale the stateless app horizontally behind the proxy; sessions already live in Postgres.
• Move PostgreSQL to a managed/replicated instance; add read replicas if needed.
• Abstract the LLM provider (Scaleway / self-hosted Qwen / alternative) behind the existing module boundary — already exercised once, when Together.ai was replaced by Scaleway with no change outside llm/llm.js.

Why choose it

• Data sovereignty. Student answers and all personal data stay on school hardware — a decisive advantage for GDPR compliance and minors' protection.
• Works offline. No dependence on internet uptime or a third-party AI provider during lessons.
• No per-token cost. Once the hardware is in place, AI feedback has no marginal usage bill.
• Full control. The school owns the model, the data, and the update cadence.

What it requires & how it works

• A capable on-prem machine — ideally a modest GPU, or a strong multi-core CPU for smaller models — running an open model (e.g. Qwen) via Ollama or vLLM.
• Only the LLM provider module changes: it points at the local model's OpenAI-compatible endpoint instead of Scaleway. The rest of the app is identical.
• App, PostgreSQL, and nginx run on the same box (or two); content is imported once from Sheets, then the install can be fully offline.
• Trade-offs: local IT must maintain the box and apply updates; a locally hostable model may score below a hosted frontier model, so a short quality check per language is advised.

Reference mapping

• Compute: the Node app on EC2, or containerised on ECS/Fargate behind an Application Load Balancer (TLS via ACM).
• Database: Amazon RDS for PostgreSQL — managed backups, patching, and optional Multi-AZ failover.
• AI: keep Scaleway, or switch to Amazon Bedrock (Qwen / other models) to keep inference inside AWS — noting that an EU region would be a requirement, not a preference.
• Static & backups: S3 (optionally CloudFront); logs/metrics: CloudWatch; secrets: Secrets Manager / SSM.

Trade-offs

• Pros: elastic scaling, managed DB backups and HA, first-class monitoring, easy horizontal scale of the stateless app.
• Cons: higher and usage-based cost, more operational surface than a single VPS.
• GDPR: pin all services to an EU region (e.g. eu-central-1) and keep student data within EU data residency.