# mentra-community/mentraos architecture

> Architecture diagram of the GitHub repository mentra-community/mentraos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mentra-community/mentraos
- Repository: https://github.com/mentra-community/mentraos

## Overview

MentraOS is a cross-compatible smart-glasses platform: users pair glasses with a phone, run miniapps in the phone-side Mentra Runtime, and use shared device and hardware capabilities. The repository also contains cloud services for identity, workspaces, app registry, reports, and administration, plus SDK/client packages for building integrations. The README explicitly describes miniapps running in the Runtime and multiple apps sharing a glasses connection; many cloud and mobile internals are represented by tree paths but were not sampled, so their links are marked unverified rather than treated as inspected call paths.

Main entry points: [`cloud-v2/packages/runtime/src/services/runtime-services.ts`](https://github.com/mentra-community/mentraos/blob/dev/cloud-v2/packages/runtime/src/services/runtime-services.ts) (Mentra Runtime), [`cloud-v2/packages/core/src/api/app.ts`](https://github.com/mentra-community/mentraos/blob/dev/cloud-v2/packages/core/src/api/app.ts) (Cloud API), [`mobile/modules/engine/src/engine.ts`](https://github.com/mentra-community/mentraos/blob/dev/mobile/modules/engine/src/engine.ts) (Mobile host), [`cloud-v2/packages/core/src/services/report.service.ts`](https://github.com/mentra-community/mentraos/blob/dev/cloud-v2/packages/core/src/services/report.service.ts) (Reports and logs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Phone Runtime"]
  node_phone["Mobile host<br/>[engine.ts]"]
  node_runtime["Mentra Runtime"]
  node_engine_cloud["Cloud client service"]
  node_protocol["Device protocol<br/>[messages.ts]"]
  node_runtime_storage["Runtime blob storage<br/>[storage.service.ts]"]
end

subgraph group_apps["Miniapp Workloads"]
  node_captions["Captions miniapp"]
  node_navigation["Navigation miniapp"]
  node_recorder["Recorder miniapp"]
  node_teleprompter["Teleprompter miniapp"]
end

subgraph group_cloud["Cloud Platform"]
  node_cloud_api["Cloud API<br/>[app.ts]"]
  node_identity["Identity and OIDC<br/>[provider.ts]"]
  node_workspaces["Workspace services"]
  node_registry["Miniapp registry"]
  node_reports["Reports and logs<br/>[report.service.ts]"]
  node_core_storage["Core blob storage<br/>[storage.service.ts]"]
end

subgraph group_developer["SDK and Operations"]
  node_cloud_client["Cloud client SDK<br/>[client.ts]"]
  node_miniapp_sdk["Miniapp SDK<br/>[navigation.ts]"]
  node_admin["Admin console<br/>[App.tsx]"]
  node_mcp["Console MCP<br/>[server.ts]"]
end

node_user(("Glasses user"))
node_glasses["Smart glasses"]

node_user -.->|"uses"| node_phone
node_phone -.->|"hosts apps"| node_runtime
node_runtime -.->|"shares connection"| node_glasses
node_runtime -.->|"runs miniapp"| node_captions
node_runtime -.->|"runs miniapp"| node_navigation
node_runtime -.->|"runs miniapp"| node_recorder
node_runtime -.->|"runs miniapp"| node_teleprompter
node_phone -->|"initializes"| node_engine_cloud
node_runtime -.->|"uses messages"| node_protocol
node_phone -.->|"connects to cloud"| node_cloud_api
node_cloud_client -.->|"calls API"| node_cloud_api
node_cloud_api -.->|"delegates identity"| node_identity
node_cloud_api -.->|"serves workspace operations"| node_workspaces
node_cloud_api -.->|"serves registry operations"| node_registry
node_cloud_api -.->|"serves report operations"| node_reports
node_reports -.->|"stores artifacts"| node_core_storage
node_runtime -.->|"stores runtime blobs"| node_runtime_storage
node_miniapp_sdk -.->|"accesses runtime"| node_runtime
node_admin -.->|"administers services"| node_cloud_api
node_mcp -.->|"accesses console data"| node_cloud_api

click node_phone "https://github.com/mentra-community/mentraos/blob/dev/mobile/modules/engine/src/engine.ts"
click node_runtime "https://github.com/mentra-community/mentraos/blob/dev/cloud-v2/packages/runtime/src/services/runtime-services.ts"
click node_engine_cloud "https://github.com/mentra-community/mentraos/blob/dev/mobile/modules/engine/src/services/CloudClientService.ts"
click node_protocol "https://github.com/mentra-community/mentraos/blob/dev/cloud-v2/packages/protocol/src/messages.ts"
click node_captions "https://github.com/mentra-community/mentraos/blob/dev/miniapps/captions/src/background/controllers/CaptionsController.ts"
click node_navigation "https://github.com/mentra-community/mentraos/blob/dev/miniapps/navigation/src/background/NavigationController.ts"
click node_recorder "https://github.com/mentra-community/mentraos/blob/dev/miniapps/recorder/src/background/controllers/RecorderController.ts"
click node_teleprompter "https://github.com/mentra-community/mentraos/blob/dev/miniapps/teleprompter/src/background/controllers/TeleprompterController.ts"
click node_cloud_api "https://github.com/mentra-community/mentraos/blob/dev/cloud-v2/packages/core/src/api/app.ts"
click node_identity "https://github.com/mentra-community/mentraos/blob/dev/cloud-v2/packages/core/src/services/oidc/provider.ts"
click node_workspaces "https://github.com/mentra-community/mentraos/blob/dev/cloud-v2/packages/core/src/services/workspaces/workspace.service.ts"
click node_registry "https://github.com/mentra-community/mentraos/blob/dev/cloud-v2/packages/core/src/services/registry/registry.service.ts"
click node_reports "https://github.com/mentra-community/mentraos/blob/dev/cloud-v2/packages/core/src/services/report.service.ts"
click node_core_storage "https://github.com/mentra-community/mentraos/blob/dev/cloud-v2/packages/core/src/services/storage/storage.service.ts"
click node_runtime_storage "https://github.com/mentra-community/mentraos/blob/dev/cloud-v2/packages/runtime/src/services/storage/storage.service.ts"
click node_cloud_client "https://github.com/mentra-community/mentraos/blob/dev/cloud-v2/packages/cloud-client/src/client.ts"
click node_miniapp_sdk "https://github.com/mentra-community/mentraos/blob/dev/mobile/modules/miniapp/src/modules/navigation.ts"
click node_admin "https://github.com/mentra-community/mentraos/blob/dev/cloud-v2/websites/admin/src/App.tsx"
click node_mcp "https://github.com/mentra-community/mentraos/blob/dev/cloud-v2/packages/console-mcp/src/server.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_phone,node_runtime,node_engine_cloud,node_protocol,node_runtime_storage,node_user toneBlue
class node_captions,node_navigation,node_recorder,node_teleprompter toneAmber
class node_cloud_api,node_identity,node_workspaces,node_registry,node_reports,node_core_storage toneMint
class node_cloud_client,node_miniapp_sdk,node_admin,node_mcp toneRose
class node_glasses toneIndigo
```

## Components

### Phone Runtime

- [Mobile host](https://github.com/mentra-community/mentraos/blob/dev/mobile/modules/engine/src/engine.ts): `mobile/modules/engine/src/engine.ts`
- [Mentra Runtime](https://github.com/mentra-community/mentraos/blob/dev/cloud-v2/packages/runtime/src/services/runtime-services.ts): `cloud-v2/packages/runtime/src/services/runtime-services.ts`
- [Cloud client service](https://github.com/mentra-community/mentraos/blob/dev/mobile/modules/engine/src/services/CloudClientService.ts): `mobile/modules/engine/src/services/CloudClientService.ts`
- [Device protocol](https://github.com/mentra-community/mentraos/blob/dev/cloud-v2/packages/protocol/src/messages.ts): `cloud-v2/packages/protocol/src/messages.ts`
- [Runtime blob storage](https://github.com/mentra-community/mentraos/blob/dev/cloud-v2/packages/runtime/src/services/storage/storage.service.ts): `cloud-v2/packages/runtime/src/services/storage/storage.service.ts`

### Miniapp Workloads

- [Captions miniapp](https://github.com/mentra-community/mentraos/blob/dev/miniapps/captions/src/background/controllers/CaptionsController.ts): `miniapps/captions/src/background/controllers/CaptionsController.ts`
- [Navigation miniapp](https://github.com/mentra-community/mentraos/blob/dev/miniapps/navigation/src/background/NavigationController.ts): `miniapps/navigation/src/background/NavigationController.ts`
- [Recorder miniapp](https://github.com/mentra-community/mentraos/blob/dev/miniapps/recorder/src/background/controllers/RecorderController.ts): `miniapps/recorder/src/background/controllers/RecorderController.ts`
- [Teleprompter miniapp](https://github.com/mentra-community/mentraos/blob/dev/miniapps/teleprompter/src/background/controllers/TeleprompterController.ts): `miniapps/teleprompter/src/background/controllers/TeleprompterController.ts`

### Cloud Platform

- [Cloud API](https://github.com/mentra-community/mentraos/blob/dev/cloud-v2/packages/core/src/api/app.ts): `cloud-v2/packages/core/src/api/app.ts`
- [Identity and OIDC](https://github.com/mentra-community/mentraos/blob/dev/cloud-v2/packages/core/src/services/oidc/provider.ts): `cloud-v2/packages/core/src/services/oidc/provider.ts`
- [Workspace services](https://github.com/mentra-community/mentraos/blob/dev/cloud-v2/packages/core/src/services/workspaces/workspace.service.ts): `cloud-v2/packages/core/src/services/workspaces/workspace.service.ts`
- [Miniapp registry](https://github.com/mentra-community/mentraos/blob/dev/cloud-v2/packages/core/src/services/registry/registry.service.ts): `cloud-v2/packages/core/src/services/registry/registry.service.ts`
- [Reports and logs](https://github.com/mentra-community/mentraos/blob/dev/cloud-v2/packages/core/src/services/report.service.ts): `cloud-v2/packages/core/src/services/report.service.ts`
- [Core blob storage](https://github.com/mentra-community/mentraos/blob/dev/cloud-v2/packages/core/src/services/storage/storage.service.ts): `cloud-v2/packages/core/src/services/storage/storage.service.ts`

### SDK and Operations

- [Cloud client SDK](https://github.com/mentra-community/mentraos/blob/dev/cloud-v2/packages/cloud-client/src/client.ts): `cloud-v2/packages/cloud-client/src/client.ts`
- [Miniapp SDK](https://github.com/mentra-community/mentraos/blob/dev/mobile/modules/miniapp/src/modules/navigation.ts): `mobile/modules/miniapp/src/modules/navigation.ts`
- [Admin console](https://github.com/mentra-community/mentraos/blob/dev/cloud-v2/websites/admin/src/App.tsx): `cloud-v2/websites/admin/src/App.tsx`
- [Console MCP](https://github.com/mentra-community/mentraos/blob/dev/cloud-v2/packages/console-mcp/src/server.ts): `cloud-v2/packages/console-mcp/src/server.ts`

### Other components

- **Glasses user**
- **Smart glasses**

## Connections

- Glasses user → Mobile host: uses
- Mobile host → Mentra Runtime: hosts apps
- Mentra Runtime → Smart glasses: shares connection
- Mentra Runtime → Captions miniapp: runs miniapp
- Mentra Runtime → Navigation miniapp: runs miniapp
- Mentra Runtime → Recorder miniapp: runs miniapp
- Mentra Runtime → Teleprompter miniapp: runs miniapp
- Mobile host → Cloud client service: initializes (evidence: `mobile/modules/engine/src/engine.ts`)
- Mentra Runtime → Device protocol: uses messages
- Mobile host → Cloud API: connects to cloud
- Cloud client SDK → Cloud API: calls API
- Cloud API → Identity and OIDC: delegates identity
- Cloud API → Workspace services: serves workspace operations
- Cloud API → Miniapp registry: serves registry operations
- Cloud API → Reports and logs: serves report operations
- Reports and logs → Core blob storage: stores artifacts
- Mentra Runtime → Runtime blob storage: stores runtime blobs
- Miniapp SDK → Mentra Runtime: accesses runtime
- Admin console → Cloud API: administers services
- Console MCP → Cloud API: accesses console data
