Skip to content

Getting Started — Your First Day on LCO DMA

Welcome to the LCO DMA team. This is the single checklist to go from a fresh laptop to a running app, your first passing test, and your first change. Budget ~1 hour.

Reading order for week one: 1. This page (setup + first change) 2. QUICK_START.md — the condensed run commands 3. ARCHITECTURE_PRIMER.md — the 10-minute mental model 4. CLAUDE_CODE_GUIDE.md + SKILLS_MATRIX.md — how we use Claude Code here 5. .agent-context/conventions.md — the team's hard rules

What you're working on

LCO DMA is a full-stack construction cost estimation platform: a React 18 SPA backed by a FastAPI service on Azure Cosmos DB. It replaces spreadsheet-based estimating with structured estimation, loan-monitoring, project-controls, and claims services across 9 MTO (material take-off) disciplines. 40 pages, 39 API routers, 30 Cosmos containers. It's a production system — see ARCHITECTURE_PRIMER.md for how it all fits together.

✅ Day-One Checklist

1. Install the toolchain

Tool Why Install
Node.js 20.19+ (22.x ok) Frontend (Vite/React) https://nodejs.org/
uv All Python deps + the pinned Python 3.12 (we never use pip) curl -LsSf https://astral.sh/uv/install.sh \| sh
just The command runner — every workflow goes through it brew install just
gh (GitHub CLI) PRs, issues (we use gh, not the GitHub MCP) brew install gh
Docker (optional) Only for just test-backend-integration https://docker.com

Verify: 

node --version && uv --version && just --version && gh --version

2. Get access

  • [ ] GitHub — push access to the repo; gh auth login
  • [ ] Cosmos DB (dev) — ask a teammate for the dev COSMOS_ENDPOINT and COSMOS_KEY. Local dev points at the shared dev Cosmos account — we do not run a local emulator.
  • [ ] Azure (if deploying) — Azure CLI access to the subscription
  • [ ] Atlassian — Jira + Confluence (compassdataanalytics.atlassian.net) for tickets and docs

3. Clone and configure

git clone <repository-url>
cd LCO-DMA

cp backend/.env.example backend/.env
# edit backend/.env: set COSMOS_ENDPOINT, COSMOS_KEY, DATABASE_NAME=lco-construction

The frontend runs on defaults; only create frontend/.env.local (from frontend/.env.example) if you need to override the API URL or auth. Blob Storage / Service Bus vars in backend/.env are only needed if you're working on the async import pipeline.

4. Install dependencies

just install      # npm install (frontend) + uv sync (backend)

5. Run the app

just dev          # backend :8000 + frontend :5173 in parallel

Verify: - [ ] http://localhost:5173 — the app loads - [ ] http://localhost:8000/api/v1/health — {"status":"healthy", ... "database":"connected"} - [ ] http://localhost:8000/api/docs — interactive Swagger

just stop frees the ports when you're done.

6. Run the test suites

just test-frontend       # Vitest
just test-backend        # pytest (unit)

Backend integration tests (just test-backend-integration) need Docker and the Cosmos emulator. If those fail without Docker, that's expected — they're not part of the default local loop.

7. Learn the quality gate

Before any commit, the team runs:

just check     # lint + typecheck everything (fast)
just quality   # full lint/format/types (frontend + backend)
just ci        # quality + tests + build (the full gate)

just --list shows every recipe. Everything goes through just — see JUSTFILE recipes below.

🛠️ Your First Change (end-to-end)

A safe first PR to learn the loop:

  1. Branch off dev (never main): 
    git switch dev && git pull
git switch -c chore/<your-name>-onboarding
# or use an isolated worktree: just worktree chore/<your-name>-onboarding
  2. Make a small change — e.g. fix a typo in a doc, or add yourself to a CONTRIBUTORS list.
  3. Run the gate: just check (and just test if you touched code).
  4. Commit (conventional style, no AI attribution): 
    git add -A && git commit -m "chore: onboarding warm-up change"
  5. Open a PR targeting dev: 
    gh pr create --base dev --fill
    (The team also has a /create-pr Claude Code skill that writes a structured PR for you.)
  6. Watch the PR bot — an automated review runs on the PR. Address comments (the /pr-bot-review skill helps). dev → main happens via a weekly release PR.

🧭 How the team works (the short version)

  • Branching: main = production, dev = integration. Feature/fix branches come off dev, and PRs target dev. dev → main is a periodic weekly release merge.
  • Conventions are written down: .agent-context/conventions.md (always/never rules), .agent-context/practices.md (review style + known pain points), and .claude/rules/ (codegen guardrails). Read these before non-trivial work — they encode hard-won lessons.
  • Frontend styling is strict: semantic design tokens only — text-lco-* typography and bg-card/text-foreground colors, never raw text-sm/bg-white/text-neutral-*. Use the /design-system skill for any UI work.
  • Backend is async-first + repository pattern: routers → schemas → repositories → Cosmos, with require_auth on every endpoint and parameterized queries only.
  • We use Claude Code heavily. See CLAUDE_CODE_GUIDE.md for how skills, agents, rules, and MCP servers work, and SKILLS_MATRIX.md for which skill to reach for at each stage.

🩺 Troubleshooting first-day snags

Symptom Fix
command not found: just / uv Install them (step 1); reopen your shell
Backend: Failed to initialize database Check backend/.env Cosmos creds point at the dev account
Backend: No module named ... just install-backend (runs uv sync)
Port 8000 / 5173 in use just stop (or lsof -i :<port> then kill -9 <pid>)
Frontend dependency errors cd frontend && rm -rf node_modules && npm install
Integration tests fail with no DB Expected without Docker — use unit tests + the running app
Type errors after pulling just install (deps may have changed), then just check

If you're stuck > 15 minutes, ask in the team channel — onboarding friction is a bug we want to fix.

Where to go deeper

I want to… Read
Understand the architecture ARCHITECTURE_PRIMER.md → ARCHITECTURE.md
Work on the backend backend/ARCHITECTURE.md, backend/README.md
Work on the frontend frontend/ARCHITECTURE.md, frontend/DEVELOPER_GUIDE.md
Understand the data model database/INDEX.md
Understand auth auth/AUTH_IMPLEMENTATION.md
Add an API endpoint the /api-endpoint skill + backend/ARCHITECTURE.md
Navigate all docs index.md and KNOWLEDGE_BASE.md

Appendix: Common just recipes

Task Recipe
Run both servers just dev
Frontend / backend only just dev-frontend / just dev-backend
Import worker just dev-worker
Install everything just install
Fast check (no tests) just check
All quality checks just quality
All tests just test
Full CI gate just ci
Production build just build
Stop dev servers just stop
New worktree just worktree <branch> [base]
Sync Confluence → wiki/ just confluence-sync
Sync Jira → jira/ just jira-tickets-sync

Run just --list for the complete, annotated list.