From 354d6e8c140801cac2e871ecedc84d6ccd5d8954 Mon Sep 17 00:00:00 2001
From: warnason <276599704+warnason@users.noreply.github.com>
Date: Mon, 27 Apr 2026 11:10:41 +0200
Subject: [PATCH] Add test suite and polish project documentation

- 8 pytest tests covering health, upload validation, API responses, schemas
- Updated README with architecture diagram, feature list, design decisions
- Live demo link and complete API reference
---
 README.md | 109 ++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 78 insertions(+), 31 deletions(-)

diff --git a/README.md b/README.md
index 403f041..519daba 100644
--- a/README.md
+++ b/README.md
@@ -4,12 +4,51 @@ Interactive IFC-based 3D building model viewer. Upload an IFC file to
 inspect building elements, their properties, and navigate the model in
 a browser-based 3D view.
 
+**Live demo:** [bim.stifting.at](https://bim.stifting.at)
+
+## Features
+
+- Upload IFC files (IFC2x3, IFC4) via drag-and-drop or file picker
+- Server-side conversion to glTF binary for efficient 3D rendering
+- Interactive Three.js viewer with orbit, pan, and zoom controls
+- Click any building element to inspect its IFC properties
+- Filter elements by type (wall, door, window, slab, ...) and storey
+- Double-click to set a new orbit pivot point
+- Collapsible floating panels for unobstructed 3D viewing
+- Full REST API with automatic OpenAPI documentation
+
 ## Tech stack
 
-- **Backend:** Python 3.12, FastAPI, SQLAlchemy (async), IfcOpenShell
-- **Frontend:** Vue.js 3, Three.js
-- **Database:** PostgreSQL 16
-- **Infrastructure:** Docker Compose, Caddy, Forgejo CI
+| Layer          | Technology                                      |
+|----------------|------------------------------------------------|
+| Backend        | Python 3.12, FastAPI, SQLAlchemy (async)        |
+| IFC processing | IfcOpenShell (parsing + geometry serialization) |
+| Frontend       | Vue.js 3, Three.js, Vite                        |
+| Database       | PostgreSQL 16                                   |
+| Infrastructure | Docker Compose, Caddy, Forgejo CI, Linux        |
+
+## Architecture
+
+```
+Browser                          Server
+┌─────────────┐    HTTPS    ┌──────────────────────────┐
+│  Vue.js     │◄───────────►│  Caddy (reverse proxy)   │
+│  Three.js   │             └──────┬───────────────────┘
+│  GLTFLoader │                    │
+└─────────────┘             ┌──────▼───────────────────┐
+                            │  FastAPI                  │
+                            │  ├─ /api/upload           │
+                            │  ├─ /api/projects         │
+                            │  ├─ /api/elements         │
+                            │  └─ /api/projects/*/model │
+                            └──────┬───────────────────┘
+                                   │
+                    ┌──────────────┼──────────────┐
+                    ▼              ▼              ▼
+              PostgreSQL    IfcOpenShell     glb files
+              (elements,    (IFC parser +   (3D models)
+               properties)  geometry engine)
+```
 
 ## Quick start
 
@@ -20,9 +59,27 @@ cp .env.example .env
 docker compose up -d
 ```
 
-- **API:** http://localhost:8000
-- **API docs:** http://localhost:8000/docs
 - **Frontend:** http://localhost:5173
+- **API docs:** http://localhost:8000/docs
+- **Health check:** http://localhost:8000/health
+
+## API overview
+
+| Method | Endpoint                                          | Description                |
+|--------|---------------------------------------------------|----------------------------|
+| GET    | `/health`                                         | Health check               |
+| POST   | `/api/upload`                                     | Upload and parse IFC file  |
+| GET    | `/api/projects`                                   | List all projects          |
+| GET    | `/api/projects/{id}/elements`                     | List elements (filterable) |
+| GET    | `/api/projects/{id}/elements/by-global-id/{gid}`  | Lookup element by GlobalId |
+| GET    | `/api/elements/{id}`                              | Element detail + properties|
+| GET    | `/api/projects/{id}/model.glb`                    | Download 3D model          |
+
+## Running tests
+
+```bash
+docker compose exec backend python -m pytest -v
+```
 
 ## Project structure
 
@@ -33,44 +90,34 @@ docker compose up -d
 │   │   ├── api/            # FastAPI route handlers
 │   │   ├── models/         # SQLAlchemy ORM models
 │   │   ├── schemas/        # Pydantic request/response schemas
-│   │   └── services/       # Business logic (IFC parsing)
-│   ├── tests/
+│   │   └── services/       # IFC parsing and geometry conversion
+│   ├── tests/              # pytest test suite
 │   ├── Dockerfile
 │   └── requirements.txt
 ├── frontend/
 │   ├── src/
-│   │   ├── components/     # Vue components (viewer, panels)
-│   │   ├── views/          # Page-level views
-│   │   └── composables/    # Reusable composition functions
+│   │   ├── components/     # Vue components
+│   │   ├── composables/    # useApi, useViewer (Three.js)
+│   │   └── App.vue         # Main application
 │   ├── Dockerfile
 │   └── package.json
-├── data/
-│   └── sample/             # Example IFC files for testing
-├── docs/
+├── data/sample/            # Example IFC files
 ├── docker-compose.yml
 └── README.md
 ```
 
-## API overview
+## Design decisions
 
-| Method | Endpoint                              | Description               |
-|--------|---------------------------------------|---------------------------|
-| GET    | `/health`                             | Health check              |
-| POST   | `/api/upload`                         | Upload and parse IFC file |
-| GET    | `/api/projects`                       | List all projects         |
-| GET    | `/api/projects/{id}/elements`         | List elements (filterable)|
-| GET    | `/api/elements/{id}`                  | Element detail + properties|
+- **Server-side IFC→glb conversion** rather than client-side WASM processing.
+  IfcOpenShell's geometry engine produces optimized meshes with IFC GlobalIds
+  preserved as mesh names, enabling click-to-inspect without shipping heavy
+  WASM bundles to the browser.
 
-## Running tests
+- **Async SQLAlchemy** for non-blocking database access during concurrent
+  file uploads and API queries.
 
-```bash
-# Backend
-docker compose exec backend pytest -v
-
-# Or locally
-cd backend
-python -m pytest -v
-```
+- **Floating UI panels** over a full-viewport 3D canvas for maximum spatial
+  awareness while inspecting element metadata.
 
 ## License