Skip to content

App DB

Jump to bottom
TalarMustafa edited this page Oct 18, 2026 · 1 revision

Repository: RoamView-Technologies/roamview-app-db

The App DB is the RoamView application database, on MongoDB 7. It holds the structured records used by the RoamView Application and the API Gateway: organizations, users, sites, robots, sessions, mesh metadata, annotations, measurements, reports, inspection schedules and the object storage registry (storage_objects). File bytes stay in object storage; documents hold only their keys. It is not the Object Storage and not the Jobs DB.

Related use cases: UC-GU02 Auth, UC-GU03/04 Load meshes, UC-GU05 Mesh scan history, UC-GU06 Compare mesh version, UC-GU11 Annotate mesh, UC-OA01 Schedule inspections. Related specs: SP-4.3.1 (public / private meshes) in the Software Requirement Specification.

The collections map one-to-one from the ER diagram on Data Model & Storage. That page was written for PostgreSQL; the table below shows how it maps to MongoDB.

Data diagram

erDiagram
    direction TB
    organizations {
        string _id PK "UUID"
        string name
        string slug UK
        date created_at
    }
    users {
        string _id PK "UUID"
        string org_id FK
        string email UK "lowercase"
        string password_hash "nullable"
        string role "USER | ON_SITE_ADMIN"
        date created_at
    }
    sites {
        string _id PK "UUID"
        string org_id FK
        string name
        string address "nullable"
        object footprint "GeoJSON Polygon, 2dsphere"
        date created_at
    }
    robots {
        string _id PK "UUID"
        string org_id FK
        string site_id FK "nullable"
        string name
        string serial_number UK
        string status
        int battery_pct "0-100"
        date last_seen_at "nullable"
    }
    sessions {
        string _id PK "UUID"
        string site_id FK
        string robot_id FK
        string operator_id FK "nullable"
        string mode "AUTONOMOUS | LIVE_WALKTHROUGH"
        string status
        string video_storage_key "nullable"
        date started_at
        date ended_at "nullable"
    }
    meshes {
        string _id PK "UUID"
        string session_id FK,UK
        string previous_mesh_id FK,UK "nullable"
        string visibility "PUBLIC | PRIVATE"
        int version ">= 1"
        string object_storage_key "nullable"
        string tileset_key "nullable"
        string preview_key "nullable"
        date created_at
    }
    annotations {
        string _id PK "UUID"
        string mesh_id FK
        string author_id FK
        object position "x, y, z"
        string label
        string severity "nullable"
        string notes "nullable"
        date created_at
    }
    measurements {
        string _id PK "UUID"
        string mesh_id FK
        string author_id FK
        string type
        array points "x, y, z (2 or more)"
        double value_meters
        date created_at
    }
    reports {
        string _id PK "UUID"
        string session_id FK,UK
        string author_id FK
        string title
        string pdf_storage_key "nullable"
        date generated_at
    }
    scheduled_inspections {
        string _id PK "UUID"
        string site_id FK
        string robot_id FK
        date run_at
        string status
    }
    inspection_jobs {
        string _id PK "UUID"
        string schedule_id FK,UK
        string session_id FK,UK "nullable"
        string status
    }
    storage_objects {
        string _id PK "UUID"
        string org_id FK
        string session_id FK "nullable"
        string bucket "roamview-raw | -work | -assets | -media"
        string object_key "UK with bucket"
        string kind "RGB_SET | DEPTH_SET | TELEMETRY | SLAM_MAP | VIDEO | MESH | TILESET | PREVIEW | REPORT | INTERMEDIATE"
        string content_type
        long size_bytes
        string sha256 "nullable"
        string status "PENDING | AVAILABLE | ARCHIVED | DELETED"
        date expires_at "nullable"
        date created_at
    }

    organizations ||--o{ users : has
    organizations ||--o{ sites : owns
    organizations ||--o{ robots : owns
    sites ||--o| robots : assigned
    users ||--o{ sessions : operates
    sites ||--o{ sessions : hosts
    robots ||--o{ sessions : performs
    sessions ||--o| meshes : produces
    sessions ||--o| reports : generates
    meshes |o--o| meshes : previous_version
    meshes ||--o{ annotations : has
    meshes ||--o{ measurements : has
    users ||--o{ annotations : authors
    users ||--o{ measurements : authors
    sites ||--o{ scheduled_inspections : schedules
    robots ||--o{ scheduled_inspections : target
    scheduled_inspections ||--o| inspection_jobs : creates
    inspection_jobs ||--o| sessions : results_in
    organizations ||--o{ storage_objects : "owns files"
    sessions |o--o{ storage_objects : "raw capture, video"
Loading

Mapping from the ER diagram

ER diagram (PostgreSQL) App DB (MongoDB)
Table Collection with the same name
id uuid PK _id: UUID string, set by the application (crypto.randomUUID() / uuid.NewString()). ObjectIds are rejected by the validators
xxx_id uuid FK xxx_id: UUID string of the other document. MongoDB does not enforce foreign keys; the services do
timestamp BSON date
int / bigint / float BSON int or long / long / any number
geometry footprint GeoJSON Polygon (longitude, latitude) with a 2dsphere index
geometry position, jsonb points {x, y, z} objects in the mesh's local frame (metres)
*_key columns Object storage keys only. File bytes never go into the App DB. null until the upload is AVAILABLE
Column names Unchanged (snake_case), so the wiki model and the database read the same

Every collection has a $jsonSchema validator (validationLevel: strict, validationAction: error). Validators check required fields, types and the enums that the data model fixes. Extra fields are allowed.

Indexes

Every collection also has MongoDB's default unique index on _id. Unique indexes enforce the "zero or one" sides of the diagram.

Collection Index name Keys Options Used for
organizations slug_unique slug unique Look up an organization by slug
users email_unique email unique Sign-in (UC-GU02)
users org_id org_id Users of an organization
sites org_id_name org_id, name Sites of an organization, sorted by name
sites footprint_2dsphere footprint 2dsphere Map / location queries
robots serial_number_unique serial_number unique Robot registration
robots org_id org_id Robots of an organization
robots site_id site_id Robot assigned to a site
sessions site_id_started_at site_id, started_at desc Scan history of a site (UC-GU05)
sessions robot_id_started_at robot_id, started_at desc Sessions of a robot
sessions operator_id_started_at operator_id, started_at desc Sessions of a user
sessions status status Sessions waiting for processing
meshes session_id_unique session_id unique One mesh per session
meshes previous_mesh_id_unique previous_mesh_id unique, only when set One next version per mesh (UC-GU06)
meshes visibility_created_at visibility, created_at desc Public meshes (UC-GU03, SP-4.3.1)
annotations mesh_id_created_at mesh_id, created_at Annotations of a mesh (UC-GU11)
annotations author_id author_id Annotations by a user
measurements mesh_id_created_at mesh_id, created_at Measurements of a mesh
measurements author_id author_id Measurements by a user
reports session_id_unique session_id unique One report per session
reports author_id author_id Reports by a user
scheduled_inspections site_id_run_at site_id, run_at Schedule of a site (UC-OA01)
scheduled_inspections robot_id_run_at robot_id, run_at Schedule of a robot
scheduled_inspections status_run_at status, run_at Next runs due
inspection_jobs schedule_id_unique schedule_id unique One job per schedule entry
inspection_jobs session_id_unique session_id unique, only when set One session per job
inspection_jobs status status Open jobs
storage_objects bucket_object_key_unique bucket, object_key unique One registry entry per file
storage_objects session_id_kind session_id, kind All files of a session
storage_objects status_expires_at status, expires_at Retention sweeper
storage_objects org_id org_id Storage usage per organization

Interfaces

Exposes

Interface Caller Notes
MongoDB wire protocol, database roamview RoamView Application (Next.js, mongodb driver) MONGODB_URI, MONGODB_DB
MongoDB wire protocol, database roamview API Gateway (Go, go.mongodb.org/mongo-driver/v2) MONGODB_URI, MONGODB_DB; /readyz should ping it

Locally the URI is mongodb://localhost:27017/roamview (Docker, no password, reachable from the same computer only). A managed instance (MongoDB Atlas) uses a mongodb+srv:// URI kept out of the repos.

Refers to

Target How
Object storage (roamview-raw, -work, -assets, -media) *_key fields and storage_objects.bucket + object_key. See Data Model & Storage §3 
flowchart LR
    APP["RoamView Application<br/>(Next.js, mongodb driver)"]
    GW["API Gateway<br/>(Go, mongo-driver v2)"]
    DB[("App DB<br/>MongoDB 7 · database roamview")]
    OS[("Object Storage<br/>file bytes")]
    APP -- "MONGODB_URI" --> DB
    GW -- "MONGODB_URI" --> DB
    DB -. "*_key / storage_objects.object_key" .-> OS
Loading

Running it

See the repo README for start / stop / reset, connection snippets for Next.js and Go, the Atlas steps and CI.

RoamView Wiki

Clone this wiki locally