# spinalcom/spinal-organ-api-server architecture

> Architecture diagram of the GitHub repository spinalcom/spinal-organ-api-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/spinalcom/spinal-organ-api-server
- Repository: https://github.com/spinalcom/spinal-organ-api-server

## Overview

spinal-organ-api-server is a REST API for querying and managing SpinalHub digital-twin data. Clients send requests through the Express server and registered route handlers, which expose spatial/BIM information, IoT networks and time series, analytics, workflow tickets, and organizational and user data. A separate startup path can preload graph nodes from a snapshot, while the server also supports socket access and optional monitoring. The tree and excerpts identify these subsystems; detailed wiring within unsampled route families is not asserted.

Main entry points: [`src/routes/routes.ts`](https://github.com/spinalcom/spinal-organ-api-server/blob/main/src/routes/routes.ts) (Route registration), [`src/api-server.ts`](https://github.com/spinalcom/spinal-organ-api-server/blob/main/src/api-server.ts) (Express API), [`src/spinalAPIMiddleware.ts`](https://github.com/spinalcom/spinal-organ-api-server/blob/main/src/spinalAPIMiddleware.ts) (Graph middleware), [`src/routes/snapshot`](https://github.com/spinalcom/spinal-organ-api-server/tree/main/src/routes/snapshot) (Node snapshots)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["API runtime"]
  node_api["Express API<br/>[api-server.ts]"]
  node_routes["Route registration<br/>[routes.ts]"]
  node_middleware["Graph middleware"]
end

subgraph group_twin["Twin data"]
  node_geo["Spatial contexts"]
  node_bim["BIM and scenes"]
  node_iot["IoT networks"]
  node_timeseries["Time series"]
  node_nodes["Graph nodes"]
  node_attributes["Attributes"]
end

subgraph group_operations["Operations"]
  node_analytics["Analytics"]
  node_tickets["Tickets and workflows"]
  node_calendar["Calendar events"]
  node_commands["Room commands"]
end

subgraph group_identity["Organization and users"]
  node_organization["Organization"]
  node_users["Users and groups"]
end

subgraph group_startup["Preload and integration"]
  node_snapshot["Node snapshots"]
  node_preload["Preload runner<br/>[runPreloading.ts]"]
  node_activity["Request activity<br/>[requestActivity.ts]"]
  node_socket["Socket service<br/>[index.ts]"]
end

node_client(("API client"))
node_hub[("SpinalHub graph")]
node_monitor["Monitoring service"]

node_client -->|"sends requests"| node_api
node_api -->|"registers routes"| node_routes
node_routes -->|"registers handlers"| node_geo
node_routes -->|"registers handlers"| node_bim
node_routes -->|"registers handlers"| node_iot
node_routes -->|"registers handlers"| node_analytics
node_routes -->|"registers handlers"| node_tickets
node_routes -->|"registers handlers"| node_calendar
node_routes -->|"registers handlers"| node_commands
node_routes -->|"registers handlers"| node_organization
node_routes -->|"registers handlers"| node_users
node_routes -->|"registers handlers"| node_snapshot
node_routes -->|"registers handlers"| node_nodes
node_routes -->|"registers handlers"| node_attributes
node_api -->|"uses graph access"| node_middleware
node_geo -->|"reads graph"| node_middleware
node_iot -->|"serves series routes"| node_timeseries
node_timeseries -->|"reads and writes"| node_hub
node_middleware -->|"connects to graph"| node_hub
node_snapshot -->|"enumerates loaded nodes"| node_hub
node_preload -->|"loads snapshot"| node_snapshot
node_preload -->|"waits for idle"| node_activity
node_api -->|"starts socket service"| node_socket
node_api -.->|"initializes optionally"| node_monitor

click node_api "https://github.com/spinalcom/spinal-organ-api-server/blob/main/src/api-server.ts"
click node_routes "https://github.com/spinalcom/spinal-organ-api-server/blob/main/src/routes/routes.ts"
click node_middleware "https://github.com/spinalcom/spinal-organ-api-server/blob/main/src/spinalAPIMiddleware.ts"
click node_geo "https://github.com/spinalcom/spinal-organ-api-server/tree/main/src/routes/geographicContext"
click node_bim "https://github.com/spinalcom/spinal-organ-api-server/tree/main/src/routes/BIM"
click node_iot "https://github.com/spinalcom/spinal-organ-api-server/tree/main/src/routes/IoTNetwork"
click node_timeseries "https://github.com/spinalcom/spinal-organ-api-server/tree/main/src/routes/IoTNetwork/timeSeries"
click node_nodes "https://github.com/spinalcom/spinal-organ-api-server/tree/main/src/routes/nodes"
click node_attributes "https://github.com/spinalcom/spinal-organ-api-server/tree/main/src/routes/attributs"
click node_analytics "https://github.com/spinalcom/spinal-organ-api-server/tree/main/src/routes/analysis"
click node_tickets "https://github.com/spinalcom/spinal-organ-api-server/tree/main/src/routes/tickets"
click node_calendar "https://github.com/spinalcom/spinal-organ-api-server/tree/main/src/routes/calendar"
click node_commands "https://github.com/spinalcom/spinal-organ-api-server/tree/main/src/routes/command"
click node_organization "https://github.com/spinalcom/spinal-organ-api-server/tree/main/src/routes/organization"
click node_users "https://github.com/spinalcom/spinal-organ-api-server/tree/main/src/routes/user"
click node_snapshot "https://github.com/spinalcom/spinal-organ-api-server/tree/main/src/routes/snapshot"
click node_preload "https://github.com/spinalcom/spinal-organ-api-server/blob/main/src/preloadingScript/runPreloading.ts"
click node_activity "https://github.com/spinalcom/spinal-organ-api-server/blob/main/src/preloadingScript/requestActivity.ts"
click node_socket "https://github.com/spinalcom/spinal-organ-api-server/blob/main/src/lib/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_routes,node_middleware,node_client toneBlue
class node_geo,node_bim,node_iot,node_timeseries,node_nodes,node_attributes,node_hub toneAmber
class node_analytics,node_tickets,node_calendar,node_commands toneMint
class node_organization,node_users toneRose
class node_snapshot,node_preload,node_activity,node_socket,node_monitor toneIndigo
```

## Components

### API runtime

- [Express API](https://github.com/spinalcom/spinal-organ-api-server/blob/main/src/api-server.ts): `src/api-server.ts`
- [Route registration](https://github.com/spinalcom/spinal-organ-api-server/blob/main/src/routes/routes.ts): `src/routes/routes.ts`
- [Graph middleware](https://github.com/spinalcom/spinal-organ-api-server/blob/main/src/spinalAPIMiddleware.ts): `src/spinalAPIMiddleware.ts`

### Twin data

- [Spatial contexts](https://github.com/spinalcom/spinal-organ-api-server/tree/main/src/routes/geographicContext): `src/routes/geographicContext`
- [BIM and scenes](https://github.com/spinalcom/spinal-organ-api-server/tree/main/src/routes/BIM): `src/routes/BIM`
- [IoT networks](https://github.com/spinalcom/spinal-organ-api-server/tree/main/src/routes/IoTNetwork): `src/routes/IoTNetwork`
- [Time series](https://github.com/spinalcom/spinal-organ-api-server/tree/main/src/routes/IoTNetwork/timeSeries): `src/routes/IoTNetwork/timeSeries`
- [Graph nodes](https://github.com/spinalcom/spinal-organ-api-server/tree/main/src/routes/nodes): `src/routes/nodes`
- [Attributes](https://github.com/spinalcom/spinal-organ-api-server/tree/main/src/routes/attributs): `src/routes/attributs`

### Operations

- [Analytics](https://github.com/spinalcom/spinal-organ-api-server/tree/main/src/routes/analysis): `src/routes/analysis`
- [Tickets and workflows](https://github.com/spinalcom/spinal-organ-api-server/tree/main/src/routes/tickets): `src/routes/tickets`
- [Calendar events](https://github.com/spinalcom/spinal-organ-api-server/tree/main/src/routes/calendar): `src/routes/calendar`
- [Room commands](https://github.com/spinalcom/spinal-organ-api-server/tree/main/src/routes/command): `src/routes/command`

### Organization and users

- [Organization](https://github.com/spinalcom/spinal-organ-api-server/tree/main/src/routes/organization): `src/routes/organization`
- [Users and groups](https://github.com/spinalcom/spinal-organ-api-server/tree/main/src/routes/user): `src/routes/user`

### Preload and integration

- [Node snapshots](https://github.com/spinalcom/spinal-organ-api-server/tree/main/src/routes/snapshot): `src/routes/snapshot`
- [Preload runner](https://github.com/spinalcom/spinal-organ-api-server/blob/main/src/preloadingScript/runPreloading.ts): `src/preloadingScript/runPreloading.ts`
- [Request activity](https://github.com/spinalcom/spinal-organ-api-server/blob/main/src/preloadingScript/requestActivity.ts): `src/preloadingScript/requestActivity.ts`
- [Socket service](https://github.com/spinalcom/spinal-organ-api-server/blob/main/src/lib/index.ts): `src/lib/index.ts`

### Other components

- **API client**
- **SpinalHub graph**
- **Monitoring service**

## Connections

- API client → Express API: sends requests
- Express API → Route registration: registers routes
- Route registration → Spatial contexts: registers handlers
- Route registration → BIM and scenes: registers handlers
- Route registration → IoT networks: registers handlers
- Route registration → Analytics: registers handlers
- Route registration → Tickets and workflows: registers handlers
- Route registration → Calendar events: registers handlers
- Route registration → Room commands: registers handlers
- Route registration → Organization: registers handlers
- Route registration → Users and groups: registers handlers
- Route registration → Node snapshots: registers handlers
- Route registration → Graph nodes: registers handlers
- Route registration → Attributes: registers handlers
- Express API → Graph middleware: uses graph access
- Spatial contexts → Graph middleware: reads graph
- IoT networks → Time series: serves series routes
- Time series → SpinalHub graph: reads and writes
- Graph middleware → SpinalHub graph: connects to graph
- Node snapshots → SpinalHub graph: enumerates loaded nodes
- Preload runner → Node snapshots: loads snapshot
- Preload runner → Request activity: waits for idle
- Express API → Socket service: starts socket service
- Express API → Monitoring service: initializes optionally