Onboarding

Owner: Engineering Last reviewed: 2026-Q2

Objective: Get new engineers productive on day 3 with a working local setup and first PR.

Week 0 (Pre-Start)

• Create Azure DevOps access, ACR, and App Service read permissions
• Invite to Clerk and required third-party tools
• Assign a buddy; share this handbook

Day 1: Access + Local Setup

• Clone repo; read README.md and this handbook
• Frontend: copy frontend/env.example → .env (API URL, Clerk key) → npm ci && npm run dev
• Backend: copy backend/py/env.example → .env (DB, Clerk, Azure) → run python backend/py/main.py (or uvicorn)
• Database: install or connect to PostgreSQL, set backend DB env vars, then run alembic upgrade head from backend/py
• Azure: request dev credentials only for the services needed by your work; use mocks for routine tests
• Verify: health endpoints, login via Clerk, basic Kanban operations

Day 2: First Change

• Pick a labeled “good first issue” or small doc/UX polish
• Follow the Workflow doc: small PR, tests, orval regen if needed
• Get at least one review; deploy to dev and validate

Day 3-5: Deep Dive

• Tour: api/routes, schemas, services, models, ADRs
• Debugging and observability: read Azure Monitor traces/metrics for a dev deploy
• Security tour: auth flow (core/authentication.py), authorization (core/authorization.py), file validation (core/config.py)

Expectations

• Ask questions early; keep PRs small
• Update docs when you learn something non-obvious
• Prefer paved paths over custom solutions until you’ve synced with the team