Skip to content

LCO DMA — Quick Start Guide

Get the LCO Data Management Application running on your local machine in under 10 minutes.

New here? Start with GETTING_STARTED.md for the full first-day checklist and ARCHITECTURE_PRIMER.md for the mental model. This page is the fast path to a running app.

Prerequisites

Install these tools before starting:

  1. Node.js 20.19+ (22.x recommended) 

    node --version
    Download from https://nodejs.org/.

  2. uv — Python package & environment manager (we do not use pip or raw python) 

    uv --version
curl -LsSf https://astral.sh/uv/install.sh | sh   # if not installed
    uv provisions and pins the project's Python 3.12 automatically — you don't need a system Python 3.12.

  3. just — command runner (the single entry point for every workflow) 

    just --version
brew install just        # macOS

  4. Azure Cosmos DB access — local dev connects to the shared dev Cosmos DB, not a local emulator. Ask a teammate for the COSMOS_ENDPOINT / COSMOS_KEY for the dev account (see Step 2).

  5. (Optional) Docker — only needed for just test-backend-integration, which spins up the Cosmos emulator.

Quick Setup (5 Steps)

Step 1: Clone the Repository

git clone <repository-url>
cd LCO-DMA

Step 2: Configure Backend Environment

cp backend/.env.example backend/.env

Edit backend/.env with the dev Cosmos DB credentials (get them from a teammate):

COSMOS_ENDPOINT=https://<dev-account>.documents.azure.com:443/
COSMOS_KEY=<dev-primary-key>
DATABASE_NAME=lco-construction

backend/.env.example documents every variable (Blob Storage and Service Bus are only needed if you work on the async import pipeline). The frontend works with defaults; create frontend/.env.local from frontend/.env.example only if you need to override the API URL or auth settings.

Step 3: Install Dependencies

From the project root:

just install

This runs npm install for the frontend and uv sync for the backend. To do one side only:

just install-frontend   # npm install in frontend/
just install-backend    # uv sync in backend/

Step 4: Start Both Servers

just dev

This launches the backend (FastAPI on :8000) and frontend (Vite on :5173) in parallel. To run them separately in two terminals:

just dev-backend    # FastAPI @ http://localhost:8000  (runs backend/start-dev.sh)
just dev-frontend   # Vite     @ http://localhost:5173

Both reload on save (Uvicorn watch mode + Vite HMR) — no restarts needed during development.

To stop servers and free their ports:

just stop

Step 5: Verify Everything Works

  1. Frontend loads — open http://localhost:5173, you should see the LCO DMA app.
  2. Backend health — http://localhost:8000/api/v1/health returns: 
    { "status": "healthy", "service": "LCO API", "version": "2.0.0", "database": "connected" }
  3. API docs — interactive Swagger at http://localhost:8000/api/docs.

Common Issues & Solutions

Backend won't start

command not found: uv — install uv (Prerequisites step 2), then just install-backend.

Failed to initialize database — check backend/.env: - COSMOS_ENDPOINT starts with https:// and ends with :443/ - COSMOS_KEY is the full primary key - You're pointed at the dev account you were given (not a placeholder)

Port 8000 already in use — just stop, or lsof -i :8000 then kill -9 <PID>.

Frontend won't start

Dependency / lockfile errors — clean install: 

cd frontend && rm -rf node_modules && npm install

Port 5173 in use — Vite auto-increments to 5174, 5175, … (CORS origins for these are pre-configured).

API calls fail

CORS errors — confirm the backend is running on :8000. BACKEND_CORS_ORIGINS in backend/.env already allows localhost:5173/5174.

404 on API calls — the frontend calls the /api/v1 prefix; confirm the backend is up.

Tests fail locally

Backend integration tests need Docker (just test-backend-integration starts the Cosmos emulator). Plain just test-backend runs the unit suite. If an integration test fails because it can't reach a DB, that's expected without Docker — verify behavior against the running app instead.

Quality & Tests (before you commit)

just check     # lint + typecheck everything (fast, no tests)
just quality   # frontend + backend lint/format/types
just test      # backend + frontend test suites
just ci        # full gate: quality + tests + build
just build     # production frontend build

Run just --list to see every recipe. All workflows go through just — don't hand-roll npm/uv pipelines when a recipe exists.

Next Steps

Production Deployment

See backend/README.md for Azure deployment, and the deploy recipes (just deploy-containers, just deploy-flex, just deploy-import-processor).