Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page: - [terraform/infrastructure/main.tf](https://github.com/crt25/collimator/blob/HEAD/terraform/infrastructure/main.tf) - [terraform/infrastructure/modules/static-website/main.tf](https://github.com/crt25/collimator/blob/HEAD/terraform/infrastructure/modules/static-website/main.tf) - [frontend/README.md](https://github.com/crt25/collimator/blob/HEAD/frontend/README.md) - [frontend/package.json](https://github.com/crt25/collimator/blob/HEAD/frontend/package.json) - [frontend/src/pages/task/[taskId]/detail.tsx](https://github.com/crt25/collimator/blob/HEAD/frontend/src/pages/task/%5BtaskId%5D/detail.tsx) - [backend/README.md](https://github.com/crt25/collimator/blob/HEAD/backend/README.md) - [apps/scratch/package.json](https://github.com/crt25/collimator/blob/HEAD/apps/scratch/package.json) - [apps/scratch/craco.config.js](https://github.com/crt25/collimator/blob/HEAD/apps/scratch/craco.config.js) - [e2e/tests/sessions/session-analysis.spec.ts](https://github.com/crt25/collimator/blob/HEAD/e2e/tests/sessions/session-analysis.spec.ts)

The Collimator project is a web-based platform composed of several distinct services working in concert. The architecture is designed for scalability and is deployed on Amazon Web Services (AWS), managed via Terraform. The system comprises a main user-facing frontend, a dedicated backend API, and a specialized application for interactive tasks based on Scratch.

This document provides a high-level overview of the system's components, their technologies, and how they interact. The core components are a Next.js frontend, a NestJS backend, and a Create React App-based Scratch application, all orchestrated through AWS services like CloudFront, Fargate, S3, and Lambda@Edge.

High-Level Components

The system is divided into three main application components and the underlying infrastructure that hosts them.

Component	Technology	Description	Source
Frontend	Next.js, React	The main web interface for users. Handles user management, class/session management, and task displays.	frontend/README.md
Backend	NestJS, Node.js	A server-side application providing a RESTful API for the frontend. Manages data persistence and business logic.	backend/README.md
Scratch App	Create React App, Scratch	An embedded application for creating, solving, and viewing interactive Scratch-based tasks.	apps/scratch/package.json
Infrastructure	AWS, Terraform	The cloud infrastructure that runs all application components, including networking, databases, and compute services.	terraform/infrastructure/main.tf

This diagram illustrates the primary components and their relationships.

Frontend Application

The frontend is a Next.js application responsible for the main user interface.

Sources: frontend/README.md, frontend/package.json

Key Technologies

• Framework: Next.js with React 19.
• UI: React Bootstrap and PrimeReact.
• State Management/Data Fetching: SWR for remote data fetching.
• Internationalization: react-intl (FormatJS) for handling multiple languages.
• API Generation: orval is used to generate a typed API client from an OpenAPI specification.

Sources: frontend/package.json:49-74, frontend/package.json:17

Structure and Deployment

The application uses the Next.js pages directory for file-system based routing. For example, frontend/src/pages/task/[taskId]/edit.tsx corresponds to the route for editing a specific task.

It is deployed as a static website on AWS S3 and served via CloudFront. A Lambda@Edge function is used to handle URL rewrites, a common pattern for single-page applications (SPAs) and Next.js static exports.

Sources: frontend/README.md:15-18, terraform/infrastructure/main.tf:15-23, terraform/infrastructure/modules/static-website/main.tf

Backend Service

The backend is a NestJS application, which provides a scalable Node.js server-side framework. It exposes a REST API consumed by the frontend.

Sources: backend/README.md

Key Technologies

• Framework: NestJS (TypeScript).
• Deployment: Runs as a containerized service on AWS Fargate.
• Database: Connects to a PostgreSQL database hosted on AWS RDS.
• Service Discovery: Utilizes AWS Cloud Map for service discovery within the VPC.

Sources: backend/README.md:29, terraform/infrastructure/main.tf:56-74, terraform/infrastructure/main.tf:41-54

Configuration

The backend service is configured via environment variables passed into the Fargate task definition. These include the database connection URL, OpenID Connect client ID, and Sentry DSN for error monitoring.

Sources: terraform/infrastructure/main.tf:70-72

Scratch Application

A separate application, app-scratch, is dedicated to handling tasks built with Scratch. It is a heavily customized Create React App (CRA) project.

Sources: apps/scratch/package.json, apps/scratch/craco.config.js

Purpose and Integration

This application provides three main views, accessible via different routes (/edit, /solve, /show):

• Editing: For teachers to create or modify Scratch tasks.
• Solving: For students to interact with and solve the tasks.
• Showing: A read-only view to display a solution.

The Scratch app is not a standalone service but is embedded within the main Next.js frontend using an <iframe>. Communication between the parent frontend and the embedded Scratch app is handled via iframe-rpc-react.

The following diagram shows how the main frontend loads a task for a student to solve.

Customization

The project uses craco (Create React App Configuration Override) to customize the Webpack configuration. This is necessary to integrate various Scratch libraries like scratch-vm, scratch-blocks, and scratch-paint, which have specific build requirements. The configuration handles aliasing, custom loaders, and polyfills for Node.js modules in the browser.

Sources: apps/scratch/craco.config.js

Infrastructure and Deployment (Terraform)

The entire cloud infrastructure is defined using Terraform. The main configuration file terraform/infrastructure/main.tf orchestrates the creation of all resources by calling reusable modules.

Terraform Modules

Module Name	Purpose	Source File
network	Sets up the VPC, subnets, and domain/certificate.	terraform/infrastructure/main.tf:5-13
frontend	Deploys the Next.js frontend as a static website on S3 with a Lambda@Edge rewriter.	terraform/infrastructure/main.tf:15-23
scratchapp	Deploys the Scratch CRA as a static website on S3 with a Lambda@Edge rewriter.	terraform/infrastructure/main.tf:25-33
database	Provisions an AWS RDS database instance within the private subnets of the VPC.	terraform/infrastructure/main.tf:41-54
backend	Deploys the NestJS backend as a containerized service on AWS Fargate.	terraform/infrastructure/main.tf:56-74
cdn	Configures a CloudFront distribution to serve all applications and route API requests.	terraform/infrastructure/main.tf:76-95
cd_backend	Configures resources for Continuous Deployment of the backend.	terraform/infrastructure/main.tf:97-104

This diagram shows the dependencies between the Terraform modules.

Summary

The Collimator architecture is a modern, decoupled system leveraging specialized frameworks for different concerns. The Next.js frontend provides a robust user experience, the NestJS backend offers a structured API layer, and the embedded Scratch application delivers specialized, interactive functionality. The entire system is deployed on a scalable and well-defined AWS infrastructure managed by Terraform, ensuring consistency and reliability across environments. This modular design allows for independent development and deployment of its constituent parts.