---
title: DevisionX Progress Tracking
emoji: 🏗️
colorFrom: blue
colorTo: gray
sdk: docker
app_port: 8000
pinned: false
---

<!-- The block above configures Hugging Face Spaces (Docker SDK). It is ignored by
     GitHub except as a small metadata table. See DEPLOY.md for deploy steps. -->

# DevisionX — Site Progress Tracking (Physical → CAD)

An on-premise tool that tracks **construction progress** by comparing site photos
against approved drawings using the Gemini API.

**Model:** a **project** contains **drawings**. A drawing is the tracked unit —
you upload it once and the AI derives a checklist of expected **build elements**
(editable) plus you set planned **start/finish** dates. Over time you add dated
**captures** (site photos); each capture scores every element **built / in progress
/ not built / not visible**, producing a **completion %** that's charted over time
and compared against the schedule. Each capture also surfaces deviation **findings**
(missing / extra / misplaced / mismatch) with severity, confidence, and an editable
status for QA tracking.

> **Honest by design.** Completion is reported as **built X of Y visible**, never an
> invented percentage; elements the photo can't show are marked *not visible* and
> excluded from the ratio. The model is told never to fabricate dimensions. It's an
> assistive triage/tracking tool — a human confirms every state and finding.

Everything runs locally: **FastAPI** + **SQLite** + local file storage
(`backend/live_data/`, gitignored) and a **React + Vite + Tailwind** frontend. Files
only leave the machine for the Gemini API call.

## Setup

1. Add your Gemini API key to `demo1-physical-cad/backend/.env`:

   ```ini
   GEMINI_API_KEY=your-paid-key-here
   GEMINI_MODEL_COMPARE=gemini-2.5-pro     # drawing reading + element scoring (quality)
   GEMINI_MODEL=gemini-2.5-flash           # follow-up text Q&A (speed)
   ```

2. Run it (two terminals):

   ```bash
   cd demo1-physical-cad
   bash run-backend.sh     # FastAPI  -> http://127.0.0.1:8000
   bash run-frontend.sh    # React UI -> http://127.0.0.1:5173
   ```

## Workflow

1. **Create a project.**
2. **Add a drawing** (PNG/JPG/PDF) with planned start/finish → AI derives the element
   checklist (review/edit it on the drawing page).
3. **Add captures** over time (dated site photos) → each scores element completion and
   logs deviation findings.
4. Watch the **progress timeline** and **schedule** (on track / behind) on the drawing
   page; open any capture for side-by-side images, element states, findings (with
   status toggles), follow-up chat, and **Print/Export PDF**.

## How it works

- `backend/live.py` — all `/api/*` routes (projects, drawings, elements, captures,
  findings, capture `/ask`). PDFs are rasterized (PyMuPDF), images resized (Pillow),
  and sent to Gemini with a structured-JSON response schema. Two Gemini calls:
  element **derivation** (drawing only) and capture **analysis** (drawing + photo +
  the element list).
- `frontend/src/` — `react-router-dom` app: projects → project (drawings) → drawing
  (schedule + checklist + timeline) → capture detail.

## Notes & limits

- Needs the FastAPI backend + a valid key; no offline mode.
- Each capture takes ~20–40 s and uses paid Gemini. Drawing derivation ~15–25 s.
- Drawings: PNG/JPG/PDF (PDF first page only). **No native DWG/DXF** — export to PDF/PNG.
- Element scoring from a single, unaligned photo is assistive, not survey-grade;
  confidence levels + the human-editable states are the backstop.

---

DevisionX · Confidential