Buildings

The Building domain model is the physical core of CrowdVision’s digital twin paradigm. It is entirely responsible for storing the 3D spatial layout of a facility alongside the operational parameters of its rooms.

🏢 The Building Aggregate

The Building acts as the Aggregate Root for all spatial data.

export interface IBuilding {
    id: string;
    rooms: Room[];
    domains: string[];
}

The Decoupled Multi-Tenancy Design

Notice that the domains array is an array of strings, not MongoDB ObjectId references.

• Why we did this: The Twin Service operates on a completely isolated database (twin-db). It literally cannot execute a database join against the Auth Service’s Domain collection. By storing the domain name directly as a string, the Twin Service can independently authorize requests by simply matching these strings against the domain names embedded inside the user’s JWT.

🚪 The Room Entity

A Building is composed of an array of Room entities. In MongoDB, these are stored as embedded subdocuments rather than a separate collection, ensuring that fetching a building returns its complete 3D geometry in a single, lightning-fast query.

export interface Room {
    id: string;
    capacity: number;
    temperature: number;
    no_person: number;
    position: Coordinates;
    dimensions: Dimensions;
    color?: string;
    maxTemperature?: number;
}

The Room entity elegantly mixes two different types of data:

1. Static / Metadata: Fields like id, capacity, maxTemperature, and color dictate the safety constraints and visual representation of the room.
2. Dynamic / Operational: Fields like temperature and no_person (headcount) represent the live state of the physical space. (Note: In a heavily scaled production environment, operational data might be offloaded to an in-memory store like Redis, but embedding it here allows for simple snapshotting).

📐 Spatial Value Objects

To render the 3D Digital Twin on the frontend using TresJS, the backend must provide exact spatial coordinates.

CrowdVision strictly types these using rigid Value Objects: Coordinates and Dimensions.

classDiagram
    class Room {
        +String id
        +Number capacity
        +Number no_person
    }

    class Coordinates {
        <<Value Object>>
        +Number x
        +Number y
        +Number z
    }

    class Dimensions {
        <<Value Object>>
        +Number width
        +Number height
        +Number depth
    }

    Room "1" *-- "1" Coordinates : position
    Room "1" *-- "1" Dimensions : dimensions

• Coordinates (x, y, z): Determines the exact center-point placement of the room block within the 3D scene.
• Dimensions (width, height, depth): Determines the volumetric size of the room block.

Because these are Value Objects, they have no distinct identity (_id: false in the Mongoose schema). They only exist as descriptors of the Room.

⚙️ The Digital Twin Lifecycle (CRUD)

Managing buildings is a two-step lifecycle process.

1.Deployment (JSON Schema) A building cannot be created room-by-room via the UI. Instead, the entire physical structure is defined externally in a JSON file containing the full array of rooms, coordinates, and dimensions.

An administrator uploads this JSON file via the Dashboard, which performs a POST request to the Twin Service to bootstrap the Building document.

2. Runtime Mutations Once the building geometry is deployed, physical spaces often change context. A lecture hall might have its capacity reduced for an exam, or a server room might require a lower maxTemperature threshold.

Instead of forcing a re-upload of the entire Building JSON, the Twin Service provides specific PUT /twin/buildings/:domain/:buildingId/rooms/:roomId endpoints. This allows authorized staff to edit individual room properties dynamically on the fly.