# virtualoptimization/vo-server architecture

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

- Interactive diagram: https://gitdiagram.com/virtualoptimization/vo-server
- Repository: https://github.com/virtualoptimization/vo-server

## Overview

VO-server is a FastAPI backend for an iOS LiDAR room-scanning and furniture-placement service. The implemented workflow accepts a typed scan at the versioned API, passes it to an endpoint, and returns an S3-style key; the S3 helper is currently a stub, and database persistence is explicitly TODO. The README also describes optimization, USDZ-to-FBX conversion, code-based VR lookup, and WebSocket synchronization, but their implementation files are absent from the supplied tree. Those capabilities are shown as documented, unverified subsystems, not inspected runtime components.

Main entry points: [`server/api/v1/endpoints/scans.py`](https://github.com/virtualoptimization/vo-server/blob/main/server/api/v1/endpoints/scans.py) (Scan receiver), [`server/api/v1/router.py`](https://github.com/virtualoptimization/vo-server/blob/main/server/api/v1/router.py) (v1 router), [`server/core/s3.py`](https://github.com/virtualoptimization/vo-server/blob/main/server/core/s3.py) (S3 uploader stub), [`server/main.py`](https://github.com/virtualoptimization/vo-server/blob/main/server/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Scan API"]
  node_app["FastAPI app<br/>[main.py]"]
  node_router["v1 router<br/>[router.py]"]
  node_scan["Scan receiver<br/>[scans.py]"]
  node_scan_schema["Scan schemas<br/>[scan.py]"]
end

subgraph group_storage["Storage configuration"]
  node_s3_helper["S3 uploader stub<br/>[s3.py]"]
  node_config["Settings<br/>[config.py]"]
end

subgraph group_capabilities["Documented capabilities"]
  node_optimizer["Placement optimizer"]
  node_converter["USDZ-FBX converter"]
  node_vr_lookup["VR code lookup"]
  node_realtime["Furniture sync"]
end

node_ios(("iOS scanner"))
node_vr_client(("VR client"))

node_ios -->|"submits scan"| node_scan
node_app -->|"mounts routes"| node_router
node_router -->|"routes scans"| node_scan
node_scan -->|"accepts payload"| node_scan_schema
node_scan -->|"calls upload"| node_s3_helper
node_s3_helper -->|"reads settings"| node_config
node_scan -.->|"optimization workflow"| node_optimizer
node_optimizer -.->|"converts model"| node_converter
node_vr_client -.->|"requests room"| node_vr_lookup
node_vr_client -.->|"interacts live"| node_realtime

click node_app "https://github.com/virtualoptimization/vo-server/blob/main/server/main.py"
click node_router "https://github.com/virtualoptimization/vo-server/blob/main/server/api/v1/router.py"
click node_scan "https://github.com/virtualoptimization/vo-server/blob/main/server/api/v1/endpoints/scans.py"
click node_scan_schema "https://github.com/virtualoptimization/vo-server/blob/main/server/schemas/scan.py"
click node_s3_helper "https://github.com/virtualoptimization/vo-server/blob/main/server/core/s3.py"
click node_config "https://github.com/virtualoptimization/vo-server/blob/main/server/core/config.py"

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_app,node_router,node_scan,node_scan_schema,node_vr_client toneBlue
class node_s3_helper,node_config toneAmber
class node_optimizer,node_converter,node_vr_lookup,node_realtime toneMint
class node_ios toneIndigo
```

## Components

### Scan API

- [FastAPI app](https://github.com/virtualoptimization/vo-server/blob/main/server/main.py): `server/main.py`
- [v1 router](https://github.com/virtualoptimization/vo-server/blob/main/server/api/v1/router.py): `server/api/v1/router.py`
- [Scan receiver](https://github.com/virtualoptimization/vo-server/blob/main/server/api/v1/endpoints/scans.py): `server/api/v1/endpoints/scans.py`
- [Scan schemas](https://github.com/virtualoptimization/vo-server/blob/main/server/schemas/scan.py): `server/schemas/scan.py`

### Storage configuration

- [S3 uploader stub](https://github.com/virtualoptimization/vo-server/blob/main/server/core/s3.py): `server/core/s3.py`
- [Settings](https://github.com/virtualoptimization/vo-server/blob/main/server/core/config.py): `server/core/config.py`

### Documented capabilities

- **Placement optimizer**
- **USDZ-FBX converter**
- **VR code lookup**
- **Furniture sync**

### Other components

- **iOS scanner**
- **VR client**

## Connections

- iOS scanner → Scan receiver: submits scan (evidence: `README.md`)
- FastAPI app → v1 router: mounts routes (evidence: `server/main.py`)
- v1 router → Scan receiver: routes scans (evidence: `server/api/v1/router.py`)
- Scan receiver → Scan schemas: accepts payload (evidence: `server/api/v1/endpoints/scans.py`)
- Scan receiver → S3 uploader stub: calls upload (evidence: `server/api/v1/endpoints/scans.py`)
- S3 uploader stub → Settings: reads settings (evidence: `server/core/s3.py`)
- Scan receiver → Placement optimizer: optimization workflow (evidence: `README.md`)
- Placement optimizer → USDZ-FBX converter: converts model (evidence: `README.md`)
- VR client → VR code lookup: requests room (evidence: `README.md`)
- VR client → Furniture sync: interacts live (evidence: `README.md`)
