System Architecture

Architecture at a glance

NTPU AI Learn splits the system into two paths. To read public content, the browser simply fetches pages that were prerendered at build time. Anything that needs trust, such as submitting an assessment, syncing progress, signing in or using instructor and admin features, goes to the Worker API, which validates and authorizes the request before it reads or writes the database.

• UnderstandStart with the big picture: system boundaries and relationships
• BuildGo deeper into structure: Container and its components
• OperateDeployment, operation and failure behavior

The read path needs no sign-in, makes no API call and never touches the database, so public content is fast and indexable. The interactive path is the only way to read or write learning data, and every request on it is validated and authorized inside the Worker. Answer keys and instructor-only content live only on the server and never appear on the public path.

Some interactive actions need more than a valid, authorized request. Before something like a course-completion certificate or a capability certificate is granted, the Worker also runs server-side eligibility rules that check real evidence (such as completed lessons and passed assessments, or an instructor's reviewed and passed judgment of submitted work) before anything is issued. Nothing is ever granted just because a form was submitted.

System Context

This diagram focuses on one thing: who uses NTPU AI Learn, and how the platform interacts with the outside world.

It lets someone approaching the platform for the first time quickly understand the system boundary and the overall picture.

Container Architecture

This diagram unpacks the single "NTPU AI Learn" box from System Context into the technical components that are actually deployed and run. It answers: what are the main execution and data components, what does each own, and how do they talk to each other.

How one action moves through the system

Two real examples: one that only reads public content, and one that needs server-side scoring and a database write.

1. 1The browser requests the page
   For example, a module URL under /courses/….
2. 2The Worker handles the URL
   Legacy URLs are permanently redirected at this point, and every response gets security headers.
3. 3A prerendered page is returned
   The complete HTML, CSS and JS generated at build time come from Static Assets. No API call, no database read, no sign-in.
4. 4The browser shows it and takes over
   The content is readable immediately. Once JavaScript loads it adds interaction such as the language switch, self-checks and “Mark as complete”; by default progress stays in this browser only.

1. 1Start the attempt
   The browser sends a POST to an assessment API under /api/ with the session code and learner code (no sign-in needed). The Worker validates the input, confirms the session is open, creates an attempt record in D1 and returns the questions without answers.
2. 2Submit the answers
   When the learner finishes, the browser sends another POST with the option chosen for each question.
3. 3Schema validation
   The Worker first checks the request against its schema; a malformed request is rejected right away.
4. 4Check the attempt and session
   The Worker finds the attempt and confirms the session is still open. An attempt that was already submitted gets its original result back and is never rescored. When bot verification is enabled, it is checked on the server here too.
5. 5Score on the server
   After confirming every question is answered and every question exists, the Worker scores the attempt against answers that exist only on the server and summarizes performance by competency.
6. 6Write to D1
   The score and each answer are written to the database with parameterized queries.
7. 7Return the result and update progress
   The response carries the score and competency breakdown (a post-test also includes the learner’s own pre-test score). The page shows the result and marks the assessment complete in the browser’s progress.

Components

Design principles

Behind the technology choices above are six principles that the code and the build actually enforce. The table below adds why each principle matters, what it means in practice, and the trade-off that comes with adopting it.

Quality Attributes

These are concrete scenarios rather than abstract adjectives, describing how the platform actually behaves in a few quality dimensions. Each one can be checked against the code or a test; none of them is an unmeasured numeric target.

1. 1Accessibility
   Even if client-side JavaScript fails to run, public course content remains fully readable, because it is already HTML generated at build time (see "Progressive enhancement").
2. 2Security
   Modifying the code running in the browser cannot let a learner change an authoritative authorization decision or an assessment score; those decisions are made only in the Worker, see "Trust boundaries".
3. 3Privacy
   Public pages and the front-end bundle never contain protected assessment answers, instructor-only notes, or unnecessary user data; every build scans all public output files and fails if it detects a leak.
4. 4Reliability
   When the database is unavailable, public learning content that was already prerendered is still served through Static Assets; only interactive features that need to read or write the database (such as submitting an assessment) are affected, see "Failure and degradation" below.
5. 5Maintainability
   Changes to URLs, routing and the database schema are reviewed in version control; one route table produces client routing, redirects, 404s and the sitemap, so production behavior and documentation cannot drift apart.
6. 6Reproducibility
   Given the same source revision and a supported toolchain, a maintainer can rebuild the entire public site and reconstruct the database schema by applying the versioned migrations in order.
7. 7Internationalization
   Switching language keeps you on the same logical page; because course, docs and assessment content share the same stable IDs across both languages, automated tests check that section structure, links and IDs stay in parity between them.

Content and data

“Content” and “user data” are different things, stored and managed separately. Editing course text never touches learner data, and nothing learners do is written back into the content.

Learning progress in your browser is a third kind: it stays on your device unless you choose to sync it to a course session.

• How progress works

Course feedback components

Course feedback consists of a browser form, four groups of Worker APIs, D1 tables, schedules and mail delivery, all inside the existing trust boundary: authorization, masking, thresholds and audit happen in the Worker.

Trust boundaries

• Security overview

Deployment

NTPU AI Learn has three deployment environments, each responsible for a different stage of development and release.

Production and Staging use independent deployments and data. Local development uses locally simulated resources and never touches production data directly.

Failure & Degradation

This covers only the scenarios that can currently be verified against the architecture and the code's actual behavior. No documented rollback or incident procedure for a failed migration, or for the identity/session service itself degrading, was found in this repository, so no unverified procedure is listed here.

1. 1Static delivery available, Worker API unavailable
   Public course content keeps reading normally through Static Assets, unaffected. Interactive operations that need the Worker (signing in, submitting an assessment, syncing progress) fail and show a clear error rather than pretending to succeed.
2. 2Worker API available, D1 unavailable
   Public content is unaffected, since it is served from Static Assets and never reads the database. Interactive operations that need to read or write the database fail, and never return a false success.
3. 3Worker API available, R2 file storage unavailable
   Public content and other operations that do not involve files are unaffected. Uploading or downloading credential evidence files, or downloading teacher slide exports, fails and shows a clear error, and never returns a false success.
4. 4JavaScript fails to execute
   Public course content remains readable, because it is HTML generated at build time. Only the interactions React adds after it loads (such as the language switch, self-checks, or marking a lesson complete) become unavailable.

URLs and language

The platform has a single route table: client routing, the Worker’s redirects and 404s, prerendered pages and the sitemap all come from one definition. The table also puts every URL in one of three classes: public content (prerendered and indexable), public interactive workflows (not prerendered, not indexed) and protected pages that require authorization.

The URL decides the language, and switching languages keeps you on the same logical page. Because both languages share the same IDs, progress and links keep working when you switch.

• Bilingual design

Architecture Decisions

Architecturally significant decisions are kept as Architecture Decision Records (ADRs), each recording its context, the approach taken and its consequences.

ADRs are engineering documents kept in the repository, for anyone who needs a deeper understanding of the implementation or is joining development.

Related documentation

• Security overview: server-side authorization, scoring, and input and output handling
• Privacy: what stays in your browser and what is sent to the server
• Roles and permissions: what learners, instructors and admins can each do
• Bilingual design: URLs, stable IDs and content parity