OpenConstructionERP Platform Overview
What it is
OpenConstructionERP is a self-hosted, open-source (AGPL-3.0) construction ERP by DataDrivenConstruction: BOQ management, CAD/BIM takeoff (RVT/IFC/DWG/DGN), 4D scheduling, 5D cost modelling, tendering, field management and 180+ modules in one platform. It runs embedded PostgreSQL (no Docker required) with a FastAPI backend and a Vite/React frontend.
Homepage: https://openconstructionerp.com · Repo: https://github.com/datadrivenconstruction/OpenConstructionERP · Docs: https://openconstructionerp.com/docs
Module map (what to use when)
| Need |
Module |
Key endpoints |
| Browse/load cost databases |
costs |
GET /api/v1/costs/base-catalog, POST /api/v1/costs/load-cwicr/{db_id}, GET /api/v1/costs/?region=...&q=... |
| Resource catalogs |
catalog |
POST /api/v1/catalog/import/{region}, GET /api/v1/catalog/... |
| Bill of quantities |
boq |
POST /api/v1/boqs, GET /api/v1/boqs/{id}, validate/import GAEB |
| BIM elements / takeoff |
bim |
upload RVT/IFC/DWG/DGN, link elements to BOQ lines |
| Schedule (4D) / cost (5D) |
scheduling |
tasks, dependencies, cost model roll-ups |
| Issues & quality |
punch_list, validation |
punch items, validation rule packs (DIN276/NRM/GAEB) |
| Site daily ops |
daily_diary, hse |
diary entries, safety observations |
| Docs / tasks / risks |
documents, tasks, risks |
file approvals, task board, risk register |
| Portfolio map |
geo_hub |
projects on a 3D globe |
| Property development |
property_dev |
lead → SPA → handover |
Quick start (dev)
cd backend && python -m uvicorn app.main:create_app --factory --reload --port 8000
cd frontend && npm run dev # http://localhost:5173
Auth: bootstrap admin (first registered user), JWT tokens, role-based permissions (viewer/editor/manager/admin). POST /auth/register, POST /auth/login.
Data contracts to respect
- CWICR work-item parquets follow the 95-column master schema (
rate_code, rate_original_name, rate_final_name, rate_unit, total_cost_per_position, classification collection/department/section/subsection/category, resource lines resource_*, flags is_material/is_machine/is_labor).
- Region ids match
^[A-Z]{2,3}_[A-Z0-9]+$ (e.g. TR_NATIONAL, ZH_CHINA, BR_NATIONAL).
- The importer is idempotent on
(code, region) — re-loading returns already_loaded.
Best practices
- Load the base first (
load-cwicr), then swap language (automatic via home_language_code), then reprice markets via the catalog path.
- Never invent prices: leave unpriced coefficient bases (VN, ID) as rate 0 and use the resource price sheet.
- Verify an import with
GET /api/v1/costs/regions/stats/ and a sampled item's rate against the parquet's total_cost_per_position.
1---2name: oce-platform-overview3description: Guide to OpenConstructionERP: architecture, modules, API surface and quick start. Use when starting any OpenConstructionERP work, onboarding a user to the platform, or deciding which module/endpoint to use.4---5
6# OpenConstructionERP Platform Overview
7
8## What it is
9
10OpenConstructionERP is a self-hosted, open-source (AGPL-3.0) construction ERP by DataDrivenConstruction: BOQ management, CAD/BIM takeoff (RVT/IFC/DWG/DGN), 4D scheduling, 5D cost modelling, tendering, field management and 180+ modules in one platform. It runs embedded PostgreSQL (no Docker required) with a FastAPI backend and a Vite/React frontend.
11
12> Homepage: https://openconstructionerp.com · Repo: https://github.com/datadrivenconstruction/OpenConstructionERP · Docs: https://openconstructionerp.com/docs
13
14## Module map (what to use when)
15
16| Need | Module | Key endpoints |
17|---|---|---|
18| Browse/load cost databases | `costs` | `GET /api/v1/costs/base-catalog`, `POST /api/v1/costs/load-cwicr/{db_id}`, `GET /api/v1/costs/?region=...&q=...` |
19| Resource catalogs | `catalog` | `POST /api/v1/catalog/import/{region}`, `GET /api/v1/catalog/...` |
20| Bill of quantities | `boq` | `POST /api/v1/boqs`, `GET /api/v1/boqs/{id}`, validate/import GAEB |
21| BIM elements / takeoff | `bim` | upload RVT/IFC/DWG/DGN, link elements to BOQ lines |
22| Schedule (4D) / cost (5D) | `scheduling` | tasks, dependencies, cost model roll-ups |
23| Issues & quality | `punch_list`, `validation` | punch items, validation rule packs (DIN276/NRM/GAEB) |
24| Site daily ops | `daily_diary`, `hse` | diary entries, safety observations |
25| Docs / tasks / risks | `documents`, `tasks`, `risks` | file approvals, task board, risk register |
26| Portfolio map | `geo_hub` | projects on a 3D globe |
27| Property development | `property_dev` | lead → SPA → handover |
28
29## Quick start (dev)
30
31```bash
32cd backend && python -m uvicorn app.main:create_app --factory --reload --port 8000
33cd frontend && npm run dev # http://localhost:5173
34```
35
36Auth: bootstrap admin (first registered user), JWT tokens, role-based permissions (viewer/editor/manager/admin). `POST /auth/register`, `POST /auth/login`.
37
38## Data contracts to respect
39
40- CWICR work-item parquets follow the **95-column master schema** (`rate_code`, `rate_original_name`, `rate_final_name`, `rate_unit`, `total_cost_per_position`, classification `collection/department/section/subsection/category`, resource lines `resource_*`, flags `is_material/is_machine/is_labor`).
41- Region ids match `^[A-Z]{2,3}_[A-Z0-9]+$` (e.g. `TR_NATIONAL`, `ZH_CHINA`, `BR_NATIONAL`).
42- The importer is idempotent on `(code, region)` — re-loading returns `already_loaded`.
43
44## Best practices
45
461. Load the base first (`load-cwicr`), then swap language (automatic via `home_language_code`), then reprice markets via the catalog path.
472. Never invent prices: leave unpriced coefficient bases (VN, ID) as rate 0 and use the resource price sheet.
483. Verify an import with `GET /api/v1/costs/regions/stats/` and a sampled item's `rate` against the parquet's `total_cost_per_position`.
gabrielmoreira