RetroLoop - Sprint Retrospective Tool

A real-time collaborative sprint retrospective application built with Next.js, NestJS, and WebSockets.

Project Structure

retroloop/
├── apps/
│   ├── back/          # NestJS backend API + WebSocket server
│   └── front/         # Next.js frontend application
├── packages/
│   └── shared-types/  # Shared TypeScript types and interfaces
└── docs/              # Architecture, testing, WebSocket protocol

Prerequisites

• Node.js 24+
• Yarn 4.x (packageManager is set in package.json)
• PostgreSQL 16+
• Docker & Docker Compose (recommended)

Run with Docker

Run the entire app (database + backend + frontend) with a single command:

# 1. Configure environment
cp .env.example .env
# Edit .env — at minimum set JWT_SECRET (generate with: openssl rand -base64 32)

# 2. Start everything
docker compose -f docker-compose.full.yml up --build

Once running:

• Frontend — http://localhost:3000
• Backend API — http://localhost:3001/api

To stop: docker compose -f docker-compose.full.yml down

To stop and remove data: docker compose -f docker-compose.full.yml down -v

Quick Start (Development)

# 1. Install dependencies
yarn install

# 2. Configure environment
cp .env.example .env
# Edit .env — set JWT_SECRET (generate with: openssl rand -base64 32)

# 3. Start PostgreSQL
docker-compose up -d

# 4. Build shared types
yarn workspace @retro/shared-types build-lib

# 5. Run database migrations
yarn workspace back db:migrate

# 6. Start development servers
yarn dev:back    # Terminal 1 — http://localhost:3001
yarn dev:front   # Terminal 2 — http://localhost:3000

If running PostgreSQL manually instead of Docker, create a database and set the POSTGRES_* variables in .env accordingly.

Environment Variables

All environment variables live in a single root .env file, used by Docker Compose, the backend, and the frontend.

Copy the example and fill in your values:

cp .env.example .env

Required

Variable	Description	Example
JWT_SECRET	Secret key for JWT token signing (minimum 32 characters)	Generate with: openssl rand -base64 32

Core Configuration

Variable	Description	Default
POSTGRES_USER	PostgreSQL user	retro
POSTGRES_PASSWORD	PostgreSQL password	retro_dev_password
POSTGRES_DB	PostgreSQL database name	retro
POSTGRES_HOST	PostgreSQL host	localhost
POSTGRES_PORT	PostgreSQL port	5432
PORT	Backend server port	3001
FRONTEND_URL	Frontend URL (for CORS)	http://localhost:3000
INTERNAL_PORT	Internal observability port (metrics)	9090
NEXT_PUBLIC_API_URL	Backend API base URL (frontend)	http://localhost:3001/api
NEXT_PUBLIC_WS_URL	WebSocket server URL (frontend)	http://localhost:3001

Optional Integrations

Group	Variables	Setup
Google OAuth	GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_CALLBACK_URL	Google Cloud Console
Email (Mailgun)	MAILGUN_API_KEY, MAILGUN_DOMAIN, MAILGUN_EU_HOST, EMAIL_FROM	mailgun.com
Sentry	SENTRY_DSN, SENTRY_ENABLED, NEXT_PUBLIC_SENTRY_DSN, NEXT_PUBLIC_SENTRY_ENABLED, SENTRY_ORG, SENTRY_PROJECT, SENTRY_AUTH_TOKEN	sentry.io
DB Pool Tuning	DB_POOL_MIN, DB_POOL_MAX, DB_POOL_IDLE_TIMEOUT_MS, DB_POOL_CONNECTION_TIMEOUT_MS	See .env.example for defaults

See .env.example for full documentation on every variable.

Available Scripts

Root Level

Command	Description
yarn dev:back	Start backend in development mode
yarn dev:front	Start frontend in development mode
yarn build:back	Build backend for production
yarn build:front	Build frontend for production
yarn build-lib	Build all library packages
yarn lint	Run ESLint on all packages
yarn lint:fix	Run ESLint with auto-fix
yarn format	Format all files with Prettier

Backend (apps/back)

Command	Description
yarn workspace back start:dev	Start in watch mode
yarn workspace back build	Build for production
yarn workspace back test	Run unit tests
yarn workspace back test:e2e	Run E2E tests
yarn workspace back db:generate	Generate new migration
yarn workspace back db:migrate	Run pending migrations
yarn workspace back db:push	Push schema to database (dev)
yarn workspace back db:studio	Open Drizzle Studio

Frontend (apps/front)

Command	Description
yarn workspace front dev	Start in development mode
yarn workspace front build	Build for production
yarn workspace front start	Start production server
yarn workspace front test	Run unit tests

Tech Stack

Backend

• NestJS 11
• Drizzle ORM
• PostgreSQL
• Socket.IO (WebSockets)
• Passport.js (JWT Authentication)

Frontend

• Next.js 16 (App Router)
• React 19
• Tailwind CSS
• Framer Motion
• Socket.io Client

Shared

• TypeScript
• Yarn Workspaces
• ESLint + Prettier
• Husky (Git hooks)

Documentation

Document	Description
Architecture	System diagram, module overview, database schema, data flows
WebSocket Protocol	Full WebSocket event reference
Testing Guide	How to write, run, and maintain tests
Contributing	Code style, commit conventions, PR process
Backend README	Backend architecture, commands, migrations, deployment
Frontend README	Frontend architecture, components, data fetching
Security Policy	Vulnerability reporting
Support	Getting help

License

This project is licensed under the MIT License - see the LICENSE file for details.