Developer Setup Guide

Relevant source files

The following files were used as context for generating this wiki page: - [README.md](https://github.com/crt25/collimator/blob/HEAD/README.md) - [docker/docker-compose.yml](https://github.com/crt25/collimator/blob/HEAD/docker/docker-compose.yml) - [backend/package.json](https://github.com/crt25/collimator/blob/HEAD/backend/package.json) - [frontend/package.json](https://github.com/crt25/collimator/blob/HEAD/frontend/package.json) - [backend/README.md](https://github.com/crt25/collimator/blob/HEAD/backend/README.md) - [frontend/README.md](https://github.com/crt25/collimator/blob/HEAD/frontend/README.md) - [apps/scratch/README.md](https://github.com/crt25/collimator/blob/HEAD/apps/scratch/README.md) - [apps/scratch/package.json](https://github.com/crt25/collimator/blob/HEAD/apps/scratch/package.json) - [terraform/infrastructure/main.tf](https://github.com/crt25/collimator/blob/HEAD/terraform/infrastructure/main.tf)

This guide provides instructions for setting up the Collimator project for local development. The project is a monorepo containing a NestJS backend, a Next.js frontend, and a scratch application based on Create React App. Developers can set up the environment either by running each service locally using yarn or by using the provided Docker Compose configuration.

The repository is structured into several key directories, including backend, frontend, apps/scratch for the applications, e2e for end-to-end tests, and terraform for infrastructure as code.

System Architecture Overview

The Collimator project consists of multiple independent but related applications and services. The diagram below illustrates the high-level components within the repository.

This diagram shows the main applications and their relationship. The Frontend and Scratch App both interact with the Backend API.
Sources: backend/README.md, frontend/README.md, apps/scratch/README.md, e2e/tests/users/user-management.spec.ts, terraform/infrastructure/main.tf

Local Development Setup (Manual)

This section describes how to set up and run each part of the application stack manually on your local machine. The project uses yarn as its package manager.

Sources: frontend/package.json:133-133

Backend Setup

The backend is a NestJS application.

1. Install Dependencies: Navigate to the backend directory and install the required packages.

   cd backend
   yarn install
   

   Sources: backend/README.md:29-31

2. Run the Server: Start the development server in watch mode.

   # watch mode
   yarn run start:dev
   

   Sources: backend/README.md:38-39

Backend Scripts

The backend package.json defines several scripts for development, testing, and production builds.

Script	Description
start	Runs the application.
start:dev	Runs the application in watch mode.
start:prod	Runs the application in production mode.
test	Runs unit tests.
test:e2e	Runs end-to-end tests.
test:cov	Generates a test coverage report.

Sources: backend/README.md:35-50, backend/package.json:5-15

Frontend Setup

The frontend is a Next.js application.

1. Install Dependencies: Navigate to the frontend directory and install packages.

   cd frontend
   yarn install
   

   Sources: frontend/package.json

2. Run the Server: Start the Next.js development server.

   npm run dev
   # or
   yarn dev
   

   The application will be available at http://localhost:3000.

   Sources: frontend/README.md:5-13, frontend/package.json:6-6

Frontend Scripts

The frontend package.json includes scripts for development, testing, internationalization (i18n), and API generation.

Script	Description
dev	Starts the development server on port 3000.
build	Creates a production build.
start	Starts the production server on port 3000.
lint	Lints the codebase.
update:api	Removes and regenerates the API client from the OpenAPI spec using orval.
i18n:update	Extracts, fills, and compiles internationalization messages.
test	Runs Jest and Playwright tests.
storybook	Starts the Storybook development server on port 6006.

Sources: frontend/package.json:5-41

Scratch App Setup

The scratch application is located in the apps/scratch directory and is based on Create React App, customized with craco.

1. Initialize Submodules: The app uses git submodules which must be initialized first.

   # From the root of the repository
   git submodule update --init --recursive
   

   Sources: apps/scratch/README.md:3-3

2. Install Dependencies: Navigate to the apps/scratch directory and install packages.

   cd apps/scratch
   yarn install
   

   Sources: apps/scratch/README.md:4-4

3. Run the Server: Start the development server.

   yarn dev
   

   The server will start on port 3101.

   Sources: apps/scratch/README.md:5-5, apps/scratch/package.json:5-5

Docker-based Setup

For a more integrated setup, you can use the Docker Compose configuration provided in the docker directory. This will build and run all the necessary services in containers.

The following diagram shows the services defined in the docker-compose.yml file and their dependencies.

This diagram illustrates that the backend service depends on the PostgreSQL database. The frontend and scratch app services run independently but are designed to communicate with the backend.

Sources: docker/docker-compose.yml

Services

The docker-compose.yml file defines the following services:

Service	Image/Build Context	Ports	Description
db	postgres:16.3-alpine	5432:5432	PostgreSQL database for the backend.
backend	../backend	3001:3001	The NestJS backend application.
frontend	../frontend	3000:3000	The Next.js frontend application.
scratch	../apps/scratch	3101:3101	The Scratch React application.

To start all services, you would typically run docker-compose up from the docker directory.

Sources: docker/docker-compose.yml:5-46

Testing

The project includes a comprehensive testing setup, with unit, integration, and end-to-end tests.

• Backend: Unit tests (yarn test) and E2E tests (yarn test:e2e) are available.
  Sources: backend/README.md:44-50
• Frontend: Jest (yarn test:jest) and Playwright component tests (yarn test:playwright) are configured.
  Sources: frontend/package.json:20-30
• Scratch App: Playwright tests are used (yarn test).
  Sources: apps/scratch/package.json:8-8
• E2E: A dedicated e2e directory contains Playwright tests for cross-application user flows, such as user management and task management.
  Sources: e2e/tests/users/user-management.spec.ts, e2e/tests/task/task-management.spec.ts

Infrastructure and Deployment

The project uses Terraform to manage its cloud infrastructure on AWS. The configuration is located in the terraform/infrastructure directory. It defines modules for networking, database, backend (Fargate), frontend (S3/CloudFront), and the Scratch app (S3/CloudFront).

This setup is intended for deployment and is not required for local development, but it provides context on how the application is hosted in a production-like environment.

Sources: terraform/infrastructure/main.tf, terraform/infrastructure/modules/static-website/main.tf