LCO DMA - Data Management Application¶

Full-stack web application for LCO Construction Consulting providing cost estimation, project controls, loan monitoring, and claims management services. Built with React 18, FastAPI, and Azure Cosmos DB.

Project Overview¶

The LCO DMA is a comprehensive construction data management system with 40 pages, 39 API routers, and 30 Cosmos DB containers. Key capabilities include:

Cost Estimation: Detailed cost estimates with crew compositions, material takeoffs (MTO) across 9 disciplines, equipment requirements, subcontractors, and indirect cost calculations
Estimation Overview and Comparison: Side-by-side estimation comparisons with KPI drill-down, PDF export, and caching
WBS Management: Work Breakdown Structure builder with versioning, hierarchical editing, and project-level WBS assignment
COA & KPIs: Commodity codes and key performance indicators (L1-L8) via canonical coa-kpis container
Scheduling Workflows: Multi-schedule workflow management with P6 SQLite import, activity mapping templates, and schedule comparison
S-Curve Reporting: Planned vs. actual vs. remaining progress curves with drill-down by discipline
Waterfall Breakdowns: Cost waterfall analysis showing cost progression and variance
Executive Summary: High-level project cost and progress summary
Dynamic Reporting: Historical reporting with configurable parameters and chart types
Labor Distribution Reports: Labor cost breakdowns across crews, trades, and disciplines
Manpower Plans: Resource loading and manpower projection reports
Packages, Systems, and Subsystems: Project organizational structures for grouping estimation items
Custom Columns: User-defined columns on estimation items for project-specific data
Demo Data System: Configurable demo data generation for presentations and testing
Dropdown Options: Configurable dropdown values for standardized data entry
Equipment Tags: Project-level equipment tagging and tracking
Reference Tables: Universal tables for crews, crew trades, crew members, equipment, WBS, material, and COA & KPIs
Role-Based Access Control: Reader/Contributor roles with Microsoft Entra ID and API key authentication
Excel Import/Export: Async MTO imports via Azure Functions with batch processing and progress tracking

Architecture¶

System Design¶

Frontend: Single-page application (SPA) using React 18 with client-side routing
Backend API: RESTful API built with FastAPI on Azure Container Apps (Gunicorn + Uvicorn workers)
Import Processor: Dedicated Azure Function worker for async MTO file imports (Service Bus triggered)
Database: Azure Cosmos DB (NoSQL) with document-based storage (30 containers)
Message Queue: Azure Service Bus for async processing of long-running operations
Blob Storage: Azure Blob Storage for temporary file storage during imports and schedule data
Observability: Azure Monitor with OpenTelemetry instrumentation
Deployment:
Frontend: Azure Static Web Apps (production + UAT)
Backend API: Azure Container Apps (dev + UAT)
Import Processor: Azure Function App (lco-dma-import-processor)
API Communication: Frontend proxies API requests through Vite dev server locally; Azure routing in production
Async Processing: User -> FastAPI -> Service Bus -> Azure Function -> Cosmos DB

Key Architectural Patterns¶

Repository Pattern: Backend isolates data access logic in repository classes (31 repositories)
Schema Validation: Pydantic models enforce type safety and validation on both request/response (31 schemas)
Path Aliasing: Both frontend (@/) and backend use absolute imports for cleaner code
Async-First: Backend uses async/await throughout for optimal performance with Cosmos DB
Component Composition: Frontend leverages Radix UI primitives with custom styling via Tailwind CSS
Queue-Based Processing: Long-running imports use Service Bus for reliable async execution
Batch Processing: Large datasets processed in configurable batches (default: 100 items)
Checkpointing: Import progress saved to Cosmos DB for resumability on failures
3-Level Retry: Batch retries (3x) -> Service Bus retries (10x) -> Manual checkpoint resume
Hook Factories: createInfiniteResourceHook for paginated data with deduplication
Zustand Stores: 3 global stores (authStore, projectStore, demoDataStore) for state management
Lazy Loading: Heavy analysis pages loaded on demand via React.lazy/Suspense
Query Persistence: TanStack Query cache persisted to localStorage for faster navigation
Dual Authentication: Microsoft Entra ID JWT + API key alternate authentication

Tech Stack¶

Frontend¶

Framework: React 18.3.1
Language: TypeScript 5.8.3
Build Tool: Vite 6.3.6
Router: React Router DOM 6.30.1
State Management: Zustand 5.0.8
Data Fetching: TanStack React Query 5.90.11
Tables: TanStack React Table 8.21.3
Virtualization: TanStack React Virtual 3.13.12
UI Components: Radix UI primitives (Dialog, Dropdown, Tabs, Toast, etc.)
Styling: Tailwind CSS 3.4.17 with custom theme
Design System: shadcn/ui (component library built on Radix UI)
Forms: React Hook Form 7.71.1 + Zod 4.3.5
Charts: Recharts 2.15.4
Icons: Lucide React 0.542.0
HTTP Client: Axios 1.11.0
PDF Generation: jsPDF 4.2.0 + jspdf-autotable 5.0.7
Excel: xlsx 0.18.5, xlsx-js-style 1.2.0
SQLite (P6 Import): sql.js 1.13.0
Drag and Drop: dnd-kit (core, sortable, modifiers)
Markdown: react-markdown 10.1.0 with remark-gfm, rehype-raw
Authentication: MSAL Browser 4.27.0, MSAL React 3.0.23
Testing: Vitest 4.0.13, Testing Library
Node Version: 20.19.0+

Backend¶

Framework: FastAPI 0.104.0+
Language: Python 3.12
Runtime: Uvicorn (ASGI server), Gunicorn (production)
Database: Azure Cosmos DB 4.5.0+
Authentication: fastapi-azure-auth 5.0.0+, bcrypt 4.0.0+
Message Queue: Azure Service Bus 7.11.0+
Blob Storage: Azure Blob Storage 12.19.0+
Schema Validation: Pydantic 2.5.0+, pydantic-settings 2.1.0+
Serverless: Azure Functions 1.18.0+
HTTP Client: httpx 0.26.0+
File Parsing: pandas 2.0+, openpyxl 3.1+, xlrd 2.0+, python-calamine 0.6+, pyarrow 14.0+
Serialization: orjson 3.9.0+
Observability: azure-monitor-opentelemetry 1.0.0+, opentelemetry-instrumentation-fastapi
Environment: python-dotenv 1.0.0+

Code Quality and Testing¶

Frontend: - Linter: ESLint 9.32.0 with TypeScript ESLint - Type Checking: TypeScript compiler (tsc) - Testing: Vitest 4.0.13 with Testing Library - Plugins: React Hooks, React Refresh

Backend: - Linter: Ruff (replaces flake8, isort, black) - Type Checker: mypy (Python 3.12 target) - Testing: pytest 7.4.0+, pytest-asyncio 0.21.0+ - Line Length: 100 characters - Python Target: 3.12

Project Structure¶

lco-dma/
├── frontend/                     # React SPA
│   ├── src/
│   │   ├── auth/                 # MSAL authentication config and helpers
│   │   ├── components/           # Reusable UI components
│   │   │   ├── auth/             # Auth overlay, role guards, login button
│   │   │   ├── sidebar/          # Project context card, sidebar sub-components
│   │   │   └── ui/               # shadcn/ui base components
│   │   ├── config/               # Configuration (API URLs, environment)
│   │   ├── constants/            # Application constants
│   │   ├── contexts/             # React contexts
│   │   ├── data/                 # Static/demo data
│   │   ├── hooks/                # Custom React hooks (orchestrators, factories)
│   │   ├── lib/                  # Third-party library configurations
│   │   ├── pages/                # 40 route-level page components
│   │   ├── schemas/              # Zod validation schemas
│   │   ├── services/api/         # Axios API clients (35+ service modules)
│   │   ├── stores/               # Zustand stores (auth, project, demoData)
│   │   ├── test/                 # Test utilities and setup
│   │   ├── types/                # TypeScript type definitions
│   │   └── utils/                # Utility functions
│   ├── package.json
│   ├── vite.config.ts
│   ├── tsconfig.json
│   ├── eslint.config.js
│   ├── tailwind.config.js
│   └── components.json           # shadcn/ui configuration
│
├── backend/                      # FastAPI application
│   ├── app/
│   │   ├── api/v1/routers/       # 39 FastAPI route handlers
│   │   ├── core/                 # Config, auth, observability
│   │   │   ├── config.py         # Settings (env variables, container names)
│   │   │   ├── auth.py           # Entra ID + API key auth
│   │   │   └── observability.py  # OpenTelemetry setup
│   │   ├── db/
│   │   │   └── cosmos.py         # Cosmos DB client (30 containers)
│   │   ├── repositories/         # 31 data access repositories
│   │   ├── schemas/              # 31 Pydantic model modules
│   │   ├── services/             # Business logic services
│   │   │   ├── import_processing/  # Shared import handler registry
│   │   │   ├── parsers/          # Excel/file parsing
│   │   │   ├── primavera/        # P6 schedule parsing
│   │   │   ├── schedule/         # Schedule processing
│   │   │   ├── scurve/           # S-Curve calculations
│   │   │   ├── exporters/        # Data export services
│   │   │   └── ...               # COA, waterfall, comparison, etc.
│   │   └── main.py               # Application entry point
│   ├── functions/                # Azure Functions
│   │   └── import-processor/     # MTO import worker (Service Bus triggered)
│   ├── tests/                    # Test suite
│   ├── scripts/                  # Utility scripts (migration, cleanup)
│   ├── requirements.txt          # Production dependencies
│   ├── requirements-dev.txt      # Development dependencies
│   └── pyproject.toml            # Ruff, mypy, pytest configuration
│
├── .github/workflows/            # GitHub Actions CI/CD (13 workflows)
├── docs/                         # Documentation
│   ├── features/                 # Feature-specific docs
│   ├── frontend/                 # Frontend architecture and styles
│   ├── backend/                  # Backend architecture and deployment
│   ├── auth/                     # Authentication implementation
│   ├── database/                 # Database schema and patterns
│   └── KNOWLEDGE_BASE.md         # Documentation index
│
├── package.json                  # Root-level scripts
├── staticwebapp.config.json      # Azure Static Web Apps config
├── CLAUDE.md                     # AI assistant context
└── README.md                     # This file

Data Model¶

Cosmos DB Containers¶

The application uses Azure Cosmos DB with 30 containers organized by domain:

Core Project Data:

Container	Partition Key	Description
Projects	`/clientId`	Project metadata, budgets, timelines
Clients	`/clientId`	Client organizations and contact information
Services	`/projectId`	Project services (estimation, loan monitoring, project controls, claims)

Estimation and Cost Data:

Container	Partition Key	Description
Estimations	`/serviceId`	Estimation configurations per service
EstimationItems	`/projectId`	Unified MTO + upload estimation line items
MaterialTakeoff	`/projectId`	Material quantities and specs by discipline (9 disciplines)
EstimationMasterUploads	`/projectId`	Master estimation file upload tracking
Subcontractors	`/projectId`	Subcontractor cost items per project

Crew and Labor:

Container	Partition Key	Description
Crews	`/crewId`	Master crew definitions (templates)
CrewTrades	`/tradeCode`	Trade definitions (carpenter, electrician, etc.)
CrewMembers	`/locationKey`	Individual crew member roles and base rates
ServiceCrews	`/serviceCrewId`	Crew assignments to services with rates, hours, indirect costs

Equipment and Material:

Container	Partition Key	Description
Equipment	`/equipmentCode`	Equipment catalog with rates and specifications
equipment-tags	`/projectId`	Project-level equipment tag assignments
Material	`/materialCode`	Material catalog with codes and specifications
ProjectMaterialCosts	`/projectId`	Project-specific material cost overrides

WBS and COA:

Container	Partition Key	Description
WBS	`/wbsCode`	Work Breakdown Structure definitions with versioning
coa-kpis	`/group`	COA Key Performance Indicators / commodity codes

Scheduling:

Container	Partition Key	Description
ScheduleActivities	`/projectId`	Schedule activities (P6 imported)
Schedules	`/projectId`	Multi-schedule definitions per project
SchedulingWorkflows	`/projectId`	Scheduling workflow configurations
WorkflowMappings	`/projectId`	Activity-to-WBS mapping templates

Reference and Configuration:

Container	Partition Key	Description
Packages	`/projectId`	Project work packages
SystemsSubsystems	`/projectId`	Systems and subsystems organizational structure
CustomColumnDefinitions	`/projectId`	User-defined column definitions per project
DropdownOptions	`/dropdownType`	Configurable dropdown option values
DemoDataConfig	`/projectId`	Demo data generation configuration
ApiKeys	`/keyPrefix`	API key authentication records
FileUploads	`/projectId`	File upload metadata tracking
Tasks	`/projectId`	Background task status tracking (imports, etc.)

Key Relationships¶

Client 1:N Projects (one client has many projects)
Project 1:N Services (one project has many services)
Service 1:N ServiceCrews (one service uses many crews)
Service 1:N EstimationItems (estimation line items)
Crew template -> ServiceCrew instance (crews are instantiated per service)
Project 1:N SchedulingWorkflows (multi-schedule workflows)
Project 1:1 WBS assignment (project references a WBS version)
Project 1:N Packages, Systems/Subsystems, CustomColumns

Authentication¶

The application supports dual authentication modes:

Microsoft Entra ID (Primary)¶

Frontend uses MSAL (Microsoft Authentication Library) with popup-based login
Backend validates JWT tokens via fastapi-azure-auth
Multi-tenant support with configurable allowed tenant IDs
Role-based access: Reader (view only) and Contributor (full CRUD)
Session expiration handling with automatic re-authentication prompts
Swagger UI OAuth integration for API testing

API Keys (Alternate)¶

API key authentication for programmatic/integration access
Keys managed via the Settings > API Keys page
Hashed storage using bcrypt
Key prefix-based lookup for efficient validation
Same Reader/Contributor role system

Auth Configuration¶

Auth can be disabled for local development (AZURE_AUTH_ENABLED=false, VITE_AUTH_ENABLED=false)
When disabled, a mock "Development User" with Contributor role is used
Default role assignment configurable for multi-tenant deployments

API Structure¶

Base URL¶

Local: http://localhost:8000/api/v1
Production: https://lco-api-<env>.azurecontainerapps.io/api/v1

Endpoints Overview¶

All endpoints are prefixed with /api/v1. The API has 39 routers organized into the following groups:

Projects and Clients¶

GET/POST /projects - List/create projects
GET/PUT/DELETE /projects/{projectId} - Project CRUD
GET/POST /clients - List/create clients
GET/PUT /clients/{clientId} - Client CRUD

Services¶

GET/POST /projects/{projectId}/services - List/create services per project
GET/PUT/DELETE /services/{serviceId} - Service CRUD

Crews, Trades, and Members¶

GET/POST /crews - List/create crew templates
GET/PUT/DELETE /crews/{crewId} - Crew CRUD
GET/POST /crews/trades - Crew trades
GET/POST /crews/members - Crew members
POST /crew-members/import, /crew-trades/import, /crews/import - Bulk imports

Equipment¶

GET/POST /equipment - List/create equipment
GET/PUT /equipment/{equipmentCode} - Equipment CRUD
POST /equipment/import - Bulk equipment import

Material¶

GET/POST /material - List/create material catalog entries
POST /material/import - Bulk material import
GET/POST /project-material-costs - Project-specific material cost overrides

Service Crews¶

GET/POST /service-crews - List/create service crew instances
GET/PUT/DELETE /service-crews/{serviceCrewId} - Service crew CRUD

Material Takeoff (MTO)¶

GET/POST /mto - Get/create MTO data
PUT/DELETE /mto/{mtoId} - MTO CRUD
POST /mto/import/async - Async Excel import (returns task ID)
GET /mto/import/status/{taskId} - Poll import progress
POST /mto/export - Export MTO to Excel

Estimation Items¶

GET/POST /estimation-items - Unified estimation line items
PUT/DELETE /estimation-items/{itemId} - Item CRUD
Supports both MTO-sourced and manually uploaded items

Estimation Master Upload¶

POST /estimation-master-upload - Upload master estimation files
Async processing via Service Bus

Estimation Comparison¶

GET /estimation-comparison - Compare estimations across services/versions

WBS (Work Breakdown Structure)¶

GET/POST /wbs - List/create WBS definitions
GET/PUT/DELETE /wbs/{wbsId} - WBS CRUD
Version management and hierarchical structure editing

COA KPIs¶

GET/POST /coa-kpis - Commodity codes and KPI definitions
GET/PUT/DELETE /coa-kpis/{kpiId} - KPI CRUD

Scheduling¶

GET/POST /schedule - Legacy schedule activities (P6 import)
GET/POST /projects/{projectId}/schedules - Multi-schedule management
GET/POST /projects/{projectId}/workflows - Scheduling workflow CRUD
GET/POST /projects/{projectId}/templates - Activity mapping templates

S-Curve¶

GET /scurve - S-Curve data (planned, actual, remaining)

Project Waterfall¶

GET /project-waterfall - Waterfall cost breakdown data

Equipment Tags¶

GET/POST /equipment-tags - Project-level equipment tag management

Subcontractors¶

GET/POST /subcontractors - Subcontractor cost items

Packages¶

GET/POST /packages - Project work packages
GET/PUT/DELETE /packages/{packageId} - Package CRUD

Systems and Subsystems¶

GET/POST /systems, /subsystems - Organizational groupings
GET/PUT/DELETE /systems/{systemId}, /subsystems/{subsystemId} - CRUD

Custom Columns¶

GET/POST /custom-columns - Column definitions per project
GET/PUT/DELETE /custom-columns/{columnId} - Column CRUD

Labor Settings¶

GET/PUT /labor-settings - Overtime rates, working days, standard hours configuration

API Keys¶

GET/POST /api-keys - API key management
DELETE /api-keys/{keyId} - Revoke API key

Settings¶

GET/PUT /settings/dropdown-options - Configurable dropdown values
GET/PUT /demo-data-config - Demo data generation configuration

File Uploads¶

POST /file-uploads - File upload tracking
GET /file-uploads/{uploadId} - Upload status

Auth¶

GET /auth/me - Current authenticated user info

Health Check¶

GET /health - API health status and database connectivity

Setup Instructions¶

Prerequisites¶

Node.js: 20.19.0 or higher
Python: 3.12 or higher
uv: Python package manager (recommended) or pip
Azure Cosmos DB: Account with connection string (or emulator for local dev)

Environment Configuration¶

Frontend Environment Variables¶

Create /frontend/.env.local (optional, defaults work for local dev):

VITE_API_URL=http://localhost:8000/api/v1
VITE_ENVIRONMENT=development
VITE_AUTH_ENABLED=false          # Set to 'true' to enable Entra ID auth
VITE_AZURE_CLIENT_ID=your-client-id
VITE_AZURE_TENANT_ID=your-tenant-id

Backend Environment Variables¶

Create /backend/.env (required):

# Cosmos DB Configuration
COSMOS_ENDPOINT=https://your-account.documents.azure.com:443/
COSMOS_KEY=your-cosmos-key-here
DATABASE_NAME=lco-construction

# Azure Auth (set to false for local dev without auth)
AZURE_AUTH_ENABLED=false
AZURE_CLIENT_ID=your-client-id
AZURE_TENANT_ID=your-tenant-id

# Azure Service Bus (for async imports)
AZURE_SERVICE_BUS_CONNECTION_STRING=Endpoint=sb://your-namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=YOUR_KEY
AZURE_SERVICE_BUS_QUEUE_NAME=import-queue

# Azure Blob Storage (for file storage)
AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=your-storage-account;AccountKey=YOUR_KEY;EndpointSuffix=core.windows.net
IMPORTS_BLOB_CONTAINER=imports
SCHEDULE_BLOB_CONTAINER=schedule-data

# Observability (optional)
APPLICATIONINSIGHTS_CONNECTION_STRING=your-connection-string

# API Configuration
API_V1_STR=/api/v1
DEBUG=True

# CORS (add production URLs as needed)
BACKEND_CORS_ORIGINS=["http://localhost:3000","http://localhost:5173"]

See /backend/.env.example for a complete template.

Azure Function Import Processor Configuration¶

Create /backend/functions/import-processor/local.settings.json (for local testing):

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "python",
    "ServiceBusConnection": "your-service-bus-connection-string",
    "AZURE_STORAGE_CONNECTION_STRING": "your-storage-connection-string",
    "IMPORTS_BLOB_CONTAINER": "imports",
    "AZURE_SERVICE_BUS_CONNECTION_STRING": "your-service-bus-connection-string",
    "AZURE_SERVICE_BUS_QUEUE_NAME": "import-queue",
    "COSMOS_ENDPOINT": "your-cosmos-endpoint",
    "COSMOS_KEY": "your-cosmos-key",
    "DATABASE_NAME": "lco-construction",
    "BATCH_SIZE": "100",
    "BATCH_RETRY_ATTEMPTS": "3"
  }
}

See /backend/functions/import-processor/local.settings.json.example for a template.

Installation¶

All commands are centralized in the justfile. Install just then:

just install          # Install frontend + backend dependencies
just install-frontend # Frontend only
just install-backend  # Backend only

For backend development with code quality tools:

cd backend
uv pip install -r requirements.txt
uv pip install -r requirements-dev.txt

Running the Application¶

Development Mode¶

just dev              # Start frontend + backend in parallel
just dev-frontend     # Frontend only (http://localhost:5173)
just dev-backend      # Backend only (http://localhost:8000)
just dev-worker       # Import processor worker

The Vite dev server proxies /api/* requests to http://localhost:8000 automatically.

Accessing the Application¶

Frontend: http://localhost:5173
Backend API: http://localhost:8000
API Documentation: http://localhost:8000/api/docs (Swagger UI with OAuth)
API ReDoc: http://localhost:8000/api/redoc (alternative docs)
API OpenAPI Spec: http://localhost:8000/api/openapi.json

Development Workflow¶

All commands below use just. Run just --list for the full list.

Quality Checks¶

just quality              # All quality checks (frontend + backend)
just quality-frontend     # ESLint + TypeScript type check
just quality-backend      # Ruff lint + format check + mypy
just check                # Alias for just quality

Frontend¶

just lint-frontend        # ESLint
just typecheck-frontend   # tsc --noEmit
just test-frontend        # Vitest (single run)
just test-frontend-cov    # Vitest with coverage
just test-frontend-ui     # Vitest interactive UI
just build                # Production build -> frontend/dist
just build-analyze        # Build with bundle analyzer

Backend¶

just lint-backend         # Ruff check
just lint-fix-backend     # Ruff check --fix
just fmt-backend          # Ruff format
just typecheck-backend    # mypy app/
just test-backend         # pytest (all)
just test-backend-unit    # pytest (unit only, excludes slow/integration)
just test-backend-bench   # pytest benchmarks

Full CI Gate¶

just ci                   # quality + test + build

Adding New Dependencies¶

Frontend:

cd frontend && npm install <package-name>

Backend:

cd backend
uv pip install <package-name>
# Update requirements.txt accordingly

Code Quality and CI/CD¶

GitHub Actions Workflows¶

Workflow	Trigger	Purpose
`ci-frontend-lint.yml`	Push/PR to main/dev	ESLint + TypeScript type checking
`ci-backend-quality.yml`	Push/PR to main/dev	Ruff linter + formatter + mypy + pytest
`bot-claude-pr-review.yml`	Pull requests	AI-powered code review
`bot-claude-on-mention.yml`	Pull requests	Claude Code integration
`ci-performance.yml`	Push/PR	Performance benchmarks
`cron-test-gap-analyzer.yml`	On demand	Identifies missing test coverage
`bot-auto-changelog.yml`	Release events	Automatic changelog generation
`cron-weekly-release-pr.yml`	Scheduled (weekly)	Automated release PR creation
`cd-dev.yml` / `cd-uat.yml` / `cd-prod.yml`	Push to dev/uat/main	Composite deployment pipelines (build + deploy frontend + API)
`cd-sandbox-uat-from-main.yml`	Push to main	Sandbox UAT backend + worker deployment to Container Apps

Code Standards¶

Frontend: - ESLint rules: React hooks, React refresh, TypeScript recommended - No unused variables - Proper TypeScript typing (no implicit any) - Component names in PascalCase - File organization: components in /components, pages in /pages - State management: Zustand for global state, local state for UI-only concerns

Backend: - Ruff enforces: PEP 8, pyflakes, isort, pep8-naming, pyupgrade, bugbear, comprehensions, simplify - Line length: 100 characters - Type hints required on public functions (mypy) - Async/await for all database operations - Repository pattern for data access - Pydantic schemas for all API inputs/outputs - camelCase JSON serialization for frontend contract

Common Development Tasks¶

Adding a New Page¶

Create component in /frontend/src/pages/NewPage.tsx

Add route in /frontend/src/App.tsx:

<Route path="/new-page" element={<NewPage />} />

Add navigation link in /frontend/src/components/AppSidebar.tsx

Adding a New API Endpoint¶

Define Pydantic schemas in /backend/app/schemas/
Create/update repository in /backend/app/repositories/
Add router function in /backend/app/api/v1/routers/
Include router in /backend/app/main.py if new

Adding a New Database Container¶

Update /backend/app/core/config.py with container name constant
Add container config in /backend/app/db/cosmos.py initialize() method
Create Pydantic schema in /backend/app/schemas/
Create repository class in /backend/app/repositories/

Creating a shadcn/ui Component¶

cd frontend
npx shadcn@latest add <component-name>

This adds the component to /frontend/src/components/ui/.

Troubleshooting¶

Backend won't start¶

Issue: ModuleNotFoundError or dependency errors

Solution:

cd backend
rm -rf .venv
uv venv
uv pip install -r requirements.txt

Issue: Failed to initialize database

Solution: Check .env file has correct COSMOS_ENDPOINT and COSMOS_KEY.

Frontend build errors¶

Issue: TypeScript compilation errors

Solution:

cd frontend
rm -rf node_modules package-lock.json
npm install
npx tsc -b --noEmit  # Check for type errors

API calls fail with CORS errors¶

Issue: Frontend can't reach backend

Solution: Ensure backend is running on port 8000 and Vite proxy is configured in vite.config.ts.

Tests fail¶

Backend Tests:

cd backend && pytest -v  # See verbose output

Check that Cosmos DB connection is available (tests may require a real DB or mocking).

Deployment¶

The application consists of three separately deployed components:

1. Frontend (Azure Static Web Apps)¶

Automated via GitHub Actions on push to main/dev: - Workflows: .github/workflows/azure-static-web-apps-*.yml - Builds /frontend -> deploys to Azure Static Web Apps - Configuration: /staticwebapp.config.json - Production and UAT environments

2. Backend API (Azure Container Apps)¶

Automated via GitHub Actions on push to main/dev: - Workflows: .github/workflows/deploy-lco-api-*-container-app.yml - Runtime: Gunicorn with Uvicorn workers - Entry point: /backend/app/main.py (FastAPI application) - Startup command: gunicorn --bind=0.0.0.0 --timeout 600 --workers 4 --worker-class uvicorn.workers.UvicornWorker app.main:app - Dev and UAT environments

See /backend/DEPLOYMENT_GUIDE.md for detailed instructions.

3. Import Processor (Azure Function - `lco-dma-import-processor`)¶

Manual deployment:

cd backend/functions/import-processor
./deploy.sh lco-dma-import-processor

Type: Azure Function App (Flex Consumption plan)
Trigger: Service Bus queue (import-queue)
Entry point: /backend/functions/import-processor/function_app.py
Purpose: Processes large MTO Excel imports asynchronously
Concurrency: Single message processing (maxConcurrentCalls=1)

See /backend/AZURE_FUNCTIONS_DEPLOY.md for detailed instructions.

Azure Resources Required¶

Frontend: Azure Static Web Apps instance (production + UAT)
Backend API: Azure Container Apps (dev + UAT)
Import Processor: Azure Function App with Python 3.12 (Flex Consumption)
Database: Azure Cosmos DB with 30 containers
Message Queue: Azure Service Bus namespace with queues (import-queue, estimation-master-copy)
Blob Storage: Azure Storage Account with containers (imports, schedule-data)
Observability: Azure Application Insights

Documentation¶

Map of all docs & context: CONTEXT_MAP.md — audience-tagged inventory of every context surface (docs/, wiki/, jira/, .claude/*, .tdd/, claude-mem) with how each is updated and how to read it.

Core Documentation¶

Knowledge Base Index: docs/KNOWLEDGE_BASE.md
Architecture: docs/ARCHITECTURE.md
API Reference: docs/API_REFERENCE.md
Quick Start: docs/QUICK_START.md

Frontend¶

Frontend Architecture: docs/frontend/ARCHITECTURE.md
Component Patterns: docs/frontend/COMPONENT_PATTERNS.md
UI/UX Styles: docs/frontend/STYLES.md

Backend¶

Backend Architecture: docs/backend/ARCHITECTURE.md
MTO Import/Export Guide: docs/backend/MTO_IMPORT_EXPORT_GUIDE.md
Import Processing Architecture: docs/backend/IMPORT_PROCESSING_ARCHITECTURE.md
Deployment: docs/backend/README.md

Authentication¶

Auth Implementation: docs/auth/AUTH_IMPLEMENTATION.md

Database¶

Database Index: docs/database/INDEX.md

Feature Documentation¶

COA KPIs: docs/features/COA_KPIS.md
Demo Data System: docs/features/DEMO_DATA_SYSTEM.md
Dropdown Options: docs/features/DROPDOWN_OPTIONS.md
Estimation Overview and Comparison: docs/features/ESTIMATION_OVERVIEW_COMPARISON.md
MTO Enhancement Hooks: docs/features/MTO_ENHANCEMENT_HOOKS.md
Schedule Activities Module: docs/features/SCHEDULE_ACTIVITIES_MODULE.md
Schedule Module: docs/features/SCHEDULE_MODULE.md
S-Curve and Scheduling: docs/features/SCURVE_SCHEDULING.md

Design Resources¶

Figma Design: LCO Data Management App
Figma shadcn UI Kit: LCO shadcn-ui kit

Support¶

For questions or issues, contact the development team or refer to the detailed documentation in the /docs directory.

LCO DMA - Data Management Application¶

Project Overview¶

Architecture¶

System Design¶

Key Architectural Patterns¶

Tech Stack¶

Frontend¶

Backend¶

Code Quality and Testing¶

Project Structure¶

Data Model¶

Cosmos DB Containers¶

Key Relationships¶

Authentication¶

Microsoft Entra ID (Primary)¶

API Keys (Alternate)¶

Auth Configuration¶

API Structure¶

Base URL¶

Endpoints Overview¶

Projects and Clients¶

Services¶

Crews, Trades, and Members¶

Equipment¶

Material¶

Service Crews¶

Material Takeoff (MTO)¶

Estimation Items¶

Estimation Master Upload¶

Estimation Comparison¶

WBS (Work Breakdown Structure)¶

COA KPIs¶

Scheduling¶

S-Curve¶

Project Waterfall¶

Equipment Tags¶

Subcontractors¶

Packages¶

Systems and Subsystems¶

Custom Columns¶

Labor Settings¶

API Keys¶

Settings¶

File Uploads¶

Auth¶

Health Check¶

Setup Instructions¶

Prerequisites¶

Environment Configuration¶

Frontend Environment Variables¶

Backend Environment Variables¶

Azure Function Import Processor Configuration¶

Installation¶

Running the Application¶

Development Mode¶

Accessing the Application¶

Development Workflow¶

Quality Checks¶

Frontend¶

Backend¶

Full CI Gate¶

Adding New Dependencies¶

Code Quality and CI/CD¶

GitHub Actions Workflows¶

Code Standards¶

Common Development Tasks¶

Adding a New Page¶

Adding a New API Endpoint¶

Adding a New Database Container¶

Creating a shadcn/ui Component¶

Troubleshooting¶

Backend won't start¶

Frontend build errors¶

API calls fail with CORS errors¶

Tests fail¶

Deployment¶

1. Frontend (Azure Static Web Apps)¶

2. Backend API (Azure Container Apps)¶

3. Import Processor (Azure Function - lco-dma-import-processor)¶

Azure Resources Required¶

3. Import Processor (Azure Function - `lco-dma-import-processor`)¶