Architecture

SCL is a browser-centered product with a .NET evaluation backend. The browser owns the learner journey and real-time voice orchestration; backend services own active role-play content, evaluation, completion, and server-side analytics delivery.

System context

End-to-end request flow

The parent launches the SPA with a role-play ID and sends the learner bearer token.
The SPA loads the active role-play from the Evaluation API.
The backend joins the role-play record with its active SCAI agent and loads localized briefing/help plus private evaluation criteria.
The learner starts practice; the SPA obtains a SCAI application token and establishes WebSocket/WebRTC communication.
SCAI audio and metadata drive the spoken interaction and temporary transcript.
When practice ends, the SPA posts the transcript, elapsed time, locale, and optional analytics session ID.
The backend exchanges the learner token for an AI Factory technical token, combines the private criteria with the transcript, and validates the structured result.
A successful response is returned to the learner. Completion and backend analytics delivery are queued or proxied independently when enabled.

Runtime components

Component	Functional responsibility	Failure effect
Parent platform	Learner identity, iframe launch, token refresh, course context	SCL cannot launch or refresh identity
SCL SPA	Briefing, practice controls, timer, transcript, feedback rendering	Learner journey stops and shows a client error
Evaluation API	Active catalog reads, evaluation orchestration, completion and analytics enqueue	Role-play or feedback unavailable
Catalog storage	Role-play/agent records and content/evaluation files	Inactive role-play/agent is unavailable; missing content degrades its specific feature; malformed session JSON fails loading
Integration Credentials	SCAI, analytics, and AI Factory technical tokens	The affected voice, analytics, or evaluation path cannot authenticate
SCAI	Simulated-customer voice, signalling, media, transcript metadata	Practice cannot connect or is interrupted
AI Factory	Applies role-play criteria and returns structured feedback	Evaluation returns an error; no partial feedback is shown
Learning Platform Integration	Records optional completion	Feedback still succeeds; completion retries in background
SCL Analytics	Creates session IDs and receives lifecycle events	Learning flow continues without analytics

Data ownership

Role-play and SCAI agent records are held in Azure Table Storage.
Briefing, help, and evaluation criteria are separate blob content referenced by the role-play record.
The browser holds user and voice tokens in memory, preferences in localStorage, and the temporary transcript in sessionStorage.
The current backend does not persist evaluation history or transcripts.
Completion and backend analytics use queues to separate learner response time from downstream delivery.

Current and planned service boundaries

Only the Evaluation API is implemented in the backend repository today. It reads the catalog directly and runs the completion and analytics workers.

A dedicated Catalog API with governed CRUD, versioning, and approvals is planned but remains a placeholder.
A dedicated Sessions API for evaluation history, reporting, and optional transcript audit is planned but remains a placeholder.

These planned services must not be described as current product capabilities.

Important architectural properties

The frontend is a state-driven single-page application rather than a route-per-step workflow.
Voice is browser-to-SCAI; audio does not pass through the Evaluation API.
Evaluation criteria stay server-side even though briefing and connection data are returned to the browser.
Analytics is implemented as a backend proxy and best-effort delivery path: failures are logged or ignored without blocking practice or replacing feedback.
Completion is asynchronous and cannot be confirmed from the feedback UI.
No durable resume mechanism exists for an interrupted attempt.