Skip to content

Repo Setup Guide

Written by Marcel Stoltz
24 Apr 2026

Purpose

This guide serves as a repo setup guide for the 2026 Vigil Capstone Team, specifically for the UMTAS Project.

Our Approach to the Ideal Developer Experience

We use pnpm workspaces via root scripts such as TurboRepo.

The goal?
Frontend devs never need to worry about Python dependencies, and backend devs don't have to struggle with venv.

The "One Command" Workflow

A: Bootstrap a New Dev

pnpm run setup
What happens during setup?
  1. Tool Check: Verifies docker, pnpm, and node versions.
  2. Env Config: Copies .env.example to .env.
  3. Install: Runs pnpm install across all workspaces.
  4. Solver Prep: Pulls or builds the Docker image for the Python solver.

B: Development Lifecycle

We use a split strategy for the fastest hot-reload performance.

pnpm run dev:infra # (1)
  1. Starts Postgres, Redis, MinIO, and the Python Solver container.
pnpm run dev # (2)
  1. Boots Turborepo to run the Next.js frontend and NestJS backend natively.

Deployment & Advanced Modes

While local native dev is fastest, we maintain Docker profiles for full system testing.

Full Docker Stack

Command: pnpm run dev:docker

Boots the full infrastructure PLUS the frontend and backend in containers. Use this to verify network flows and environment variables before a merge.

Monitoring Mode (PLG Stack)

Command: pnpm run dev:monitor

Adds the observability layer:

  • Grafana: Dashboards
  • Prometheus: Metrics
  • Loki: Log Aggregation

Quality Assurance

  1. Unit & Integration: Powered by Jest.
  2. E2E: Powered by Playwright.
  3. Pre-commit Hooks: Managed by Husky + Lint Staged.
  4. Local CI Simulation: Run your GitHub Actions locally using act.

Troubleshooting

Docker Permission Denied

Ensure your user is part of the docker group:

sudo usermod -aG docker $USER
PNPM Lockfile Conflicts

If you encounter lockfile issues after a heavy merge, run:

pnpm install --no-frozen-lockfile