# khushal-senghani/omni-host architecture

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

- Interactive diagram: https://gitdiagram.com/khushal-senghani/omni-host
- Repository: https://github.com/khushal-senghani/omni-host

## Overview

Omni-Host is a self-hosted Fastify hub that discovers app plugins, validates their configuration, mounts them behind a central server, and provides authentication and system-health endpoints. The main flow is request to the server, through authentication or a mounted app, to a response; the server also owns startup discovery and registration. The README describes SQLite, but the sampled database models and server connection refer to MongoDB, so the graph reflects the sampled implementation. Unsampled subsystems are included only where the README or source index supports them.

Main entry points: [`apps/server/src/index.ts`](https://github.com/khushal-senghani/omni-host/blob/main/apps/server/src/index.ts) (Fastify Server), [`packages/auth/src/plugin.ts`](https://github.com/khushal-senghani/omni-host/blob/main/packages/auth/src/plugin.ts) (Auth Endpoints), [`packages/core/src/loader.ts`](https://github.com/khushal-senghani/omni-host/blob/main/packages/core/src/loader.ts) (App Discovery), [`apps/test-app/src/routes.ts`](https://github.com/khushal-senghani/omni-host/blob/main/apps/test-app/src/routes.ts) (Example App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Server Gateway"]
  node_server["Fastify Server<br/>[index.ts]"]
  node_request_id["Request IDs<br/>[requestId.ts]"]
  node_error_handler["Error Handler<br/>[error-handler.ts]"]
  node_system_routes["System Routes<br/>[system.ts]"]
end

subgraph group_apps["App Runtime"]
  node_discovery["App Discovery<br/>[loader.ts]"]
  node_plugin_contract["Plugin Contract<br/>[plugin.ts]"]
  node_registry["Plugin Registry<br/>[registry.ts]"]
  node_test_app["Example App<br/>[routes.ts]"]
end

subgraph group_auth["Authentication"]
  node_auth_plugin["Auth Endpoints<br/>[plugin.ts]"]
  node_auth_strategies["Auth Strategies<br/>[strategies.ts]"]
  node_password["Password Verification<br/>[password.ts]"]
end

subgraph group_core["Core Services"]
  node_env_merge["App Env Validation<br/>[merge.ts]"]
end

subgraph group_data["Persistence"]
  node_database[("Database Connection<br/>[index.ts]")]
  node_users[("User Records<br/>[Users.ts]")]
  node_refresh_tokens[("Refresh Tokens<br/>[RefreshToken.ts]")]
  node_api_keys[("API Keys<br/>[ApiKey.ts]")]
  node_scoped_db["Scoped Database<br/>[scoped.ts]"]
end

node_client(("API Client"))

node_client -->|"sends requests"| node_server
node_server -->|"registers"| node_request_id
node_server -->|"registers"| node_error_handler
node_server -->|"registers"| node_auth_plugin
node_server -->|"connects"| node_database
node_server -->|"discovers apps"| node_discovery
node_discovery -->|"validates"| node_plugin_contract
node_discovery -->|"imports app"| node_test_app
node_server -->|"registers results"| node_registry
node_server -->|"validates app envs"| node_env_merge
node_server -->|"registers"| node_system_routes
node_system_routes -->|"reads status"| node_registry
node_server -->|"mounts plugin"| node_test_app
node_test_app -->|"uses authenticate"| node_auth_strategies
node_auth_plugin -->|"reads user"| node_users
node_auth_plugin -->|"reads and writes"| node_refresh_tokens
node_auth_plugin -->|"verifies password"| node_password
node_auth_strategies -->|"checks key"| node_api_keys
node_server -->|"creates app scope"| node_scoped_db

click node_server "https://github.com/khushal-senghani/omni-host/blob/main/apps/server/src/index.ts"
click node_request_id "https://github.com/khushal-senghani/omni-host/blob/main/apps/server/src/plugins/requestId.ts"
click node_error_handler "https://github.com/khushal-senghani/omni-host/blob/main/apps/server/src/plugins/error-handler.ts"
click node_system_routes "https://github.com/khushal-senghani/omni-host/blob/main/apps/server/src/routes/system.ts"
click node_discovery "https://github.com/khushal-senghani/omni-host/blob/main/packages/core/src/loader.ts"
click node_plugin_contract "https://github.com/khushal-senghani/omni-host/blob/main/packages/core/src/types/plugin.ts"
click node_registry "https://github.com/khushal-senghani/omni-host/blob/main/packages/core/src/registry.ts"
click node_test_app "https://github.com/khushal-senghani/omni-host/blob/main/apps/test-app/src/routes.ts"
click node_env_merge "https://github.com/khushal-senghani/omni-host/blob/main/packages/config/src/merge.ts"
click node_auth_plugin "https://github.com/khushal-senghani/omni-host/blob/main/packages/auth/src/plugin.ts"
click node_auth_strategies "https://github.com/khushal-senghani/omni-host/blob/main/packages/auth/src/strategies.ts"
click node_password "https://github.com/khushal-senghani/omni-host/blob/main/packages/auth/src/password.ts"
click node_database "https://github.com/khushal-senghani/omni-host/blob/main/packages/core/src/db/index.ts"
click node_users "https://github.com/khushal-senghani/omni-host/blob/main/packages/core/src/db/models/Users.ts"
click node_refresh_tokens "https://github.com/khushal-senghani/omni-host/blob/main/packages/core/src/db/models/RefreshToken.ts"
click node_api_keys "https://github.com/khushal-senghani/omni-host/blob/main/packages/core/src/db/models/ApiKey.ts"
click node_scoped_db "https://github.com/khushal-senghani/omni-host/blob/main/packages/core/src/db/scoped.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_server,node_request_id,node_error_handler,node_system_routes,node_client toneBlue
class node_discovery,node_plugin_contract,node_registry,node_test_app toneAmber
class node_auth_plugin,node_auth_strategies,node_password toneMint
class node_env_merge toneRose
class node_database,node_users,node_refresh_tokens,node_api_keys,node_scoped_db toneIndigo
```

## Components

### Server Gateway

- [Fastify Server](https://github.com/khushal-senghani/omni-host/blob/main/apps/server/src/index.ts): `apps/server/src/index.ts`
- [Request IDs](https://github.com/khushal-senghani/omni-host/blob/main/apps/server/src/plugins/requestId.ts): `apps/server/src/plugins/requestId.ts`
- [Error Handler](https://github.com/khushal-senghani/omni-host/blob/main/apps/server/src/plugins/error-handler.ts): `apps/server/src/plugins/error-handler.ts`
- [System Routes](https://github.com/khushal-senghani/omni-host/blob/main/apps/server/src/routes/system.ts): `apps/server/src/routes/system.ts`

### App Runtime

- [App Discovery](https://github.com/khushal-senghani/omni-host/blob/main/packages/core/src/loader.ts): `packages/core/src/loader.ts`
- [Plugin Contract](https://github.com/khushal-senghani/omni-host/blob/main/packages/core/src/types/plugin.ts): `packages/core/src/types/plugin.ts`
- [Plugin Registry](https://github.com/khushal-senghani/omni-host/blob/main/packages/core/src/registry.ts): `packages/core/src/registry.ts`
- [Example App](https://github.com/khushal-senghani/omni-host/blob/main/apps/test-app/src/routes.ts): `apps/test-app/src/routes.ts`

### Authentication

- [Auth Endpoints](https://github.com/khushal-senghani/omni-host/blob/main/packages/auth/src/plugin.ts): `packages/auth/src/plugin.ts`
- [Auth Strategies](https://github.com/khushal-senghani/omni-host/blob/main/packages/auth/src/strategies.ts): `packages/auth/src/strategies.ts`
- [Password Verification](https://github.com/khushal-senghani/omni-host/blob/main/packages/auth/src/password.ts): `packages/auth/src/password.ts`

### Core Services

- [App Env Validation](https://github.com/khushal-senghani/omni-host/blob/main/packages/config/src/merge.ts): `packages/config/src/merge.ts`

### Persistence

- [Database Connection](https://github.com/khushal-senghani/omni-host/blob/main/packages/core/src/db/index.ts): `packages/core/src/db/index.ts`
- [User Records](https://github.com/khushal-senghani/omni-host/blob/main/packages/core/src/db/models/Users.ts): `packages/core/src/db/models/Users.ts`
- [Refresh Tokens](https://github.com/khushal-senghani/omni-host/blob/main/packages/core/src/db/models/RefreshToken.ts): `packages/core/src/db/models/RefreshToken.ts`
- [API Keys](https://github.com/khushal-senghani/omni-host/blob/main/packages/core/src/db/models/ApiKey.ts): `packages/core/src/db/models/ApiKey.ts`
- [Scoped Database](https://github.com/khushal-senghani/omni-host/blob/main/packages/core/src/db/scoped.ts): `packages/core/src/db/scoped.ts`

### Other components

- **API Client**

## Connections

- API Client → Fastify Server: sends requests (evidence: `README.md`)
- Fastify Server → Request IDs: registers (evidence: `apps/server/src/index.ts`)
- Fastify Server → Error Handler: registers (evidence: `apps/server/src/index.ts`)
- Fastify Server → Auth Endpoints: registers (evidence: `apps/server/src/index.ts`)
- Fastify Server → Database Connection: connects (evidence: `apps/server/src/index.ts`)
- Fastify Server → App Discovery: discovers apps (evidence: `apps/server/src/index.ts`)
- App Discovery → Plugin Contract: validates (evidence: `packages/core/src/loader.ts`)
- App Discovery → Example App: imports app (evidence: `packages/core/src/loader.ts`)
- Fastify Server → Plugin Registry: registers results (evidence: `apps/server/src/index.ts`)
- Fastify Server → App Env Validation: validates app envs (evidence: `apps/server/src/index.ts`)
- Fastify Server → System Routes: registers (evidence: `apps/server/src/index.ts`)
- System Routes → Plugin Registry: reads status (evidence: `apps/server/src/routes/system.ts`)
- Fastify Server → Example App: mounts plugin (evidence: `README.md`)
- Example App → Auth Strategies: uses authenticate (evidence: `apps/test-app/src/routes.ts`)
- Auth Endpoints → User Records: reads user (evidence: `packages/auth/src/plugin.ts`)
- Auth Endpoints → Refresh Tokens: reads and writes (evidence: `packages/auth/src/plugin.ts`)
- Auth Endpoints → Password Verification: verifies password (evidence: `packages/auth/src/plugin.ts`)
- Auth Strategies → API Keys: checks key (evidence: `packages/auth/src/strategies.ts`)
- Fastify Server → Scoped Database: creates app scope (evidence: `apps/server/src/index.ts`)
