Onboarding — first day to first commit

Goal: clone the repo, run the full stack, understand the shape of the system, and open your first pull request — in one day. Work through the checklist in order; each step links to the doc that goes deeper.

Your day at a glance:

Step	What you'll have afterwards	Time
1. Prerequisites	Docker, Node, Java installed	~15 min
2. Run the stack	The app running at localhost:5173	~10 min
3. Poke around	A feel for what the product does	~20 min
4. Run the tests	All three suites green locally	~30 min
5. Pick your dev loop	Fast edit-reload for your area	~10 min
6. Monitoring (optional)	Grafana dashboards over your local stack	~10 min
7. Understand the system	The mental map	~2 h reading
8. First commit & PR	Your first merged PR	rest of the day

The system in one minute

MotorPH is a Philippine-compliance payroll SaaS: a Spring Boot backend, a React frontend (served as a static build by nginx), and PostgreSQL, all wired together by Docker Compose. A Mailpit container catches every email the app sends so nothing leaves your machine.

 your browser ──► frontend (nginx)      :5173
                       │ /api proxied to
                  backend (Spring Boot) :8081   ──► Swagger at :8081/swagger-ui.html
                       │                        ──► emails to Mailpit UI at :8025
                  PostgreSQL            :5434 (host port; 5432 inside Docker)

Where things live in the repo:

Path	What it is
backend/	Spring Boot app — API, payroll engine, Flyway migrations
frontend/	React + Vite + Chakra v3 + AG Grid
e2e/	Playwright end-to-end suite (runs against the Docker stack)
docs/	You are here — docs/README.md is the index
docker-compose.yml	The local dev stack (the one you'll use daily)
docker-compose.monitoring.yml	Optional Grafana/Prometheus/Loki/Tempo overlay
deploy/, infra/	VPS deployment scripts and infra config (Caddy, Traefik, monitoring)
dev.sh	Backend-on-host dev loop helper
.github/	CI workflows and the PR template

1. Prerequisites

• Docker with the compose plugin (docker compose version) — the only hard requirement for running the stack.
• Node.js 24+ and npm — for the frontend dev server and the Playwright suite.
• Java 21 + Maven — only needed for the backend host-run dev loop and mvn test (the Docker build compiles the backend for you otherwise; ./mvnw at the repo root belongs to the legacy JavaFX app, use your own mvn for backend/).
• openssl (any Linux/macOS has it) — used once to generate a JWT secret.

2. Run the stack

• Clone and start (README — Run it):

  git clone https://github.com/jomariabejo/MotorPH-Enterprise-Payroll-System-v2.git
  cd MotorPH-Enterprise-Payroll-System-v2
  cp .env.example .env
  sed -i "s/^JWT_SECRET=.*/JWT_SECRET=$(openssl rand -hex 64)/" .env
  docker compose up -d --build

  The JWT step is not optional — the backend refuses to boot with the placeholder secret. First boot takes a few minutes; watch docker compose logs -f motorph_payroll_backend until Flyway finishes and docker compose ps shows the backend (healthy).

• Open http://localhost:5173 and log in as sysadmin_demo — the password is in reference/demo-users.md.

Success looks like: the login page loads, the demo login works, and you see a dashboard. If not, jump to Common first-day snags — and for anything not listed there, troubleshooting.md opens with a three-command triage flow and a symptom index. It's written so you can get unstuck without waiting on anyone; work through it before asking.

3. Poke around

• Log in as a few different personas — all seeded accounts are in reference/demo-users.md.
• Try the role switcher in the profile menu — most demo users hold several roles, and the visible navigation changes with the active role (frontend/auth-and-permissions.md).
• Open Swagger at http://localhost:8081/swagger-ui.html and call GET /api/auth/me with a token (api/README.md).
• Open Mailpit at http://localhost:8025 — every email the app sends lands here instead of the internet (backend/email.md).

4. Run the tests

Details for all three suites: testing/README.md.

• Backend unit/integration tests: cd backend && mvn test (repo-root mvn test runs nothing — it belongs to the legacy app).

• Frontend unit tests: cd frontend && npm install && npm test

• E2E (Playwright) — needs the Docker stack running and ALTCHA_ENABLED=false (the default). From the repo root:

  npm install
  npx playwright install --with-deps chromium
  npx playwright test --project=chromium e2e/login.spec.ts

  Read e2e/README.md before running the full suite — it documents the demo personas, seed-data baselines, and serial-mode conventions. Don't run it while someone else's run is using the same stack.

These local suites matter more here than in most repos: CI runs CodeQL and gitleaks, but backend and frontend tests are not CI-enforced — your local green run is the merge gate (git-workflow.md).

5. Pick your dev loop

Loop	How	When to use
Full Docker	edit → docker compose up -d --build	Closest to prod; slow (image rebuild per change — the frontend image is a static build, it never hot-reloads)
Frontend HMR	stack up in Docker, then cd frontend && npm run dev → http://localhost:5173 is nginx, the Vite dev server picks its own port and proxies nothing — set VITE_API_URL=http://localhost:8081 in frontend/.env.local so API calls reach the backend, and make sure that origin is in CORS_ALLOWED_ORIGINS	Day-to-day frontend work
Backend on host	./dev.sh (starts only Postgres in Docker, then mvn spring-boot:run → backend on :8080)	Day-to-day backend work with instant restarts

6. See the monitoring stack (optional, recommended)

The repo ships a full observability overlay — Prometheus (metrics), Loki (logs), Tempo (traces), Grafana (dashboards), Alertmanager — that layers onto the same dev stack with one command:

• Start it:

  docker compose -f docker-compose.yml -f docker-compose.monitoring.yml up -d

• Open Grafana at http://localhost:3000 (admin/admin by default) and browse the provisioned dashboards — start with Server Health and the auth-security dashboard, then click around Explore to query Loki logs.

• Prometheus is at http://localhost:9090, Alertmanager at http://localhost:9093. All monitoring UIs bind to 127.0.0.1 on purpose — see deployment/monitoring.md for why (Docker's port publishing bypasses UFW).

Two things worth knowing on day one:

• This is the same overlay production uses — learning it locally means you can read the prod dashboards later.
• To stop it, use the same two -f flags with stop. A plain docker compose down (single -f) leaves the monitoring containers orphaned.

Everything else — the dashboard catalog, alert rules, tracing, how promtail parses the app's JSON logs — is in deployment/monitoring.md.

7. Understand the system (reading order)

• architecture.md — the map: services, route trees, where authn/authz happen.
• erd.md + business-rules.md — the data model and the payroll rules it exists to serve.
• learn/employees-walkthrough.md — a guided end-to-end trace of one feature (/employees) through every layer.
• learn/build-a-module-page.md — the companion recipe: how to build a page like that yourself, end to end (migration → backend → permissions → grid/drawers/actions/filters → tests). When you get your first "add a new page" task, this is the doc to follow.
• coding-standards.md and git-workflow.md.

8. First commit & PR

• Branch from main: git checkout -b feature/<short-name>.
• Make a small change (a doc fix counts; a grid page tweak is a good starter — see frontend/ag-grid.md).
• Verify: stack still builds (docker compose up -d --build), relevant tests pass, cd frontend && npm run lint is clean for frontend changes.
• Commit with a conventional-commit subject — feat(scope): …, fix(scope): …, docs: … (git-workflow.md has real examples from history).
• Push and open a PR against main. GitHub pre-fills the PR template — fill it honestly rather than deleting it:
  • Summary / Changes — what and why, for a reviewer with no context.
  • Testing — check only what you actually ran; the manual-verification line is the part only you can write.
  • Database / Breaking / Deployment sections carry the repo's sharp edges (migration numbering, tenant scoping, nginx config being baked into the image). If a section doesn't apply, say "None." — that's a useful answer.
• CI runs CodeQL and gitleaks on every PR; Playwright's real signal is your local run (deployment/ci.md).

The one rule to internalize before your first merge: merging to main deploys to production — automatically, a few health-gated minutes after staging goes green. Merge only what you'd ship (git-workflow.md).

Common first-day snags

Symptom	Fix
Backend crash-loops immediately after up	You skipped the JWT_SECRET step — the log says exactly this. Fix .env, docker compose up -d.
Blank page / API errors right after startup	Backend still migrating; wait for (healthy) in docker compose ps.
429 or account locked while testing logins	Login rate limit (10/min/IP) or exponential lockout. Wait, or restart the backend (limits are in-memory): docker compose restart motorph_payroll_backend.
Ports 5173/8081/5434 taken	Set FRONTEND_PORT/BACKEND_PORT/POSTGRES_PORT in .env (and add the new frontend origin to CORS_ALLOWED_ORIGINS).
Edited frontend code but nothing changed on :5173	:5173 is a static nginx build — it never hot-reloads. Rebuild the image, or use the Frontend HMR loop from step 5.
Monitoring containers still running after docker compose down	The overlay needs both files: docker compose -f docker-compose.yml -f docker-compose.monitoring.yml down.

Anything else: troubleshooting.md — start with its triage flow (docker compose ps → backend logs → docker compose config), then find your symptom in its index. It covers Docker daemon/permission problems, Flyway errors, disk space, e2e/Playwright failures, Mailpit, and the monitoring overlay.