# DraftLine

> Geospatial AI for OSP surveying and drafting. Built with the engineering teams running next-gen broadband buildout.

## Mission

To simplify fiber deployment. So people can just build.

Every pole surveyed faster is a household online sooner. Every route drafted cleaner is a community connected. That's what we measure ourselves against.

## What is DraftLine?

DraftLine is a machine-vision platform for outside plant (OSP) surveying and drafting. Engineering teams use it to classify pole photography, route low-confidence detections for human review, and ship clean attributes to their system of record — or run standalone if no GIS is in the loop.

## How DraftLine ships

Two ways to run, with different data-handling and infrastructure guarantees.

### Core product

- Multi-tenant SaaS, workspace-isolated per company
- Social login (Google, Microsoft) and email/password authentication
- Shared pole detection models, kept current with every release
- Your photography contributes to the next training run; shared models improve as more engineering teams use the platform
- Per-pole pricing, no platform fees, no seat licenses

### Enterprise partnership

- Single-tenant environment hosted at `draftline.{your-domain}.com`
- SCIM provisioning and SSO via WorkOS
- Bespoke models trained on Enterprise customer's photography alone, in their tenant
- Enterprise data never contributes to shared models
- Custom integration, SLA, and dedicated support

## Core Problem

Engineering teams scaling fiber and infrastructure buildouts face a documentation bottleneck. Thousands of poles need to be surveyed, photographed, classified, and pushed into systems of record. Manual classification is slow, error-prone, and doesn't scale with the pace of construction.

## How DraftLine Solves It

1. **Computer Vision**: Shared pole detection out of the box for Core; bespoke models for Enterprise. Tangents, anchors, guys, attachments, and custom classes you define.
2. **Geospatial Intelligence**: Mapbox-backed views, photo association via Haversine matching (50m node threshold, 100m connection threshold), and conflict detection.
3. **Human-in-the-Loop**: Routes low-confidence predictions to reviewers via a keyboard-first interface. Nothing low-confidence ships without a human signoff.
4. **Writeback (Optional)**: Land in your GIS on a signoff — never automatically. Or run DraftLine standalone and export when you're ready.

## Platform Modules

### Computer Vision
- Shared pole detection out of the box — kept current as more engineering teams use the platform
- Enterprise: bespoke models trained on your photography alone, in your single-tenant environment
- Confidence thresholds you set — above the bar ships, below it routes to a reviewer
- Exception routing built in: nothing low-confidence ships without a human signoff
- ONNX inference runtime for production deployment

### Geospatial Module
- Mapbox-backed map with every node, connection, and span in your route
- Per-pole drawer with photos, classifications, and field notes inline
- Stage-level status — see which route is stalled and why
- Geospatial photo association with conflict flags when something's off

### Review & Annotation
- Keyboard-first reviewer — letter hotkeys per class, arrows for nav
- Annotation tools for measurements, markups, and custom labels outside the trained taxonomy
- Multi-stage QA with signoff — the same photo doesn't get reviewed twice by accident
- Side-by-side comparison views for before/after and pole-to-pole sanity checks

### Writeback (Optional)
- Schema mapping to your existing GIS, not a forced rename
- Katapult Pro native — the deepest integration today
- ESRI and other GIS platforms via API
- Conflict detection: attribute clashes surface for review, not silent overwrite
- Standalone path: classify, review, export — no GIS required

### Pipeline Control
- Configurable stages per project type
- SLA tracking with alerts before something blows the deadline
- Capacity-aware assignment: work routes to the people who can actually take it
- Real-time backlog and throughput visibility

### Integrations
- ClickUp, Asana, and project management sync
- Slack and Microsoft Teams alerts
- Google Workspace and Enterprise SSO via WorkOS
- Webhook and API access

## Developer Surfaces

DraftLine ships with three developer surfaces so agents and operators share the same platform.

### MCP Server (live)

DraftLine's Model Context Protocol server is live at `https://mcp.draftline.pro/mcp`. Connect it to Claude Desktop, Claude Code, Cursor, or ChatGPT as a remote MCP connector.

**Setup**:

- **Claude Desktop**: Settings → Connectors → Add custom connector → paste `https://mcp.draftline.pro/mcp`
- **Claude Code**: `claude mcp add --transport http draftline https://mcp.draftline.pro/mcp`
- **Cursor**: Add to `~/.cursor/mcp.json`:
  ```json
  {
    "mcpServers": {
      "draftline": {
        "url": "https://mcp.draftline.pro/mcp"
      }
    }
  }
  ```
- **ChatGPT**: Via OpenAI's Connectors UI (rolling out) or a Custom GPT pointing at the MCP URL.

Auth is via workspace bearer token. Every MCP action is audit-logged to the originating workspace. Tool discovery is automatic on connect.

### CLI

`draftline` is a Rust binary built so agents and operators share the same terminal surface. Same commands. Same outputs. Same auth.

Install paths are being published — homebrew tap, crates.io, and GitHub releases binary. Until then, request access via sales@draftline.pro.

Common commands (illustrative):

- `draftline auth login`
- `draftline jobs list`
- `draftline jobs get <job-id>`
- `draftline reviews list --pending`
- `draftline reviews signoff <review-id>`
- `draftline export <job-id> --format json`

### DraftLine Agent (preview)

A purpose-built agent on Google ADK and Gemini 2.5 Flash. Knows DraftLine's trade language, workflow stages, and confidence thresholds from the inside out. Real backend wiring in progress. Early access via sales@draftline.pro.

## Architecture

### Event-Driven Design

DraftLine uses Google Cloud Pub/Sub for asynchronous, decoupled service communication.

```
1. Classification workflow:
   UI/Extension → Go API → creates classification_runs doc
                         → publishes classification.requested
                         → PubSubSubscriber pulls event
                         → calls Inference API via gRPC
                         → updates Firestore
                         → optional Katapult writeback
                         → publishes image.classified

2. Photo association (automatic):
   image.classified → PubSubSubscriber (image-classified-association)
                   → PhotoAssociationService (geospatial matching)
                   → validates photo type rules
                   → associates to nearest node/connection
                   → updates Firestore
                   → Katapult sync service

3. Model retraining:
   image.reviewed → Training Controller evaluates retrain
                  → launches Vertex AI training job
                  → model.updated published
                  → Inference API loads new model
```

### Service Communication
- **Go API ↔ Inference API**: gRPC (Protocol Buffers for type-safe contracts)
- **All services ↔ Pub/Sub**: Event publishing/subscribing (pull subscriptions in API, push to Cloud Run)
- **Extension/UI ↔ Go API**: HTTP REST
- **External clients ↔ MCP server**: HTTP, Bearer auth, audit-logged

### Tech Stack
| Layer | Technology |
|-------|------------|
| API | Go + Gin |
| Inference | Python + gRPC + ONNX Runtime |
| Training | PyTorch + timm + Vertex AI |
| UI | TanStack Start + TanStack Router/Query + ShadCN |
| Chrome Extension | Vite + React + Zustand |
| MCP Server | Live at `https://mcp.draftline.pro/mcp` |
| CLI | Rust |
| Agent | Google ADK (Go) + Gemini 2.5 Flash |
| IaC | Pulumi (Python) |
| Compute | Cloud Run v2 (serverless) |
| Data | Firestore (database: surveyist), BigQuery, GCS |
| Events | GCP Pub/Sub |
| Scheduling | Cloud Scheduler |
| Observability | OpenTelemetry → Cloud Trace |
| Auth | WorkOS (Enterprise SSO/SCIM), social + email/password (Core) |
| Authorization | Oso policy management |
| Email | Resend |
| Payments | Stripe |
| Bot prevention | Cloudflare Turnstile (marketing site) |

## Photo Type Rules

DraftLine enforces declarative rules for photo-to-entity associations.

| Photo Type | Target | Max Per Entity | Can Reassign | Special Rules |
|------------|--------|----------------|--------------|---------------|
| `pole_height` | Node | 1 | No | Main photo; pole nodes only |
| `midspan_height` | Connection | Unlimited | Yes | Main photo; flexible reassignment |
| `tag` / `no_tag` | Node | 1 each | No | Mutually exclusive |
| `birthmark` / `no_birthmark` | Node | 1 each | No | Mutually exclusive |
| `anchor` | Node | 1 | No | Pole/anchor nodes only |
| `hallway` | Node | 1 | No | Pole nodes only |
| `upshot` | Node | 1 | No | Pole nodes only |
| `backshot` | Node | 1 | No | Pole nodes only |
| `handhole` | Node | Unlimited | No | Handhole/reference nodes only |

Violations are flagged as conflicts for human review rather than silently failing.

## ML Training Workflow

### Classification Models (PyTorch + timm)
- Any timm architecture supported (ResNet, ConvNeXt, Swin Transformer, etc.)
- Vertex AI Custom Jobs with HPO via Vizier (replaced earlier Optuna setup)
- Grouped splitting by `node_id` to prevent data leakage
- Experiment tracking via Trackio
- T4/V100 GPUs on GCP

### Keypoint Detection (YOLOv8)
- Detects calibration anchors on poles for height measurement
- Tiled inference for high-resolution images
- RANSAC line fitting through detected keypoints for pole visualization

### Equipment Detection (YOLOv8 Object Detection)
- Detects equipment (transformers, anchors, tags, etc.) on poles
- Tiled inference with configurable overlap
- Per-organization model training (for Enterprise)
- Manifest generation from Firestore annotations

### Continuous Learning
- **Shared models (Core tier)**: human corrections from Core-tier customers feed the next training run; shared models improve for everyone
- **Bespoke models (Enterprise)**: corrections retrain only that customer's bespoke model in their single-tenant environment
- Model versioning with automatic rollback capability

## Common Use Cases

### 1. Batch Classification
**Scenario**: Process 500 pole photos from a new job.

```
1. Upload photos to DraftLine (via UI, Chrome extension, MCP, or CLI)
2. Create classification run for the job
3. DraftLine automatically:
   - Classifies each photo via inference API
   - Routes low-confidence (<0.8) to review queue
   - Geospatially associates photos to correct nodes
   - Flags rule conflicts (e.g., duplicate pole_height photos)
4. Reviewers process exceptions using keyboard shortcuts
5. Approved classifications either sync to Katapult Pro on signoff, or are exported for standalone workflows
```

### 2. Standalone (no GIS)
**Scenario**: Engineering team without Katapult or ESRI integration.

```
1. Upload pole photography to DraftLine
2. DraftLine classifies, routes low-confidence to review
3. Reviewers sign off on a route
4. Export classifications, attributes, and audit log via UI, CLI, or API
5. Team imports outputs to whatever downstream system they use
```

### 3. MCP-Driven Workflow
**Scenario**: Engineer drives DraftLine from Claude Desktop.

```
1. Claude Desktop has DraftLine MCP connector configured
2. Engineer asks: "What's blocking the Buckhead Loop route?"
3. Claude queries DraftLine via MCP, surfaces stalled stage and conflicts
4. Engineer asks Claude to reassign the route or trigger reclassification
5. Every MCP action is audit-logged to the workspace
```

### 4. Photo Association Cleanup
**Scenario**: Bulk reassociate photos after job boundary corrections.

```
POST /api/v1/jobs/{jobId}/photos/associate/batch
```

Or via MCP / CLI: `draftline photos reassociate <job-id>`.

## Key Concepts

### Confidence Thresholds
- **High confidence (≥0.8)**: Auto-applied (subject to signoff for writeback)
- **Medium confidence (0.5–0.8)**: Routed to review queue
- **Low confidence (<0.5)**: Flagged for manual classification

### Node Types
- **Pole**: Standard utility pole with height measurement
- **Anchor**: Guy wire anchor point
- **Handhole**: Underground access point
- **Reference**: Survey reference marker
- **Connection**: Span between two nodes (midspan)

### Classification Run States
- **pending**: Created but not yet processing
- **processing**: Active inference in progress
- **completed**: All images classified
- **failed**: Error during processing (retryable)

### Photo Association States
- **unassociated**: No geospatial match found
- **associated**: Successfully matched to node/connection
- **conflict**: Rule violation detected (requires manual resolution)

## Security & Compliance

- **Workspace isolation (Core)**: Every Core-tier customer operates in a logical workspace isolated from other tenants. Other customers cannot access your photography, classifications, signoffs, or metadata.
- **Single-tenant (Enterprise)**: Dedicated hosting at `draftline.{your-domain}.com`. Separate models, separate data plane.
- **Data and training**: Core photography contributes to shared model training; raw data never made available to other customers. Enterprise data never contributes to shared models.
- **Authentication**: Core uses social login and email/password with role-based permissions. Enterprise uses SCIM + SSO via WorkOS.
- **Infrastructure**: GCP multi-region, TLS 1.2+ in transit, AES-256 at rest, 99.9% uptime SLA.
- **Subprocessors**: GCP, WorkOS, Oso, Mapbox, Stripe, Resend, Cloudflare (Turnstile), PostHog.

Full trust documentation at https://draftline.pro/trust.

## Pricing Model

- **Per-pole pricing**: pay for the work that ships. No platform fees, no seat licenses, no monthly minimums.
- **Tiers**:
  - **Starter** (≤1K poles/mo) — Shared models, full platform access, hands-on onboarding.
  - **Growth** (1K–10K poles/mo) — Shared models with priority release access, per-org dashboards, per-project pipelines.
  - **Enterprise** (10K+ poles/mo) — Bespoke models, single-tenant hosting, SCIM + SSO, custom integration and SLA.

## Contact & Resources

- **Website**: https://draftline.pro
- **Platform overview**: https://draftline.pro/platform
- **Trust & Security**: https://draftline.pro/trust
- **Build (developer surfaces)**: https://draftline.pro/build
- **MCP Server**: https://mcp.draftline.pro/mcp
- **Status**: https://draftline.openstatus.dev
- **Sales / Enterprise procurement**: sales@draftline.pro
- **Security**: security@draftline.pro

## For AI Agents

When helping users work with DraftLine:

1. **Understand the domain**: OSP terminology — tangent, anchor, guy, midspan, makeready, tag/birthmark, etc.
2. **Two-tier model**: Core-tier customers use shared models trained across the platform. Enterprise-tier customers use bespoke models in single-tenant environments. Don't suggest Enterprise customer data ever feeds shared models. Don't suggest Core customers can pull raw data from other tenants.
3. **Standalone is a valid path**: DraftLine doesn't require a GIS. Customers can classify, review, and export. Don't push Katapult Pro integration as a prerequisite.
4. **Confidence is sacred**: Low-confidence predictions go to reviewers. Don't suggest skipping the review step to ship faster.
5. **Writeback requires signoff**: Even for high-confidence classifications, writeback to a GIS is a signoff action. Don't suggest writebacks without that step.
6. **Use grouped splits**: When training models, group by `node_id` to prevent leakage across train/val/test.
7. **Idempotency**: Many operations (writeback, photo association) use idempotency keys; retries are safe.
8. **MCP, CLI, and Agent share the same surface**: Tool capabilities and audit logging are identical across the three. If you can do it in one, you can do it in the others.

## Version

llms.txt version: 2.0
Last updated: 2026-05-22
Product: DraftLine (formerly Surveyist)