Software Architecture Map

SemaEHS on 3D-ILP

The domain (SemaEHS) defines what is learned. The platform (3D-ILP) defines how learning works. This map shows the full system: the 3D-ILP platform architecture (the machine), the SemaEHS domain layer (the content), the event system that connects them, and the tech stack underneath.

Platform (3D-ILP) Domain (SemaEHS) Data / Events Users / Roles Infrastructure

1 · Platform vs. Domain core mental model

SemaEHS is not a standalone app. It is a content & configuration layer running on top of 3D-ILP.

Platform · 3D-ILP

How learning works

  • Auth, roles, session management
  • Learning flow engine (block sequences, navigation)
  • Event bridge & state store
  • Evaluation & feedback engine
  • Block renderer & 3D scene lifecycle
Domain · SemaEHS

What is learned

  • EHS modules (Work at Heights, Electrical Safety, Confined Space…)
  • Hazard definitions (id, severity, regulatory flags)
  • 3D environments (scaffold, mine, substation)
  • Competency catalog & pass criteria
  • Domain event vocabulary (RISK_IDENTIFIED, PPE_SELECTED, …)
8 EHS Modules Planned
1. Work at HeightsMVP
2. Electrical SafetyPhase 2
3. Confined Space EntryPhase 2
4. Fire Prevention & ResponsePhase 2
5. Manual Handling & ErgonomicsPhase 2
6. PPE Selection & UsePhase 2
7. Chemical Hazard AwarenessPhase 2
8. Incident ReportingPhase 2

2 · The Learning Loop every experience follows this

The 3D scene is the application stage — not the whole experience.

1
Reinforce
Present key concepts through text, visuals, and summaries.
2
Activate
Engage prior knowledge via 2D interactive exercises and quizzes.
3
Apply
Place the learner in a 3D environment to demonstrate real behavior.
4
Evaluate
Interpret events, score, and deliver meaningful feedback.

3 · Content Hierarchy Inside a Domainstrict 4 levels

Components define what the learner must demonstrate. Blocks define how it is delivered.

Module
Training course
e.g. “Work at Heights”
Unit
Topic grouping
e.g. “Fall Protection”
Component
Measurable competency
e.g. “Identify fall hazards in a scaffold setup”
Block
Delivery mechanism
Text · Quiz · 2D · 3D scene

4 · System Layers each layer has one job

Layers never skip past their boundary. Blocks emit; the platform decides.

Platform Layer
Auth, role management, module orchestration, global state, event processing, evaluation, feedback, analytics, progress persistence.
Next.jsSupabase AuthZustandPrisma
Learning Flow Engine
Reads the block sequence for a component, injects context (component id, config, emit fn), advances/branches based on platform state, handles transitions.
Next.js RouterZustand store
Block Renderer
Instantiates and mounts the correct block type by kind. Provides a single shared interface contract for every block.
Reactdynamic() ssr:false
Block (2D or 3D)
Renders content (UI or 3D), captures interaction, emits structured events via the injected emit function. Zero knowledge of evaluation.
React / JSXBabylon.jsActionManager
Event Bridge
Structured event channel: { type, blockId, payload, timestamp }. Delivers events from blocks into platform state; never delivers logic back.
Zustand actionsTypeScript contract

5 · Event Flow the single source of truth

Blocks emit semantic events. The platform interprets them. State mutates. React re-renders. Nothing is ever lost — events.push() before the switch.

👆
User action
Click, zone entry, answer
🎲
Block / Scene
Babylon or 2D block emits
🔌
Event Bridge
LearningEvent
🗄️
Platform State
Zustand store updates
⚖️
Evaluator
Checks completion criteria
📣
Feedback / Flow
Advance, fail, or report
example events
3D scene
RISK_IDENTIFIED
{ id: "missing_guardrail_01" }
Quiz
ANSWER_SELECTED
{ questionId, value }
2D
PPE_SELECTED
{ itemId, correct }
3D scene
SCENE_COMPLETED
Scene finished; platform takes control.

6 · Block Types interchangeable delivery

All blocks share the same interface: receive context, emit events. They have no idea what they are teaching.

InfoText
Cards
Image
Quiz
Mini-game
2D Interactive
Wimmelbild
Feedback
Reference
Video
3D Micro Interaction
3D Full Scene
3D Unit Evaluation
VR Experience

7 · 3D Scene Lifecycle Babylon.js boundary

Babylon is a 3D engine, not a React component. It runs in a <canvas>, imperatively. Scenes must dispose completely — memory leaks degrade long sessions fast.

01
Initialize
Scene object created, engine attached.
02
Load Assets
GLB models, textures, environment (async).
03
Ready
Scene signals ready; platform shows it.
04
Interaction
User explores; events emitted.
05
Completion
SCENE_COMPLETED; platform takes control.
06
Dispose
All meshes, textures, listeners released.

8 · Technology Stack MVP choices

Small team, balancing productivity and long-term flexibility. Starting points, not contracts.

Framework
Next.js
Frontend + API routes. Client-only dynamic() import for Babylon.
3D Engine
Babylon.js
Client-side only. GLB models. ActionManager for clicks.
State
Zustand
Bridge between Babylon, event bridge, and React UI.
Backend
Next.js API Routes
No separate server at MVP. Railway if serverless limits bite.
DB + Auth
Supabase
Postgres + Auth + Storage. RLS enforces role access.
ORM
Prisma
Type-safe queries against Supabase Postgres.
Asset Storage
Supabase Storage → R2
Move to Cloudflare R2 when egress costs matter.
Hosting
Vercel
Zero-ops Next.js deploys. Preview URLs per branch.
Marketing
Hostinger
Existing marketing site stays where it is.

9 · Users & API Surface

Three roles, distinct dashboards. Thin REST API at MVP.

User Roles

Student
Industrial worker, technician, new hire — consumes modules, interacts, receives feedback.
Instructor
HSE officer / safety supervisor — assigns modules, monitors progress, views performance data.
Admin
HR / L&D / platform admin — configures company, manages users and module access.

API (MVP)

  • POST /auth/login, POST /auth/logout
  • GET /modules, GET /modules/:id
  • GET /components/:id — definition + blocks
  • GET /progress/:userId
  • POST /progress/:userId/event — record a learning event
  • POST /admin/modules, GET /admin/users

10 · Student Flow & Evaluation

The flow is the same regardless of domain. Content changes; structure does not.

Flow Loop

  1. Student selects Module → Starts first Component
  2. Platform mounts 1st Block (e.g. Text)
  3. Block completes → Platform mounts 2nd Block (e.g. Quiz or 3D)
  4. Block emits domain events → Platform state updates
  5. When component finishes, Platform evaluates state against pass criteria
  6. Success? Proceed to next Component. Fail? Retry or block.

Evaluation Engine

  • Listens to all events for current component
  • Maintains score and required milestones
  • Checks RISK_IDENTIFIED array vs required targets
  • Records attempts in DB on COMPONENT_COMPLETED

11 · MVP Scope what ships first

Work at Heights module, scaffold hazard scene. Validate — do not over-engineer.

Included

  • 1 module: Work at Heights
  • 3–4 blocks: Intro text, PPE quiz, 3D scaffold scene
  • 5 hazards in a scaffold Babylon.js scene
  • Evaluation: Pass / Partial / Fail + feedback

Excluded

  • Instructor dashboard
  • Compliance reporting
  • Multi-module support
  • Retry / replay logic
  • Mobile / VR support

Success Criteria

  • 2–3 pilot clients active
  • 1 paying client in real use
  • Positive EHS instructor feedback
  • 1 client requesting expansion
Built from: 3D-ILP_Master.md · SemaEHS.md · Developer_Onboarding.md