Monorepo Structure
Relevant source files
The following files were used as context for generating this wiki page:
The Collimator project is organized as a monorepo, housing multiple distinct but related applications and libraries within a single repository. This structure facilitates code sharing, streamlined dependency management, and integrated development workflows. The package manager is Yarn, which manages workspaces for the different projects.
The repository is divided into several top-level directories, including apps, backend, frontend, e2e, and libraries, each containing one or more packages.
High-Level Overview
The monorepo contains a main frontend application, a backend server, a specialized Scratch-based application, end-to-end tests, and shared libraries.
This diagram illustrates the primary packages and their relationships within the monorepo.
Packages
The following table summarizes the core packages within the monorepo.
| Package | Location | Purpose | Key Technologies |
|---|---|---|---|
collimator | frontend/ | The main user-facing web application. | Next.js, React, SWR, Storybook |
backend | backend/ | The server-side application providing the API and business logic. | NestJS, Prisma, Socket.IO |
app-scratch | apps/scratch/ | A customized Scratch GUI application, likely embedded in the frontend. | React, Redux, Craco, Scratch VM |
e2e | e2e/ | Contains end-to-end tests for the applications. | Playwright |
iframe-rpc | libraries/iframe-rpc/ | A shared library for communication between iframes. | TypeScript |
iframe-rpc-react | libraries/iframe-rpc-react/ | A React wrapper for the iframe-rpc library. | React, TypeScript |
Sources: frontend/package.json, backend/package.json, apps/scratch/package.json, e2e/package.json, libraries/iframe-rpc/package.json, libraries/iframe-rpc-react/package.json
frontend
The frontend package is a Next.js application that serves as the main interface for users.
Sources: frontend/README.md:1, frontend/package.json:59
Key Technologies & Dependencies
- Framework: Next.js (
15.3.1) - State Management: SWR for data fetching.
- UI: React (
19.1.0), Bootstrap, PrimeReact. - Forms: React Hook Form with Yup for validation.
- Testing: Jest for unit tests, Playwright for component tests (
@playwright/experimental-ct-react), and Storybook for UI component development. - Local Libraries: It uses
iframe-rpc-reactvia a Yarn workspace portal (portal:../libraries/iframe-rpc-react).
Sources: frontend/package.json:59-90
Scripts
The package.json defines several scripts for development, building, and testing.
"scripts": {
"dev": "echo '...' && cross-env NODE_OPTIONS=--preserve-symlinks next dev -p 3000",
"build": "cross-env NODE_OPTIONS=--preserve-symlinks next build",
"start": "cross-env NODE_OPTIONS=--preserve-symlinks next start -p 3000",
"lint": "next lint",
"test": "yarn test:jest && yarn test:playwright",
"test:ct": "yarn test:pre && playwright test -c playwright-ct.config.ts && nyc report --report-dir coverage-ct",
"storybook": "cross-env NODE_OPTIONS=--preserve-symlinks storybook dev -p 6006"
}
Sources: frontend/package.json:5-41
backend
The backend is a NestJS application responsible for server-side logic, API endpoints, and database interactions.
Sources: backend/README.md:20, backend/package.json:53
Key Technologies & Dependencies
- Framework: NestJS (
11.0.16) - Database ORM: Prisma (
6.6.0) - WebSockets:
@nestjs/platform-socket.io - API Documentation:
@nestjs/swagger - Error Monitoring: Sentry (
@sentry/nestjs)
Sources: backend/package.json:53-67
Scripts
Key scripts include starting the server, managing database migrations with Prisma, and running tests.
"scripts": {
"build": "nest build",
"start": "nest start",
"dev": "nest start --watch",
"prisma:migrate:dev": "dotenv -c -- prisma migrate dev",
"prisma:seed": "dotenv -c -- prisma db seed",
"test:e2e": "dotenv -c -- jest --config ./test/jest-e2e.json"
}
Sources: backend/package.json:8-25
apps/scratch
This package is a Create React App-based project, customized using craco (Create React App Configuration Override). It integrates a heavily modified Scratch GUI. It is designed to be embedded within other applications, such as the main frontend.
Sources: apps/scratch/package.json:2, apps/scratch/craco.config.js:2
Key Technologies & Dependencies
- Framework: React (
16.0.0) withreact-scripts. - Build Customization:
@craco/cracois used to modify the webpack configuration, for instance to handle Scratch-specific CSS module conventions and asset copying. - Core Logic: Numerous
scratch-*dependencies likescratch-vm,scratch-blocks, andscratch-gui. - Local Libraries: Like the frontend, it depends on
iframe-rpc-reactvia a Yarn workspace portal.
Sources: apps/scratch/package.json:44-100, apps/scratch/craco.config.js:10-12, 101-104
Scripts
The scripts are typical for a react-scripts project, with craco replacing react-scripts for commands.
"scripts": {
"dev": "cross-env NODE_OPTIONS=--preserve-symlinks PORT=3101 craco start",
"build": "cross-env NODE_OPTIONS=--preserve-symlinks craco build",
"test": "yarn pretest && playwright test && yarn posttest"
}
Sources: apps/scratch/package.json:5-13
e2e
This package is dedicated to end-to-end testing of the Collimator platform. It uses Playwright to automate browser interactions and verify application behavior from a user's perspective.
Sources: e2e/package.json:2, e2e/tests/users/user-management.spec.ts
Key Technologies & Dependencies
- Testing Framework: Playwright (
@playwright/test) - Utilities: It has no production dependencies, only development dependencies for running tests.
Sources: e2e/package.json:13-15
libraries
The libraries directory contains shared code intended for use across multiple packages in the monorepo.
iframe-rpc and iframe-rpc-react
These two libraries facilitate communication between the main frontend application and the embedded apps/scratch application.
iframe-rpc: A plain TypeScript library for handling remote procedure calls between an iframe and its parent window.iframe-rpc-react: A React wrapper aroundiframe-rpc, providing React hooks and components to simplify its use in React applications.
The frontend and apps/scratch packages include iframe-rpc-react as a dependency using portal:, a Yarn workspace feature that creates a direct link to the library's source code.
Sources: libraries/iframe-rpc/package.json, libraries/iframe-rpc-react/package.json, frontend/package.json:66, apps/scratch/package.json:67
The following sequence diagram shows how the frontend loads a task into the embedded scratch application.
This flow is derived from the logic in frontend/src/pages/task/[taskId]/detail.tsx.
Sources: frontend/src/pages/task/[taskId]/detail.tsx:43-52
Conclusion
The monorepo structure of Collimator is a well-organized system that leverages Yarn workspaces to manage dependencies and relationships between its constituent parts. It clearly separates concerns into a frontend, backend, a specialized apps/scratch module, and an e2e testing suite. The use of a shared libraries folder, particularly for iframe-rpc, demonstrates a key advantage of the monorepo approach: the ability to develop and maintain shared code alongside the applications that consume it, ensuring consistency and simplifying the development process.