BIM-Guard

🔗 Live Demo

👉 View the BIMGUARD AI Interactive Pipeline

MAICEN-1125-M10 · Final Master's Project · Group 5 · Zigurat Global Institute of Technology

Project Overview

BIM Guard is a BIM compliance application built with FastHTML (Python) and MonsterUI. It lets users upload IFC models, define compliance rules from documents, and generate reports.

Tech stack: FastHTML · MonsterUI · Supabase (Postgres + Storage) · IfcOpenShell · HTMX · Gemini

Instructions Files Map

File	Who reads it	What it defines
README.md	Humans	What the project is
AGENTS.md, CLAUDE.md, .github/instructions/project-specific.instructions.md	Coding agents	How to build the project
DESIGN.md	Design agents	How the project should look and feel

Repository Structure

bim-guard/
├── app/                        # Main application package
│   ├── main.py                 # FastHTML app init and route mounting
│   ├── utils.py                # Shared utilities (env loading, helpers)
│   ├── components/             # Reusable FastHTML UI elements
│   │   ├── layout.py           # DashboardLayout, AppSidebar, AppHeader
│   │   ├── documents_ui.py
│   │   ├── projects_ui.py
│   │   ├── rules_ui.py
│   │   ├── rule_extraction_ui.py
│   │   ├── themed_ui.py
│   │   └── ui/                 # Low-level component primitives
│   │       ├── button.py, card.py, table.py, sidebar.py, ...
│   ├── routes/                 # HTTP handlers and HTMX responses
│   │   ├── dashboard.py
│   │   ├── library.py
│   │   ├── projects.py
│   │   ├── analyze.py
│   │   └── viewer.py           # In-browser IFC 3D viewer
│   ├── services/               # Business logic and persistence adapters
│   │   ├── persistence.py      # DB backend selector (Supabase default)
│   │   ├── db_adapters.py      # SQLite/Supabase table adapter layer
│   │   ├── object_storage.py   # Local/Supabase object storage adapter
│   │   ├── documents_service.py
│   │   ├── projects_service.py
│   │   ├── rules_service.py
│   │   ├── rule_extraction_service.py
│   │   ├── gemini_rule_extractor.py
│   │   └── ifc_parser.py
│   ├── modules/                # 5-step compliance pipeline
│   │   ├── module1_doc_parser/
│   │   ├── module2_ifc_read.py
│   │   ├── module3_rule_builder/
│   │   ├── module4_comparator.py
│   │   ├── module5_reporter.py
│   │   └── orchestrator.py
│   └── views/
│       └── layout.py
├── data/                       # Runtime cache and local dev artifacts
│   ├── cache/
│   └── rulesets/
├── scripts/                    # One-off migration/backfill utilities
├── docs/                       # Supporting documentation and resources
├── static/                     # CSS, JS, and IFC viewer assets
│   ├── css/
│   ├── js/
│   └── lib/
├── IFC-Sample-Test-Files/      # Sample IFC models for testing
├── main.py                     # Uvicorn entrypoint
├── pyproject.toml              # Python project metadata and dependencies
└── example.env                 # Environment variable template

Getting Started

1. Clone the repository

git clone https://github.com/maicen/bim-guard.git
cd bim-guard

2. Install uv

uv is the package manager used by this project. Install it with:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

3. Install dependencies

Step 3a — core app dependencies (FastHTML, MonsterUI, pypdf, etc.):

uv sync

This creates a .venv and installs all dependencies declared in pyproject.toml. Python 3.12 or later is required.

Step 3b — ML pipeline dependencies group (Docling, spaCy, scikit-learn, etc.):

uv sync --group ml-pipeline

This installs the optional ml-pipeline dependency group defined in pyproject.toml (including docling, spacy + English model, and scikit-learn). First run may download model weights — allow a few minutes.

4. Configure environment variables

Create a .env file from the template:

# PowerShell
Copy-Item example.env .env

# macOS / Linux
cp example.env .env

Open .env and set Supabase credentials:

BIM_GUARD_DB_BACKEND=supabase
BIM_GUARD_STORAGE_BACKEND=supabase
SUPABASE_URL=...
SUPABASE_KEY=...
SUPABASE_SERVICE_ROLE_KEY=...

For rule extraction, also set a Gemini key (free at aistudio.google.com/api-keys):

GEMINI_API_KEY=your_key_here

Without Gemini credentials, the Rule Extraction Studio (/library/rules/extract) will show an error. Core project/document workflows still work.

5. Run the app

uv run uvicorn main:app --reload

The app will be available at http://127.0.0.1:8000.

Deployment

Docker Compose

Run with Docker Compose (Supabase-backed):

docker compose up --build

• docker-compose.yml passes Supabase environment variables from host .env.
• A named cache volume is mounted at /app/data/cache for downloaded storage objects.

Render.com

This repository includes render.yaml for Render deployment using Docker.

Required Render environment variables:

• SUPABASE_URL
• SUPABASE_KEY
• SUPABASE_SERVICE_ROLE_KEY

Optional AI variables:

• GEMINI_API_KEY
• GOOGLE_API_KEY
• BIM_GUARD_RULE_MODEL

Rule Extraction (AI)

Rule extraction is available at /library/rules/extract.

Current flow:

1. Upload a BEP/regulation PDF.
2. Module1_DocParser extracts PDF text.
3. Text is normalized and chunked for long documents.
4. RuleExtractionService sends each chunk to Gemini through LiteLLM.
5. Extracted rules are normalized and de-duplicated.

Documentation Map

Use docs/README.md as the authoritative index for repository documentation. It groups markdown files by purpose and marks which docs are current vs. archival/reference.

Next Development Steps

• Verify the reported issues.
• Verify the BCF exported.

Output rule fields:

• ref
• desc
• target

Notes

• If .env is not loaded (for custom scripts/tests), call load_env_file() from app.utils before creating AI extraction services.
• Document upload validation includes extension, MIME type, and content checks.

Python Docstrings and API Docs

This repository follows PEP 257 docstring conventions and uses Python's built-in pydoc for API documentation.

Lint docstring style (PEP 257) with Ruff:

uv run ruff check .

Generate terminal docs for a module:

uv run python -m pydoc app.modules.orchestrator

Generate HTML docs for a module:

uv run python -m pydoc -w app.modules.orchestrator

Docstring policy for contributors:

• Add docstrings for new public modules, classes, and functions.
• Keep docstrings imperative and concise (PEP 257).
• Include parameters/return behavior when it improves clarity.