Getting Started

Prerequisites

• JDK 21. Maven isn't needed; the backend ships the Maven wrapper.
• Node.js 24 and npm
• Docker, for PostgreSQL and for Testcontainers in backend tests
• Git and the GitHub CLI (gh), used by the workflow skills
• Claude Code (optional), started from the repo root

Clone

git clone https://github.com/amalps565/Smart-Workspace-Seating-Chart.git
cd Smart-Workspace-Seating-Chart

Run locally

# 1. PostgreSQL 17 on localhost:5432 (database, user, and password: seating)
docker compose up -d --wait

# 2. Backend on http://localhost:8080 (from backend/; Flyway creates the schema and seed data)
./mvnw spring-boot:run          # Windows: .\mvnw.cmd spring-boot:run

# 3. Frontend on http://localhost:5173 (from frontend/, in a second terminal)
npm install
npm run dev

Open http://localhost:5173 and sign in:

Username	Password	Name
alice	password	Alice Anders
bob	password	Bob Brown
carol	password	Carol Chen
dave	password	Dave Diaz
erin	password	Erin Evans

Floor 3 (8 × 12, 4-side neighbours, walkway down the middle) and Floor 4 (4 × 6, 8-way neighbours) are seeded. Open a private window as a second user to watch bookings update live.

Port 5432 already in use?

See Troubleshooting for this and other local problems.

If a local PostgreSQL service already uses 5432, the backend fails with password authentication failed for user "seating". Either:

• run Compose on another port: POSTGRES_PORT=5433 docker compose up -d --wait, then start the backend with DB_URL=jdbc:postgresql://localhost:5433/seating; or
• skip Compose: run ./mvnw spring-boot:test-run in backend/ for a throwaway Testcontainers database.

Tests

# Backend (from backend/, Docker must be running)
./mvnw verify
./mvnw test -Dtest=BookingConcurrencyTest

# Frontend (from frontend/)
npm run typecheck
npm run lint
npm test
npx vitest run src/features/floor

# End to end (from e2e/; starts or reuses the backend and frontend)
npm install
npm run install:browsers
npm test
npx playwright test -g "neighbouring desks"

CI runs all three suites on every pull request and push to main.

Configuration

Variable	Default	Purpose
DB_URL	jdbc:postgresql://localhost:5432/seating	Database URL
DB_USERNAME / DB_PASSWORD	seating / seating	Database credentials
JWT_SECRET	dev-only value	JWT signing key, at least 32 bytes. Always set it outside local development.
BOOKING_ZONE	UTC	Office time zone that defines "today"
POSTGRES_PORT	5432	Host port for the Compose PostgreSQL

Local-only backend settings go in backend/src/main/resources/application-local.yml, which is gitignored. Secrets go in .env files, which are gitignored.