Architecting veribim-kg: A Cloud-Native, Full-Stack Blueprint for Construction Compliance

Architecting veribim-kg: A Cloud-Native, Full-Stack Blueprint for Construction Compliance

The vision for veribim-kg is clear: a unified Knowledge Layer that answers complex compliance questions. But how do we build it? This article outlines the proposed application architecture, focusing on a cloud-native, microservices approach built entirely with open-source technologies and containerised for scalability and resilience.

Our goal is to create a system that is modular, scalable, and can efficiently handle the data pipeline from IFC file ingestion and PDF decomposition to intelligent Q&A via RAG and LLM.

High-Level Architecture Overview

The system is conceived as a collection of loosely coupled services, communicating via well-defined REST APIs for front-end data fetching. The overall architecture can be broken down into three main layers:

1. Frontend Layer: A React-based single-page application (SPA).
2. Backend Layer: A suite of Node.js/Express microservices, with a Python service for the AI pipeline.
3. Data & Infrastructure Layer: Neo4j, a S3-like file store (e.g., MinIO), and everything orchestrated via Docker.

1. The Frontend: A React-based Dashboard and Viewer

The user interface is a React SPA, chosen for its component-based architecture and rich ecosystem.

• Technology Stack: React, TypeScript, Vite, and a UI library like Chakra UI.
• Core Component - IFC.js Viewer: The centrepiece is the 3D model viewer built with IFC.js. This allows users to visualise the BIM model, select elements, and see compliance data in context. The viewer component will communicate with the backend services to fetch and highlight non-compliant elements or show related evidence.
• State Management: For a complex application like this, we'd use a state management library like Zustand or Redux Toolkit to manage the global application state (e.g., user sessions, selected model elements, current query results).
• API Communication: The frontend will interact with the backend through a dedicated Backend-for-Frontend (BFF) pattern, implemented as an API Gateway.

2. The Backend: A Microservices Ecosystem in Node.js and Python

The backend is decomposed into discrete, focused services. This allows for independent development, scaling, and deployment.

a) API Gateway (Express.js)

• Role: The single entry point for all client requests. It handles authentication, rate limiting, request routing, and response aggregation.
• Implementation: We'll use a framework like Express.js with middleware like http-proxy-middleware to cleanly route traffic to the appropriate downstream service.

b) BIM Ingestion Service (Express.js)

• Role: This is the workhorse for processing IFC files.
• Implementation: It uses IFC.js in a Node.js environment to parse uploaded IFC files. The service extracts entities, properties, and spatial hierarchies. It then translates this structured data into a series of Cypher queries to populate the Neo4j graph, creating nodes for each IfcWall, IfcDoor, etc., and establishing their relationships.
• Cloud-Native Consideration: This service can be scaled independently during large model uploads and is designed to be stateless, offloading the file blob to a S3-like cloud storage service - MinIO running in the same Docker cluster.

c) Knowledge Graph Service (Express.js)

• Role: To serve as the primary interface for querying the Neo4j graph. It encapsulates all the complex Cypher logic required to navigate the web of requirements, BIM elements, and evidence.
• Implementation: This service exposes a RESTful API that the frontend and other services can call. For example, an endpoint like GET /elements/:id/compliance-requirements would execute a Cypher query to find all regulations linked to a specific BIM element. We'll use the official neo4j-driver for Node.js.

d) RAG & LLM Service (Python/FastAPI)

• Role: To orchestrate the Retrieval-Augmented Generation pipeline, acting as the "AI brain" of the application.
• Why Python? While Node.js is excellent for I/O-bound tasks, the AI/ML ecosystem is predominantly Python-based (LangChain, LlamaIndex, transformer libraries). Using FastAPI allows us to build a high-performance, asynchronous API that integrates seamlessly with these libraries.
• Implementation:
  1. It receives a natural language query from the API Gateway.
  2. It uses an LLM (e.g., via the OpenAI API) to decompose the query and generate a parameterised Cypher query.
  3. It calls the Knowledge Graph Service to retrieve the relevant context, ensuring all graph access logic remains centralised.
  4. It synthesizes the context and the original question into a final prompt for the LLM, which generates the human-readable, evidence-backed answer.

3. Data & Infrastructure: The Cloud-Ready Foundation

a) Docker Containers & Orchestration

• Every service (React frontend, API Gateway, BIM Service, KG Service, RAG Service) is packaged as a separate Docker container.
• We use Docker Compose for local development to spin up the entire stack with one command.
• For production, the architecture is designed to be deployed on a Kubernetes cluster (e.g., on EKS, AKS, or GKE) for auto-scaling, self-healing, and seamless service discovery.

b) Neo4j Database

• The heart of the system. We run Neo4j in its own container, and in production, we would use a managed service or a stateful set in Kubernetes with persistent volumes.

c) File Store

• IFC files and associated evidence (photos, PDFs) are stored in a scalable object storage system like S3, abstracted via a service to keep the application stateless.

Conclusion: A Foundation for Innovation

This proposed architecture for veribim-kg provides a robust, scalable, and modular foundation. By leveraging a full-stack Node.js core with a Python-based AI service, we get the best of both worlds: the performance and ecosystem of Node.js for web services and data processing, and the power of Python's AI/ML stack.

The containerised, microservices approach makes the system inherently cloud-ready, allowing teams to develop, scale, and deploy services independently. This is more than a theoretical exercise; it's a practical blueprint for building the next generation of intelligent, data-driven applications for the construction industry and beyond. The code is taking shape at GitHub.