Architecture Overview

This document describes the high-level architecture of IFClite, including both client-side and server-side processing paradigms.

System Architecture

IFClite supports two processing paradigms: client-side (WASM in browser) and server-side (native Rust). It provides multi-model federation for loading and managing multiple IFC models simultaneously with unified selection, visibility control, and coordinated ID spaces.

Layer Overview

flowchart TB
    subgraph Clients["Clients"]
        direction LR
        Web["Web App"]
        Desktop["Desktop"]
        CLI["CLI"]
    end

    subgraph Features["Feature Layers"]
        direction LR
        Federation["Multi-Model Federation"]
        BCFFeature["BCF"]
        IDSFeature["IDS"]
        Drawings["2D Drawings"]
        MutationsFeature["Mutations"]
    end

    subgraph APIs["APIs"]
        direction LR
        TS["TypeScript"]
        WASM["WASM"]
        Rust["Rust"]
    end

    subgraph Storage["Storage"]
        direction LR
        Tables["Columnar Tables"]
        Graph["Relationship Graph"]
        GPU["GPU Buffers"]
    end

    Clients --> Features
    Features --> APIs
    APIs --> Storage

Processing Paradigms

The system offers two processing paths depending on your needs:

flowchart LR
    subgraph ClientPath["Client-Side (WASM)"]
        direction TB
        C1["Parser"]
        C2["Geometry"]
        C3["Renderer"]
        C1 --> C2 --> C3
    end

    subgraph ServerPath["Server-Side (Native)"]
        direction TB
        S1["Parser"]
        S2["Geometry"]
        S3["Parquet Encoder"]
        S4["Content Cache"]
        S1 --> S2 --> S3 --> S4
    end

Client vs Server Paradigm

Aspect	Client-Side (WASM)	Server-Side (Rust)
Processing	Single-threaded	Multi-threaded (Rayon)
Memory	4GB WASM limit	System RAM
Caching	Browser storage	Content-addressable disk
Format	Raw geometry	Parquet (15-50x smaller)
Best For	Privacy, offline	Teams, large files

Design Principles

1. Zero-Copy Where Possible

Data flows through the system with minimal copying:

flowchart LR
    subgraph Traditional["Traditional Approach"]
        T1["File Buffer"]
        T2["Parse to Objects"]
        T3["Convert to Arrays"]
        T4["Upload to GPU"]
        T1 -->|copy| T2 -->|copy| T3 -->|copy| T4
    end

    subgraph IFCLite["IFClite Approach"]
        I1["File Buffer"]
        I2["Direct Index"]
        I3["TypedArrays"]
        I4["GPU Upload"]
        I1 -->|reference| I2 -->|view| I3 -->|share| I4
    end

    style Traditional fill:#dc2626,stroke:#7f1d1d,color:#fff
    style IFCLite fill:#16a34a,stroke:#14532d,color:#fff

2. Streaming First

Process data incrementally for responsive UIs:

sequenceDiagram
    participant File
    participant Parser
    participant Processor
    participant Renderer
    participant User

    File->>Parser: Chunk 1
    Parser->>Processor: Entities 1-100
    Processor->>Renderer: Meshes 1-50
    Renderer->>User: First render (300ms)

    File->>Parser: Chunk 2
    Parser->>Processor: Entities 101-200
    Processor->>Renderer: Meshes 51-100
    Note over User: Progressive loading

    File->>Parser: Chunk N
    Parser->>Processor: All entities
    Processor->>Renderer: All meshes
    Renderer->>User: Complete

3. On-Demand Property Extraction

Properties parsed lazily for faster initial load:

flowchart LR
    subgraph TraditionalParsing["Traditional"]
        T1["Parse All Entities"]
        T2["Parse All Properties"]
        T3["Build All Tables"]
        T1 --> T2 --> T3
    end

    subgraph OnDemand["IFClite On-Demand"]
        O1["Parse Entities"]
        O2["Build Index"]
        O3["Map: entityId → psetIds"]
        O4["Parse on Access"]
        O1 --> O2 --> O3
        O3 -.->|"lazy"| O4
    end

    style TraditionalParsing fill:#dc2626,stroke:#7f1d1d,color:#fff
    style OnDemand fill:#16a34a,stroke:#14532d,color:#fff

4. Columnar Storage

Store data in columnar format for cache-efficient access:

graph TB
    subgraph RowBased["Row-Based (Traditional)"]
        R1["Entity 1: id=1, type=WALL, name='A'"]
        R2["Entity 2: id=2, type=DOOR, name='B'"]
        R3["Entity 3: id=3, type=WALL, name='C'"]
    end

    subgraph Columnar["Columnar (IFClite)"]
        C1["IDs: Uint32Array [1, 2, 3, ...]"]
        C2["Types: Uint16Array [WALL, DOOR, WALL, ...]"]
        C3["Names: StringTable ['A', 'B', 'C', ...]"]
    end

5. Hybrid Data Model

Combine the best of different data structures:

Data Structure	Use Case	Access Pattern
Columnar Tables	Bulk queries, filtering	Sequential scan
CSR Graph	Relationship traversal	Adjacency lookup
On-Demand Maps	Property access	Hash lookup
BVH	Raycasting	Tree traversal

Package Architecture

The monorepo contains 18 TypeScript packages, 4 Rust crates, and multiple application targets.

graph TB
    subgraph Rust["Rust Crates"]
        Core["ifc-lite-core<br/>Parsing"]
        Geo["ifc-lite-geometry<br/>Triangulation"]
        Wasm["ifc-lite-wasm<br/>Bindings"]
        Server["ifc-lite-server<br/>HTTP API"]
    end

    subgraph TS["TypeScript Packages (18)"]
        Parser["@ifc-lite/parser"]
        IFCX["@ifc-lite/ifcx"]
        Geometry["@ifc-lite/geometry"]
        Renderer["@ifc-lite/renderer"]
        ServerClient["@ifc-lite/server-client"]
        ServerBin["@ifc-lite/server-bin"]
        Cache["@ifc-lite/cache"]
        Query["@ifc-lite/query"]
        Data["@ifc-lite/data"]
        Export["@ifc-lite/export"]
        BCF["@ifc-lite/bcf"]
        IDS["@ifc-lite/ids"]
        Drawing2D["@ifc-lite/drawing-2d"]
        Mutations["@ifc-lite/mutations"]
        Spatial["@ifc-lite/spatial"]
        Codegen["@ifc-lite/codegen"]
        WasmTS["@ifc-lite/wasm"]
        CreateCLI["@ifc-lite/create-ifc-lite"]
    end

    subgraph Apps["Applications"]
        Viewer["Viewer App"]
        Desktop["Desktop (Tauri)"]
        CLI["create-ifc-lite"]
    end

    Wasm --> Core
    Wasm --> Geo
    Parser --> WasmTS
    WasmTS --> Wasm
    Geometry --> WasmTS
    Renderer --> Geometry
    ServerClient --> Server
    Query --> Data
    Export --> Data
    BCF --> Data
    IDS --> Data
    Drawing2D --> Geometry
    Mutations --> Data
    Spatial --> Data
    Viewer --> Parser
    Viewer --> Renderer
    Viewer --> ServerClient
    Desktop --> Core
    Desktop --> Geo

Server Architecture

flowchart TB
    subgraph Client["Browser Client"]
        Hash["SHA-256 Hash"]
        Upload["File Upload"]
        Decode["Parquet Decoder"]
        Render["WebGPU Renderer"]
    end

    subgraph Server["Rust Server (Axum)"]
        Router["API Router"]
        Parser["IFC Parser"]
        GeoProc["Geometry Processor"]
        DataModel["Data Model Extractor"]
        Serializer["Parquet Serializer"]
    end

    subgraph Cache["Cache Layer"]
        DiskCache[(Disk Cache)]
    end

    Hash -->|"check"| Router
    Router -->|"hit"| DiskCache
    DiskCache --> Decode
    Upload -->|"miss"| Parser
    Parser --> GeoProc
    Parser --> DataModel
    GeoProc --> Serializer
    DataModel --> Serializer
    Serializer --> DiskCache
    Serializer --> Decode
    Decode --> Render

    style Client fill:#6366f1,stroke:#312e81,color:#fff
    style Server fill:#10b981,stroke:#064e3b,color:#fff
    style Cache fill:#f59e0b,stroke:#7c2d12,color:#fff

Server Cache Strategy

sequenceDiagram
    participant Client
    participant Server
    participant Cache

    Client->>Client: Compute SHA-256 hash
    Client->>Server: GET /cache/check/{hash}

    alt Cache Hit
        Server->>Cache: Lookup
        Cache-->>Server: Parquet data
        Server-->>Client: 200 (skip upload!)
    else Cache Miss
        Server-->>Client: 404
        Client->>Server: POST /parse/parquet
        Server->>Server: Parse (parallel)
        Server->>Cache: Store
        Server-->>Client: Parquet response
    end

Data Flow

Client-Side Parse Flow

Each model is parsed independently and then registered with the FederationRegistry, which assigns non-overlapping ID ranges (idOffset) so that multiple models can coexist with unique global IDs (globalId = localExpressId + model.idOffset).

flowchart TB
    Input["IFC File<br/>(ArrayBuffer)"]

    subgraph Tokenize["1. Tokenize"]
        STEP["STEP Lexer"]
        Tokens["Token Stream"]
    end

    subgraph Scan["2. Scan"]
        EntityScan["Entity Scanner"]
        Index["Entity Index"]
    end

    subgraph Decode["3. Decode"]
        Decoder["Entity Decoder"]
        Attrs["Attributes"]
    end

    subgraph Store["4. Store"]
        Tables["Columnar Tables"]
        Graph["Relationship Graph"]
        OnDemand["On-Demand Maps"]
    end

    subgraph Federate["5. Federate"]
        Registry["FederationRegistry"]
        GlobalIDs["Global ID Assignment"]
    end

    Output["IfcDataStore"]

    Input --> Tokenize
    Tokenize --> Scan
    Scan --> Decode
    Decode --> Store
    Store --> Federate
    Federate --> Output

    style Input fill:#6366f1,stroke:#312e81,color:#fff
    style Tokenize fill:#2563eb,stroke:#1e3a8a,color:#fff
    style Scan fill:#10b981,stroke:#064e3b,color:#fff
    style Decode fill:#f59e0b,stroke:#7c2d12,color:#fff
    style Store fill:#a855f7,stroke:#581c87,color:#fff
    style Federate fill:#ec4899,stroke:#831843,color:#fff
    style Output fill:#16a34a,stroke:#14532d,color:#fff

Server-Side Parse Flow

flowchart TB
    Input["IFC File"]

    subgraph Parse["1. Parse (Parallel)"]
        Tokenize["STEP Tokenizer"]
        Extract["Entity Extractor"]
    end

    subgraph Process["2. Process (Parallel)"]
        Geo["Geometry Extraction"]
        Data["Data Model Extraction"]
    end

    subgraph Serialize["3. Serialize"]
        ParquetGeo["Parquet Geometry"]
        ParquetData["Parquet Data Model"]
    end

    subgraph Cache["4. Cache"]
        Store["Disk Cache"]
    end

    Output["Parquet Response"]

    Input --> Parse
    Parse --> Process
    Geo --> ParquetGeo
    Data --> ParquetData
    ParquetGeo --> Store
    ParquetData --> Store
    Store --> Output

    style Input fill:#6366f1,stroke:#312e81,color:#fff
    style Parse fill:#2563eb,stroke:#1e3a8a,color:#fff
    style Process fill:#10b981,stroke:#064e3b,color:#fff
    style Serialize fill:#f59e0b,stroke:#7c2d12,color:#fff
    style Cache fill:#a855f7,stroke:#581c87,color:#fff

Render Flow

flowchart TB
    subgraph Input["Input"]
        Meshes["Mesh Data"]
        Camera["Camera State"]
    end

    subgraph Process["Processing"]
        Cull["Frustum Culling"]
        Sort["Depth Sort"]
        Batch["Batching"]
    end

    subgraph Upload["GPU Upload"]
        Vertex["Vertex Buffers"]
        Index["Index Buffers"]
        Uniform["Uniforms"]
    end

    subgraph Render["Render"]
        Pass["Render Pass"]
        Section["Section Planes"]
        Draw["Draw Calls"]
    end

    Output["Canvas"]

    Input --> Process
    Process --> Upload
    Upload --> Render
    Render --> Output

    style Input fill:#6366f1,stroke:#312e81,color:#fff
    style Process fill:#2563eb,stroke:#1e3a8a,color:#fff
    style Upload fill:#10b981,stroke:#064e3b,color:#fff
    style Render fill:#f59e0b,stroke:#7c2d12,color:#fff
    style Output fill:#a855f7,stroke:#581c87,color:#fff

Memory Architecture

In a multi-model federation scenario, each loaded model maintains its own data store in the JS heap. The FederationRegistry tracks ID ranges per model to enable O(1) global-to-local ID resolution without duplicating entity data across models.

graph TB
    subgraph JS["JavaScript Heap"]
        Strings["String Table"]
        Metadata["Entity Metadata"]
        Query["Query Results"]
        OnDemand["On-Demand Maps"]
        FedRegistry["FederationRegistry"]
        Models["Models Map"]
    end

    subgraph Wasm["WASM Linear Memory"]
        Parser["Parser State"]
        Geometry["Geometry Processing"]
        Buffers["Mesh Buffers"]
    end

    subgraph GPU["GPU Memory"]
        VBO["Vertex Buffers"]
        IBO["Index Buffers"]
        UBO["Uniform Buffers"]
        ID["ID Buffer (Picking)"]
    end

    Wasm -->|"Zero-copy view"| JS
    Wasm -->|"Direct upload"| GPU

Memory Efficiency

Component	Memory Strategy
Strings	Deduplicated string table (30% reduction)
Entity IDs	Uint32Array (fixed-size)
Types	Uint16Array enum (2 bytes vs ~20 for string)
Properties	On-demand parsing (not pre-loaded)
Geometry	Streaming + dispose after upload
Server	Parquet (15-50x smaller transfer)

Threading Model

Client-Side

flowchart LR
    subgraph Main["Main Thread"]
        UI["UI Events"]
        Render["Rendering"]
        Query["Queries"]
    end

    subgraph Worker["Web Worker"]
        Parse["Parsing"]
        Geo["Geometry"]
    end

    Main <-->|"Transferable"| Worker

Server-Side

flowchart TB
    subgraph Axum["Axum Runtime"]
        Router["Async Router"]
        Handlers["Request Handlers"]
    end

    subgraph Rayon["Rayon Thread Pool"]
        Parser1["Parser Thread 1"]
        Parser2["Parser Thread 2"]
        ParserN["Parser Thread N"]
    end

    subgraph Tokio["Tokio Runtime"]
        Cache["Cache I/O"]
        Response["Response Stream"]
    end

    Router --> Handlers
    Handlers -->|"spawn_blocking"| Rayon
    Handlers --> Tokio

IFC5 (IFCX) Architecture

flowchart TB
    subgraph Input["IFCX File"]
        JSON["JSON Structure"]
        Header["Header"]
        Schemas["Schemas"]
        Data["Data Nodes"]
    end

    subgraph Composition["ECS Composition"]
        Flatten["Flatten Layers"]
        Inherit["Resolve Inheritance"]
        Tree["Build Tree"]
    end

    subgraph Extract["Extraction"]
        Entities["Entity Extractor"]
        Props["Property Extractor"]
        Geo["Geometry Extractor"]
        Hierarchy["Hierarchy Builder"]
    end

    subgraph Output["Output"]
        Store["IfcxParseResult"]
        Meshes["Pre-tessellated Meshes"]
    end

    Input --> Composition
    Composition --> Extract
    Extract --> Output

    style Input fill:#6366f1,stroke:#312e81,color:#fff
    style Composition fill:#10b981,stroke:#064e3b,color:#fff
    style Extract fill:#f59e0b,stroke:#7c2d12,color:#fff
    style Output fill:#a855f7,stroke:#581c87,color:#fff

Extension Points

graph TB
    subgraph Core["Core System"]
        Parser["Parser"]
        Geometry["Geometry"]
        Renderer["Renderer"]
    end

    subgraph Extensions["Extension Points"]
        CustomExtractor["Custom Extractors"]
        CustomProcessor["Custom Processors"]
        CustomShaders["Custom Shaders"]
        Plugins["Plugins"]
    end

    CustomExtractor -.->|extends| Parser
    CustomProcessor -.->|extends| Geometry
    CustomShaders -.->|extends| Renderer
    Plugins -.->|hooks| Core

Adding Custom Geometry Processor

import { GeometryProcessor, ProcessorRegistry } from '@ifc-lite/geometry';

class CustomProcessor extends GeometryProcessor {
  canProcess(entity: Entity): boolean {
    return entity.type === 'IFCMYCUSTOMTYPE';
  }

  process(entity: Entity): Mesh {
    // Custom processing logic
    return mesh;
  }
}

ProcessorRegistry.register(new CustomProcessor());

Technology Stack

graph TB
    subgraph Languages["Languages"]
        Rust["Rust"]
        TS["TypeScript"]
        WGSL["WGSL (Shaders)"]
    end

    subgraph Runtime["Runtime"]
        WASM["WebAssembly"]
        WebGPU["WebGPU"]
        Browser["Browser"]
        Node["Node.js"]
        Tauri["Tauri"]
    end

    subgraph Build["Build Tools"]
        Cargo["Cargo"]
        Vite["Vite"]
        WasmPack["wasm-pack"]
        Turborepo["Turborepo"]
    end

    subgraph Formats["Data Formats"]
        STEP["STEP (IFC4)"]
        IFCX["IFCX (IFC5)"]
        Parquet["Apache Parquet"]
        Cache["Binary Cache"]
    end

    Rust --> WASM
    Rust --> Tauri
    TS --> Browser
    TS --> Node
    WGSL --> WebGPU

    style Languages fill:#6366f1,stroke:#312e81,color:#fff
    style Runtime fill:#10b981,stroke:#064e3b,color:#fff
    style Build fill:#f59e0b,stroke:#7c2d12,color:#fff
    style Formats fill:#a855f7,stroke:#581c87,color:#fff

Next Steps

Data Flow - Detailed data flow diagrams
Parsing Pipeline - Parser architecture
Geometry Pipeline - Geometry processing
Rendering Pipeline - WebGPU rendering

Navigation Menu

Uh oh!

Architecture Overview

System Architecture

Layer Overview

Processing Paradigms

Client vs Server Paradigm

Design Principles

1. Zero-Copy Where Possible

2. Streaming First

3. On-Demand Property Extraction

4. Columnar Storage

5. Hybrid Data Model

Package Architecture

Server Architecture

Server Cache Strategy

Data Flow

Client-Side Parse Flow

Server-Side Parse Flow

Render Flow

Memory Architecture

Memory Efficiency

Threading Model

Client-Side

Server-Side

IFC5 (IFCX) Architecture

Extension Points

Adding Custom Geometry Processor

Technology Stack

Next Steps

Uh oh!

FilesExpand file tree

overview.md

Latest commit

History

overview.md

File metadata and controls

Architecture Overview

System Architecture

Layer Overview

Processing Paradigms

Client vs Server Paradigm

Design Principles

1. Zero-Copy Where Possible

2. Streaming First

3. On-Demand Property Extraction

4. Columnar Storage

5. Hybrid Data Model

Package Architecture

Server Architecture

Server Cache Strategy

Data Flow

Client-Side Parse Flow

Server-Side Parse Flow

Render Flow

Memory Architecture

Memory Efficiency

Threading Model

Client-Side

Server-Side

IFC5 (IFCX) Architecture

Extension Points

Adding Custom Geometry Processor

Technology Stack

Next Steps