Overview

Relevant source files

• README.md
• SECURITY.md
• SECURITY_HEADERS.md
• cypress/screenshots/screenshots.cy.ts/01-game-initial-state.png
• cypress/screenshots/screenshots.cy.ts/02-game-paused.png
• cypress/screenshots/screenshots.cy.ts/03-game-with-volume-at-50.png
• cypress/screenshots/screenshots.cy.ts/04-game-muted.png
• cypress/screenshots/screenshots.cy.ts/05-game-active-with-score.png
• docs/COPILOT_QUICK_START.md
• docs/ISMS_POLICY_MAPPING.md
• package-lock.json
• package.json

Purpose and Scope

This repository provides a security-first game template for building 3D web games using React 19, Three.js, and TypeScript. It implements a complete software development lifecycle with automated security gates, cryptographic attestations, and verifiable compliance aligned with Hack23 AB's Information Security Management System (ISMS)

Key Characteristics:

• Functional 3D target-shooting game demonstrating React/Three.js integration
• Multi-stage CI/CD pipeline with defense-in-depth security enforcement
• GitHub Copilot integration with 6 custom agents and 6 reusable skills
• SLSA Level 3 build attestations and SBOM generation
• 80%+ test coverage requirement with automated quality gates

Navigation:

• Application runtime architecture: Application Architecture
• Security framework and ISMS compliance: Security Framework
• Development environment and Copilot setup: Development Environment
• Testing strategies and coverage: Testing Infrastructure
• CI/CD pipeline stages: CI/CD Pipeline
• Deployment and attestation: Deployment & Distribution

Sources: README.md1-42 SECURITY.md24-28

---

Repository Structure

The repository is organized into functional layers that separate application code, automation infrastructure, and security documentation:

game/
├── src/                          # Application source code
│   ├── components/               # React components
│   │   ├── App.tsx              # Root component with ErrorBoundary
│   │   ├── GameScene.tsx        # Three.js scene orchestration
│   │   ├── TargetSphere.tsx     # Individual target with physics
│   │   └── GameHUD.tsx          # UI overlay (score, timer, controls)
│   ├── hooks/                    # State management
│   │   ├── useGameState.ts      # Game logic, physics, scoring
│   │   └── useAudioManager.ts   # Sound synthesis with Howler.js
│   ├── utils/                    # Shared utilities
│   │   ├── gameConfig.ts        # Level scaling parameters
│   │   └── constants.ts         # Game constants (GAME_DURATION: 60s)
│   └── main.tsx                  # Application bootstrap
├── .github/                      # Automation and AI assistance
│   ├── workflows/                # CI/CD pipelines
│   │   ├── test-and-report.yml  # Quality gates (80%+ coverage)
│   │   ├── build-attest-release.yml  # SLSA attestations
│   │   ├── codeql-analysis.yml  # Static analysis (SAST)
│   │   └── scorecard.yml        # OSSF supply chain scoring
│   ├── agents/                   # GitHub Copilot custom agents
│   │   ├── product-task-agent.md
│   │   ├── game-developer.md
│   │   ├── security-specialist.md
│   │   └── test-engineer.md
│   ├── skills/                   # Reusable AI patterns
│   │   ├── security-by-design/SKILL.md
│   │   ├── react-threejs-game/SKILL.md
│   │   └── testing-strategy/SKILL.md
│   └── copilot-instructions.md   # Project-wide coding standards
├── cypress/                      # E2E test specifications
│   ├── e2e/                     # Test scenarios
│   └── screenshots/             # Visual regression artifacts
├── docs/                         # Security documentation
│   ├── ISMS_POLICY_MAPPING.md   # Feature-to-policy traceability
│   ├── MCP_CONFIGURATION.md     # Model Context Protocol setup
│   └── version.txt              # Deployed build metadata (80.25 importance)
├── public/                       # Static assets
│   └── index.html               # Security headers (CSP, X-Frame-Options)
├── package.json                  # Dependencies (React 19.2.4, Three.js 0.183.0)
├── package-lock.json            # Locked dependency tree (672.62 importance)
├── vite.config.ts               # Build configuration
├── vitest.config.ts             # Test configuration (coverage thresholds)
└── tsconfig.json                # TypeScript strict mode

Sources: package.json1-58 package-lock.json1-49 README.md1-617

---

Application Runtime Architecture

Application Architecture: React/Three.js Game Runtime

Runtime Flow:

1. public/index.html loads with security headers (CSP, X-Frame-Options, HSTS)
2. src/main.tsx bootstraps React application with ErrorBoundary
3. App.tsx initializes useGameState and useAudioManager hooks
4. Canvas component renders Three.js scene via @react-three/fiber
5. useFrame hook runs at 60fps, updating target physics with delta time
6. User clicks trigger state updates → sound effects → particle explosions
7. GameHUD displays reactive UI overlay (score, timer, controls)

Key Code Entities:

Component	File Path	Responsibility
HTML Shell	public/index.html	Security headers, CSP, X-Frame-Options
Application Entry	src/main.tsx	React bootstrap, ErrorBoundary wrapper
Root Component	src/App.tsx	Component orchestration, event handling
Game State Hook	src/hooks/useGameState.ts	Score, level, targets, physics, timers (23.27 importance)
Audio Manager Hook	src/hooks/useAudioManager.ts	Howler.js integration, procedural sound synthesis
Canvas Component	Canvas with @react-three/fiber	Three.js scene container, WebGL rendering
Target Component	TargetSphere	3D geometry, materials, click handling
Physics Update	updateTargetPhysics	Velocity, bouncing, boundary collision
Game Config	src/utils/gameConfig.ts	Level scaling, target count, size parameters
Constants	src/utils/constants.ts	GAME_DURATION: 60, COMBO_TIMEOUT: 2

Sources: package.json18-26 README.md483-520

---

Technology Stack

The application uses modern web technologies with pinned versions for supply chain security. All dependency versions are locked in package-lock.json (lockfileVersion 3, 672.62 importance score).

Core Runtime Dependencies:

Package	Version	Purpose	Configuration
React	19.2.4	UI framework with hooks	package.json:22
react-dom	19.2.4	DOM rendering	package.json:23
TypeScript	5.9.3	Static typing	tsconfig.json strict mode
Three.js	0.183.0	3D WebGL rendering	package.json:25
@react-three/fiber	9.5.0	React renderer for Three.js	package.json:20
@react-three/drei	10.7.7	Helper components (OrbitControls, Sparkles)	package.json:19
Howler.js	2.2.4	Web Audio API wrapper	package.json:21
react-error-boundary	6.1.1	Error boundary component	package.json:24

Build & Development Tools:

Package	Version	Purpose	Configuration
Vite	7.3.1	Build tool with HMR	vite.config.ts
@vitejs/plugin-react	5.1.4	React integration for Vite	vite.config.ts:4
Vitest	4.0.6	Unit test runner	vitest.config.ts
@vitest/coverage-v8	4.0.18	Code coverage reporting	vitest.config.ts:coverage
Cypress	15.10.0	E2E testing framework	cypress.config.ts
ESLint	9.39.2	Code linting	eslint.config.js
typescript-eslint	8.56.0	TypeScript linting rules	eslint.config.js

Testing & Quality Assurance:

Package	Version	Purpose
@testing-library/react	16.3.2	Component testing utilities
@testing-library/jest-dom	6.9.1	Custom DOM matchers
jsdom	28.1.0	DOM simulation for tests
cypress-junit-reporter	1.3.1	JUnit XML output for CI
license-compliance	3.0.1	Automated license validation

Supply Chain Security:

• All GitHub Actions pinned to SHA hashes (see .github/workflows/)
• package-lock.json ensures reproducible builds with SHA-512 integrity checks
• License compliance enforced via npm run test:licenses
• SBOM generation via npm sbom in release workflow

Sources: package.json18-56 package-lock.json1-49

---

Security Framework Architecture

ISMS Policy Framework: Governance to Implementation

Security Implementation Mapping:

Security Control	Implementation	Configuration File	ISMS Policy
Static Code Analysis	CodeQL JavaScript/TypeScript	.github/workflows/codeql-analysis.yml (110.29 importance)	Secure Development Policy
Linting	ESLint + TypeScript rules	eslint.config.js	Secure Development Policy
Type Safety	TypeScript strict mode	tsconfig.json:compilerOptions.strict	Secure Development Policy
Dynamic Scanning	OWASP ZAP DAST	.github/workflows/zap-security-scan.yml	Secure Development Policy
Supply Chain Score	OSSF Scorecard ≥8.0	.github/workflows/scorecard.yml	Open Source Policy
Dependency CVEs	Dependency Review	.github/workflows/dependency-review.yml	Open Source Policy
License Compliance	MIT/Apache/BSD/ISC only	package.json:scripts.test:licenses	Open Source Policy
SBOM Generation	CycloneDX/SPDX format	.github/workflows/build-attest-release.yml	Open Source Policy
SBOM Quality	SBOMQS ≥7.0/10	.github/workflows/build-attest-release.yml	Secure Development Policy
Build Attestations	SLSA Level 3 provenance	.github/workflows/build-attest-release.yml (120.98 importance)	Secure Development Policy
Code Coverage	≥80% overall, ≥95% critical	vitest.config.ts:coverage.thresholds	Secure Development Policy
Security Headers	CSP, X-Frame-Options, HSTS	public/index.html:meta	Secure Development Policy
Pinned Actions	SHA-256 commit hashes	All .github/workflows/*.yml	Secure Development Policy
Immutable Releases	Tamper-proof artifacts	docs/version.txt (80.25 importance)	Data Classification Policy

Defense-in-Depth Layers:

1. Development: Copilot security agents, TypeScript strict mode, ESLint rules
2. Pre-commit: Local testing, linting, type checking
3. CI/CD: CodeQL SAST, dependency review, license compliance, OSSF Scorecard
4. Build: SBOM generation, quality validation, SLSA attestations
5. Release: Cryptographic signing, immutable artifacts
6. Runtime: Security headers, ZAP DAST scanning
7. Monitoring: GitHub security alerts, vulnerability reporting

Sources: README.md11-42 SECURITY.md29-85 docs/ISMS_POLICY_MAPPING.md1-200 SECURITY_HEADERS.md1-100

---

Development Workflow

The repository supports two primary development environments:

GitHub Codespaces (Recommended)

Configuration: .devcontainer/devcontainer.json

Pre-configured environment with:

• Node.js runtime and npm dependencies
• VS Code extensions (ESLint, Copilot, TypeScript)
• MCP servers for enhanced Copilot capabilities
• Automatic port forwarding for dev server (5173)

Local Development

Prerequisites:

• Node.js 18+ (specified in package.json:engines)
• npm 9+ (lockfile version 3)

Setup Commands:

Sources: package.json6-16 README.md199-237 README.md457-481

---

GitHub Copilot Integration

GitHub Copilot Agent System with MCP Integration

Three-Tier Architecture:

Tier	Components	Total Lines	Purpose
1. Base Instructions	copilot-instructions.md	N/A	Project-wide coding standards, security guidelines
2. Specialized Agents	6 agent files (product-task-agent.md, game-developer.md, frontend-specialist.md, test-engineer.md (21.11), security-specialist.md (16.26), documentation-writer.md)	3,530	Domain expertise and decision frameworks
3. Agent Skills	6 skill files (security-by-design (421), isms-compliance (191), react-threejs-game (404), testing-strategy (502), documentation-standards (459), performance-optimization (492))	2,469	Reusable patterns and best practices
Total	13 configuration files	5,999	Complete AI assistance system

MCP Server Configuration:

MCP Server	Purpose	Agent Access
Filesystem	Repository file access	All agents
GitHub	Issues, PRs, API calls	product-task-agent, security-specialist, documentation-writer
Git	Version history, commits	game-developer, product-task-agent
Memory	Context persistence	product-task-agent
Playwright	Browser automation	test-engineer
Brave Search	Documentation lookup	security-specialist

Configuration: .github/copilot-mcp.json (23.77 importance)

Agent Responsibilities:

Agent	Primary Skills	Mandatory Rules	Key Outputs
product-task-agent.md	N/A	Issue creation, analysis	GitHub issues, backlog
game-developer.md	react-threejs-game, performance-optimization	60fps, InstancedMesh	Game components, physics
frontend-specialist.md	documentation-standards, performance-optimization	React 19, WCAG 2.1 AA	UI components, accessibility
test-engineer.md	testing-strategy	80%+ coverage, E2E tests	Vitest/Cypress tests
security-specialist.md	security-by-design, isms-compliance	OSSF, SLSA, SBOM	Security docs, attestations
documentation-writer.md	documentation-standards, isms-compliance	JSDoc, Mermaid	Technical documentation

Sources: README.md57-86 README.md199-237 docs/COPILOT_QUICK_START.md1-100

---

CI/CD Pipeline Overview

Multi-Stage CI/CD Pipeline with Security Enforcement

7-Stage Pipeline Implementation:

Stage	Workflows	Enforcement	Blocking
1. Code Quality	eslint.config.js	Zero errors, consistent formatting	Yes
2. Security Scanning	codeql-analysis.yml (110.29), dependency-review.yml, scorecard.yml, package.json:test:licenses	No high/critical vulns, OSSF ≥8.0, approved licenses	Yes
3. Testing	test-and-report.yml, vitest.config.ts, cypress.config.ts	≥80% coverage, all tests pass	Yes
4. Build & Validation	build-attest-release.yml (120.98), SBOMQS	SBOM quality ≥7.0, Lighthouse thresholds	Yes
5. Security Attestations	slsa-github-generator, gh attestation	SLSA Level 3 provenance	Yes
6. Release	release-drafter, GitHub Releases, GitHub Pages	Immutable artifacts with security headers	No
7. Post-Deploy	zap-security-scan.yml, lighthouse-performance.yml, gh attestation verify	DAST findings, attestation verification	No (advisory)

Quality Gates:

Gate	Threshold	Configuration	Enforcement
Test Coverage	≥80% overall	vitest.config.ts:coverage.thresholds	Hard block
Security-Critical Coverage	≥95%	vitest.config.ts:coverage.thresholds	Hard block
License Compliance	MIT/Apache-2.0/BSD-*/ISC/CC0-1.0/Unlicense only	package.json:scripts.test:licenses	Hard block
SBOM Quality	≥7.0/10 SBOMQS score	build-attest-release.yml	Hard block
CodeQL Findings	Zero high/critical	codeql-analysis.yml	Hard block
Dependency CVEs	Zero high/critical	dependency-review.yml	Hard block
OSSF Scorecard	≥8.0/10 (aspirational)	scorecard.yml	Soft warning

Artifact Outputs:

Artifact	Generator	Format	Purpose
Coverage Report	vitest	HTML, JSON, text, JUnit XML	Code coverage evidence
E2E Screenshots	cypress	PNG	Visual regression testing
SBOM	npm sbom	SPDX JSON	Dependency inventory
SLSA Provenance	slsa-github-generator	In-toto JSONL	Build attestation
GitHub Attestations	gh attestation	Sigstore format	Cryptographic signatures
Release Notes	release-drafter	Markdown	Changelog
Build Artifacts	vite build	Bundled JS/CSS/HTML	Deployable application
Version Metadata	Custom script	docs/version.txt	Deployment tracking (80.25 importance)

Sources: README.md150-164 README.md554-616

---

Testing Infrastructure

The repository implements a multi-layered testing strategy:

Unit Testing (Vitest):

• Configuration: vitest.config.ts
• Environment: jsdom for DOM simulation
• Coverage tool: v8 with HTML/JSON/text reporters
• Minimum coverage: 80% overall, 95% for security-critical code
• Test pattern: **/*.{test,spec}.{ts,tsx}

End-to-End Testing (Cypress):

• Configuration: cypress.config.ts
• Base URL: http://localhost:5173 (Vite dev server)
• Screenshot directory: cypress/screenshots/
• Video recording: On failure only
• Reporters: JUnit XML + Multi-reporter for CI integration

Test Patterns:

• Arrange-Act-Assert structure
• Deterministic tests (no Math.random())
• Mocked external dependencies (time, APIs, Three.js rendering)
• Behavior-focused assertions (outcomes, not implementation)

Sources: package.json12-16 README.md523-553

---

Key Features Summary

Application Features

• 3D Game Engine: Three.js-based target shooting game with physics
• Audio System: Programmatic sound synthesis via Howler.js (no external audio files)
• Responsive Design: Touch and mouse input support
• State Management: Custom React hooks for game logic and audio
• Level Progression: Dynamic difficulty scaling
• Visual Effects: Particle systems, sparkles, explosions

Security Features

• ISMS Alignment: Complies with ISO 27001:2022, NIST CSF 2.0, CIS Controls v8.1
• SAST/DAST: Automated static and dynamic security scanning
• Supply Chain Transparency: SBOM generation, SLSA attestations, OSSF Scorecard
• License Compliance: Automated checking of approved OSS licenses
• Security Headers: CSP, X-Frame-Options, HSTS, X-Content-Type-Options
• Pinned Dependencies: All GitHub Actions pinned to SHA hashes
• Immutable Releases: Tamper-proof artifact distribution

Developer Experience Features

• GitHub Codespaces: Zero-config cloud development environment
• GitHub Copilot: 6 custom agents + 6 reusable skills + MCP servers
• Hot Module Replacement: Fast development iteration with Vite
• Type Safety: TypeScript strict mode with comprehensive type definitions
• Automated Testing: Pre-commit hooks, CI validation, quality gates
• Visual Regression: Cypress screenshot capture for game states

Sources: README.md1-617 SECURITY.md1-100 docs/ISMS_POLICY_MAPPING.md1-200