Documentation

Platform Overview

OpenConstructionERP is a complete construction cost estimation and project management platform that runs entirely on your machine. It replaces expensive enterprise tools like iTWO, CostX, Sage Estimating, and Bluebeam with an open, self-hosted alternative. The platform covers the entire estimation workflow — from initial feasibility studies and quantity takeoff to detailed BOQ preparation, tendering, and bid comparison. All your data stays on your server. No cloud dependency, no subscriptions, no per-seat fees.

Dashboard with project KPIs, Getting Started steps, recent projects, and system status panel

First Steps After Installation

After installing OpenConstructionERP, follow these steps to set up your first project and create your first cost estimate. The entire process takes about 10 minutes.

Step 1: Log In

Open your browser and navigate to http://localhost:5173 (local development) or http://localhost:8080 (Docker). You will see the login page with a "Demo Access" panel. Click on Admin to log in instantly with the demo account, or enter your own credentials if you registered a new account.

Step 2: Complete Onboarding

On first login, the onboarding wizard guides you through initial setup:

1. Choose your language — Select from 21 available languages. The entire UI switches immediately.
2. Select your region — This determines which cost database and classification standard are used by default (e.g., DIN 276 for Germany, NRM for UK, MasterFormat for US).
3. Configure AI (optional) — If you want AI estimation features, enter an API key from any supported provider (Anthropic, OpenAI, Gemini, etc.). You can skip this and add it later in Settings.
4. Load cost database — The system offers to download and import the CWICR cost database for your selected region (55,719 items). This takes about 30 seconds.

Step 3: Create Your First Project

Click New Project on the Dashboard or navigate to Projects. Fill in:

• Project name — e.g., "Residential Building Berlin-Mitte"
• Description — Brief scope description
• Region — Determines currency and default classification standard
• Classification standard — DIN 276, NRM 1/2, MasterFormat, or custom

After creating the project, you are redirected to the project detail page where you can start adding BOQs.

Step 4: Create Your First BOQ

From the project page, click New Estimate. Give it a name (e.g., "Cost Estimate v1") and optionally choose a template. The BOQ editor opens with an empty grid ready for your first position.

Step 5: Add Positions

In the BOQ editor, click Add Position or press Enter on an empty row. Fill in:

• Ordinal — Position number (e.g., "01.001")
• Description — What work is being done (e.g., "Reinforced concrete C30/37 for foundation slab")
• Unit — Measurement unit (m3, m2, m, kg, pcs, lsum)
• Quantity — How much (e.g., 86.4)
• Unit Rate — Price per unit (e.g., 295.00 EUR)

The Total column calculates automatically (Quantity x Unit Rate). You can also search the cost database by clicking the database icon next to any position to find and apply a rate from the 55,000+ CWICR items.

Installation Guide

OpenConstructionERP is designed to be easy to install regardless of your technical background. Choose the method that matches your setup — all options take less than 5 minutes. The application uses SQLite by default, so you do not need to install or configure any database server. Everything works out of the box.

Option A: One-Line Install

# Linux / macOS
curl -sSL https://raw.githubusercontent.com/datadrivenconstruction/OpenConstructionERP/main/scripts/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/datadrivenconstruction/OpenConstructionERP/main/scripts/install.ps1 | iex

Auto-detects Docker / Python / uv and runs at http://localhost:8080

Option B: Docker

git clone https://github.com/datadrivenconstruction/OpenConstructionERP.git
cd OpenConstructionERP
make quickstart

Opens at http://localhost:8080 (~2 min first build).

Option C: Local Development

git clone https://github.com/datadrivenconstruction/OpenConstructionERP.git
cd OpenConstructionERP

# Backend (SQLite, zero config)
cd backend && pip install -r requirements.txt
uvicorn app.main:create_app --factory --reload --port 8000

# Frontend (new terminal)
cd frontend && npm install && npm run dev

Backend: http://localhost:8000 / Frontend: http://localhost:5173

Demo Accounts

5 demo projects (Berlin, London, New York, Paris, Dubai) with complete BOQs, schedules, and cost models.

BOQ Editor

The Bill of Quantities editor is where you spend most of your time. It provides a professional, spreadsheet-like interface powered by AG Grid with construction-specific features built in — hierarchical sections, resource linking, assembly recipes, and automatic markup calculations. Every change is tracked with full undo/redo support. 42 validation rules run automatically in the background, catching errors like missing quantities, zero prices, duplicate positions, and classification compliance issues before they become problems.

Bill of Quantities overview showing 11 estimates across 5 projects with stats: 424 positions, 232.6M total value

• Hierarchical structure - Sections, positions, sub-positions with drag-and-drop
• Inline editing - Click any cell to edit. Tab between fields. Undo/redo
• Resources & assemblies - Link labor, materials, equipment. Build reusable recipes
• Markups - Overhead, profit, VAT, contingency per project or regional defaults
• Validation - 42 rules check for missing quantities, zero prices, compliance
• Export - Excel, CSV, PDF report, GAEB XML (X83)

Working with Sections

Sections organize your BOQ into logical groups (e.g., "300 Structure", "400 HVAC"). To create a section:

1. Click Add Section in the toolbar
2. Enter the section name and optional DIN 276/NRM classification code
3. All positions added after a section header belong to that section
4. Each section shows its own subtotal at the bottom

You can collapse/expand sections to focus on specific trades. Drag sections to reorder the entire BOQ structure.

Linking Resources

Each BOQ position can have linked resources that break down the unit rate into components:

• Materials — Concrete, steel, bricks, insulation (from Resource Catalog)
• Labor — Worker hours by trade (formworker, electrician, plumber)
• Equipment — Crane hours, excavator, concrete pump

To add resources: expand a position row, click "Add Resource", search the catalog, set the quantity factor (e.g., 120 kg rebar per m3 concrete). The position unit rate updates automatically from the sum of its resources.

Configuring Markups

Markups are applied after the net total (sum of all positions). Common markups include:

• Overhead — Company overhead costs (typically 8-15%)
• Profit — Contractor profit margin (typically 5-12%)
• Contingency — Risk reserve for unforeseen costs (typically 5-10%)
• VAT/Tax — Value Added Tax (19% in Germany, 20% in UK, varies by country)

Click Add Markup in the toolbar. You can set regional defaults or customize per project. Markups can be percentage-based or fixed amounts, and they compound in order (overhead first, then profit on the overhead-inclusive amount, then VAT on the total).

Running Validation

Press Ctrl+Shift+V or click the shield icon in the toolbar to run validation. The system checks your BOQ against the selected rule sets and shows results inline:

• Positions with errors get a red dot
• Positions with warnings get a yellow dot
• The validation score (%) appears in the toolbar
• Click any dot to see the specific issue and fix it

Importing Data

The BOQ editor supports importing from multiple sources:

• Excel/CSV — Click Import, select your file. The wizard maps your columns (description, quantity, unit, rate) to BOQ fields. Preview before committing.
• GAEB XML — Import German-standard tender files directly. Positions, sections, and rates are preserved.
• Paste from clipboard — Copy rows from Excel, click "Paste" in the toolbar. The system detects columns automatically.
• AI Smart Import — Upload any PDF, photo, or CAD file. AI extracts BOQ positions with quantities and rates.

Keyboard Shortcuts

Cost Database

Access the largest open-source construction cost database in the world. The CWICR database contains 55,000+ cost items with descriptions in up to 9 languages, organized by trade (earthworks, concrete, masonry, steel, roofing, facades, HVAC, electrical, plumbing, finishing, landscaping). Each item includes a unit of measurement, base rate for the specified region, classification codes (DIN 276, NRM, MasterFormat), and component breakdown (materials, labor, equipment) when available.

Cost Database with Germany/DACH selected showing 55,719 items with German descriptions, rates, and classification

How to Use the Cost Database

The cost database is designed for two main workflows:

Workflow A: Browse and Apply to BOQ

1. Navigate to Databases → Cost Database
2. Select your region tab (e.g., "Germany / DACH")
3. Search for a cost item by typing in the search bar (e.g., "concrete foundation")
4. Click the star icon to add frequently used items to your Favorites
5. In the BOQ editor, click the database icon next to any position to search and apply a rate

Workflow B: Import Your Own Database

1. Navigate to Databases → Cost Database → Import Database
2. Prepare an Excel or CSV file with columns: Code, Description, Unit, Rate, Currency
3. Upload the file and map columns in the import wizard
4. Preview the data before committing
5. Your imported items appear alongside CWICR data with your custom source tag

Understanding Cost Item Structure

Each cost item contains:

• Code — Unique identifier (e.g., KADX_KAME_KAKAME_KAME)
• Description — Work item name in up to 9 languages
• Unit — Unit of measurement (m2, m3, t, pcs, etc.)
• Rate — Price per unit in the regional currency
• Components — Breakdown into materials, labor, equipment (when available)
• Classification — DIN 276, NRM, MasterFormat codes for cross-referencing

Vector Search

Enable semantic search to find cost items by meaning, not just exact keyword matches. When you search for "concrete wall", the system also finds items like "reinforced partition C30/37, 24cm with formwork" — even though the exact words do not appear. This is powered by sentence-transformer embeddings that convert descriptions into numerical vectors and find the closest matches in multi-dimensional space. Two vector database backends are supported: LanceDB (embedded, runs in-process like SQLite, 384-dimensional embeddings) and Qdrant (production server with pre-built 3072-dimensional snapshots downloadable from GitHub).

CAD/BIM & PDF Takeoff

Extract quantities directly from your project drawings and models — no manual counting required. Upload Revit, IFC, AutoCAD, or MicroStation files and the system extracts every building element with volumes, areas, and lengths. For PDF drawings, open them directly in the browser and use calibrated measurement tools to take off distances, areas, and element counts. All extracted quantities can be transferred to a BOQ for pricing.

PDF Takeoff with 4-step workflow (Upload, AI Analysis, Review, Add to BOQ), project/BOQ selector, and drag-drop upload zone

CAD/BIM Takeoff: Step by Step

1. Navigate to Takeoff → CAD/BIM Takeoff
2. Drag and drop your CAD/BIM file (.rvt, .ifc, .dwg, .dgn) onto the upload area
3. Wait for the DDC converter to extract elements (30-60 seconds for typical files)
4. The system shows available columns and suggests grouping presets:
   • Standard Revit QTO — Group by Category + Type Name, sum Volume/Area/Count
   • Detailed — Add Level for per-floor breakdown
   • By Family — Group by Revit Family for procurement lists
   • Custom — Choose any combination of the 1200+ extracted columns
5. Click Apply Grouping to see the quantity table
6. Review the grouped results — filter out empty groups, delete irrelevant categories, sort by volume
7. Click Save as BOQ to transfer quantities to a Bill of Quantities for pricing

PDF Takeoff: Step by Step

1. Navigate to Takeoff → PDF Takeoff
2. Upload your PDF construction drawing
3. The system extracts text and tables from the PDF automatically
4. Click Analyze with AI to extract construction elements with quantities
5. Or switch to the Measurements tab for manual takeoff:
   • Set the drawing scale (click two known points and enter the real distance, or select a preset like 1:100)
   • Select Distance tool and click two points to measure length
   • Select Area tool and click corners of a polygon to measure area
   • Select Count tool and click on elements to count them
6. All measurements are saved and can be exported to a BOQ

QTO Grouping Presets

• Standard Revit QTO - Category + Type Name (volume, area, count)
• Detailed + Level - Per-floor breakdown
• By Family - For procurement and ordering
• Custom - Choose any columns

AI Estimation

Connect any LLM provider to generate construction cost estimates from plain text descriptions, building photos, scanned PDFs, Excel spreadsheets, or CAD/BIM models. The AI system creates complete BOQ positions with quantities and market-rate pricing. After generation, you can match each item against the CWICR cost database to replace AI-estimated rates with verified regional market prices. AI features are entirely opt-in — the platform works fully without them.

AI Estimate page with text input, location/currency/standard selectors, and 5 input modes: Text, Photo, PDF, Excel, Paste

3

AI Cost Advisor

Chat with AI about costs, materials, and pricing using your cost database as context.

AI Cost Advisor chat with suggested questions, region selector, and CWICR database integration

4D Schedule & 5D Cost Model

Plan your construction project timeline and track costs over time with integrated scheduling and financial modeling tools.

4D Schedule

The scheduling module provides a professional Gantt chart for managing your construction timeline. Create activities, set durations, define dependencies, and the system automatically calculates the critical path showing which activities must not be delayed.

• Activity types — Tasks, milestones, and summary activities with WBS codes for structured breakdown
• Dependencies — Finish-to-Start (FS), Start-to-Start (SS), Finish-to-Finish (FF), and Start-to-Finish (SF) relationships between activities
• Critical path — Automatic CPM calculation with visual highlighting. Activities on the critical path are marked with a "CP" badge
• Auto-generate from BOQ — Select a BOQ and set total project duration. The system creates one activity per section with cost-proportional durations and sequential dependencies
• Progress tracking — Update activity status (completed/in-progress/pending) and track actual vs planned dates
• Monte Carlo simulation — Run probabilistic analysis with optimistic/pessimistic ranges to get risk-adjusted completion dates with confidence levels

5D Cost Model

The cost model connects your BOQ data to the project timeline, giving you a time-phased view of construction costs with Earned Value Management metrics.

• Gantt chart with drag-and-drop, dependencies (FS/FF/SS/SF), critical path
• Auto-generate activities from BOQ sections
• Earned Value Management: SPI, CPI, EAC, VAC
• S-curve (planned vs actual), budget snapshots, cash flow
• Monte Carlo simulation for risk-adjusted scheduling

Tendering & Bid Management

Manage the complete procurement workflow from creating bid packages to comparing proposals and awarding contracts to subcontractors.

Creating a Tender Package

Navigate to Procurement, select a project, and click "Create Package". Specify the package name, scope description, submission deadline, and select which BOQ positions to include. You can create multiple packages per project (e.g., structural works, MEP, finishing).

Managing Bids

Add bids from subcontractors with company name, contact details, and quoted prices for each BOQ position. The system supports multiple bids per package for side-by-side comparison.

Bid Comparison

The price mirror shows all bids in a comparison table with unit rates and totals per position. Visual indicators highlight the lowest and highest bids. Export the comparison as CSV for stakeholder review.

Award Process

Mark the winning bid with the Award button and add justification notes. Package status tracks through: Draft, Issued, Collecting, Evaluating, Awarded, Closed.

Risk Register

Identify, assess, and manage project risks using a probability-impact matrix. Quantify risk exposure and plan mitigation strategies for each identified risk.

Risk Assessment Matrix

The matrix displays all risks on a probability (0.1-0.9) vs impact (low/medium/high/critical) grid with color coding. Each risk shows its calculated exposure score (probability multiplied by impact cost).

Managing Risks

For each risk, document: unique code (R-001), title, category (technical, financial, schedule, regulatory, environmental, safety), mitigation strategy, contingency plan, risk owner, cost impact, and schedule impact in days. Track status through: Identified, Assessed, Mitigating, Closed, or Occurred.

Change Orders

Track scope changes and their impact on project cost and schedule. Change orders provide an audit trail of all modifications made after the initial estimate.

Change Order Workflow

Create a change order with code (CO-001), title, and reason category (client request, design change, unforeseen condition, regulatory). Add line items specifying affected BOQ positions with original and new quantities/rates. The system calculates cost deltas automatically. Status moves through: Draft, Submitted, Under Review, Approved/Rejected.

Validation & Quality Checks

Validation page - select project and BOQ, run quality checks against configurable rule sets

Run automated quality checks on your BOQs to catch errors before they become problems. The validation engine applies 42 configurable rules against your estimate data.

Rule Sets

• BOQ Quality — Missing quantities, zero prices, duplicate positions, unrealistic unit rates, empty descriptions
• DIN 276 Compliance — Cost group hierarchy, required KG codes, completeness per level
• GAEB Format — Structure validation for GAEB XML export (X83)
• NRM Compliance — NRM 1/2 element structure and measurement rules
• MasterFormat — CSI division structure and code format

Understanding Results

Each validation produces a quality score (0-100%) with color-coded findings: Errors (red, must fix), Warnings (yellow, should review), Info (blue, suggestions). Click any finding to navigate directly to the affected BOQ position.

Reports & Export

Reports page with 9 export formats: BOQ (PDF/Excel), Cost Report, GAEB XML, Validation, Schedule, 5D Cost, Tendering, Change Orders, Risk Register

Generate professional documents from your project data for stakeholders, clients, and regulatory compliance.

• BOQ Report (PDF) — Complete Bill of Quantities with sections, positions, subtotals, markups, and grand total
• BOQ Export (Excel) — Full data in .xlsx with formulas, formatting, and section grouping
• Cost Report (PDF) — Summary by trade, category, or classification standard
• GAEB XML (X83) — Standard German/Austrian tender format for electronic submission
• CSV Export — Raw data for import into other tools or spreadsheets

Document Management

Document management with drag-drop upload, category filters (Drawing, Contract, Specification, Photo), tags, and file preview

Centralize all project documents. Upload drawings, contracts, specifications, and photos with automatic categorization and search.

• Upload — Drag and drop files up to 100 MB (PDF, images, Office, CAD)
• Categories — Drawings, contracts, specifications, photos, correspondence
• Tags — Custom tags for flexible filtering
• Preview — View PDFs and images directly in the browser
• Version tracking — Upload dates, file sizes, uploader identity

Analytics Dashboard

Cross-project analytics with KPI cards (Total Budget 125.6M, Variance 63.4M), project comparison table with budget/actual/variance per region

View cross-project budget performance. The dashboard aggregates financial data across all projects to identify trends, variances, and at-risk budgets.

• Project table — Sortable list: budget, actual spend, variance, percentage, status
• KPI cards — Total portfolio value, average variance, projects on/over budget
• Regional filter — Compare performance across markets (DACH, UK, US, Gulf)
• Status filter — Focus on over-budget projects for attention

Configuration

Settings page with profile management, Simple/Advanced interface mode toggle, and module configuration

API Reference

OpenConstructionERP exposes a comprehensive REST API that powers the frontend and can be used for integrations, automation, and custom workflows. Every action available in the UI — creating projects, editing BOQs, running AI estimates, searching costs — is available as an API endpoint. Interactive Swagger documentation with try-it-out buttons is available at /api/docs when running the backend.

Support & Contributing

License: AGPL-3.0. Commercial licensing: info@datadrivenconstruction.io