title	CAE Training Scenario Generator
description	Generate deterministic aviation training scenarios and export instructor-reviewed lesson-plan YAML
ms.date	2026-07-25
ms.topic	overview

Overview

The CAE Training Scenario Generator is a Next.js application for drafting aviation training exercises. Instructors provide a title, training objectives, role, difficulty, and length. The application returns a structured scenario with timed injects, assessment criteria, and instructor briefing notes.

The current provider is deterministic and uses local mock scenario data. It does not call an external AI service or connect to an operational aviation system. Every YAML export is marked as an AI-assisted draft that requires instructor review.

Current capabilities

• Generate scenarios for pilot, maintenance, and air traffic control training
• Select basic, intermediate, or advanced difficulty
• Select short, medium, or long scenario length
• Review scenario details, timed injects, an assessment rubric, and briefing notes
• Download a versioned YAML lesson-plan document in the browser
• Validate API payloads and return structured client errors
• Run lint, Vitest coverage, and a production build through one local quality gate
• Deploy a standalone Next.js server to Azure App Service with Bicep and GitHub Actions
• Remove all deployed project resources through a guarded teardown workflow

Technology

• Next.js 16 App Router and React 19
• TypeScript 5.7
• Tailwind CSS 4 and PostCSS
• Vitest 4 with V8 coverage and Cobertura output
• YAML 2 for client-side scenario export
• Azure App Service on Linux, provisioned with Bicep
• GitHub Actions with OpenID Connect (OIDC) authentication to Azure

Run locally

Prerequisites

• Node.js 20
• npm
• PowerShell 7 or later when using the repository scripts

Install dependencies and start the development server:

npm ci
npm run dev

Open http://localhost:3000. On Windows, ./scripts/start.ps1 performs the Node.js and npm checks, installs missing dependencies, and starts the server.

The mock provider is the default, so local development requires no credentials or external services. You can set the supported environment variables in .env.local when you need explicit values:

SCENARIO_PROVIDER=mock
NEXT_PUBLIC_APP_TITLE=CAE Training Scenario Generator

Only the mock provider is implemented. Unknown SCENARIO_PROVIDER values fall back to the mock provider.

Use the generator

1. Enter a scenario title and training objectives.
2. Choose the pilot, maintenance, or ATC role preset.
3. Select the difficulty and scenario length.
4. Generate and review the scenario content.
5. Download the YAML draft for use by a lesson-plan consumer.

Scenario generation stays deterministic for a given role and request shape. YAML construction and serialization happen in the browser after generation; the download action does not send scenario data to another service.

API contract

The UI calls POST /api/generate with JSON:

{
  "title": "Emergency Descent Procedure",
  "trainingRole": "pilot",
  "objectives": "Practice emergency descent procedures and crew coordination",
  "difficulty": "intermediate",
  "scenarioLength": "medium"
}

Required fields are title, trainingRole, and objectives. Difficulty defaults to intermediate, and scenario length defaults to medium. Supported values are defined in lib/scenario-engine/types.ts.

A successful response contains:

• scenarioDescription
• injects with timing, event type, expected response, and severity
• assessmentCriteria with competency and passing standards
• instructorBriefingNotes
• metadata with generation time, role, and difficulty

Invalid request data returns HTTP 400 with an error field. Unexpected provider failures return HTTP 500 with an error field.

YAML export

Exports use schema version 1.0 and document kind cae.training.scenario. The document preserves the effective request, generated scenario, generation metadata, export time, and mandatory draft provenance.

The compatibility rules and an example document are available in:

• Scenario export contract
• Example scenario YAML

Validate changes

Run the complete local gate from PowerShell:

./scripts/test-all.ps1

The script runs all checks even when one fails, then reports step durations, total tests, pass and failure counts, skipped tests, and per-category results. It exits with a nonzero code when lint, tests, or the production build fails.

Individual npm commands are also available:

Command	Purpose
npm run dev	Start the development server
npm run lint	Run ESLint for TypeScript and TSX files
npm test	Run the Vitest suite once
npm run test:coverage	Run tests and write Cobertura coverage to coverage/
npm run build	Create the standalone production build
npm start	Start a previously built production server

The Code Quality coverage workflow runs coverage for pull requests and pushes to main, then uploads coverage/cobertura-coverage.xml to GitHub Code Quality.

Deploy to Azure

The Deploy to Azure App Service workflow runs on pushes to main or by manual dispatch. It performs these operations:

1. Installs dependencies and creates a standalone Next.js build.
2. Signs in to Azure through GitHub OIDC.
3. Creates rg-cae-training-scenario in canadacentral when needed.
4. Deploys infra/main.bicep at resource-group scope.
5. Publishes the standalone package to the provisioned Linux App Service.
6. Optionally publishes the deployment URL to the repository wiki.

Configure these GitHub Actions secrets before deployment:

Secret	Purpose
AZURE_CLIENT_ID	Entra application or managed identity client ID
AZURE_TENANT_ID	Entra tenant ID
AZURE_SUBSCRIPTION_ID	Target Azure subscription ID
WIKI_PAT	Optional repository-scoped token for the deployment wiki page

The Azure identity needs least-privilege access to create and manage the resource group and its App Service resources. Configure a federated credential for this repository and its production GitHub environment. The Bicep template creates one Linux App Service plan and one web app, with HTTPS-only traffic, TLS 1.2 minimum, disabled FTPS, and the mock scenario provider.

Tear down Azure resources

The Teardown Azure App Service workflow permanently deletes rg-cae-training-scenario, including the App Service plan, web app, deployment history, and every other resource in that group.

Caution

Keep unrelated resources out of rg-cae-training-scenario. Resource-group deletion cannot preserve individual resources inside the group.

To run the teardown:

1. Open the repository's Actions page.
2. Select Teardown Azure App Service.
3. Choose Run workflow.
4. Enter delete rg-cae-training-scenario in the confirmation field.
5. Start the workflow and approve the production environment if protection rules require it.

The workflow uses the same OIDC secrets as deployment, waits for deletion to finish, verifies that the resource group is absent, and writes a run summary. It succeeds without changes when the group is already absent. Deployment and teardown share an azure-production concurrency group, so they cannot operate on the resource group simultaneously.

Repository layout

app/                         Next.js pages, layout, error boundary, and API route
components/                  Scenario form and result presentation components
data/mock-scenarios/         Deterministic pilot, maintenance, and ATC templates
infra/main.bicep             Azure App Service infrastructure
lib/providers/               Scenario provider interface and mock implementation
lib/scenario-engine/         Request types, validation, and scenario assembly
lib/scenario-export/         Versioned export mapping, filenames, and YAML serialization
scripts/start.ps1            Local development bootstrap
scripts/test-all.ps1         Canonical lint, test, coverage, and build gate
specs/001-scenario-yaml-export/  YAML export requirements and contract
specs/002-test-summary-metrics/  Test summary requirements and implementation plan
.github/workflows/           Coverage, deployment, and teardown automation

Safety boundary

This application produces instructor-reviewed training drafts. It is not approved for operational decision-making, aircraft control, maintenance release, air traffic separation, trainee record storage, or use as a regulated system of record. The repository contains no authentication or persistent data store.

License and support

The package metadata declares the project under the MIT license. Report defects or request enhancements through the repository's GitHub issues.