# veegres/ivory architecture

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

- Interactive diagram: https://gitdiagram.com/veegres/ivory
- Repository: https://github.com/veegres/ivory

## Overview

Ivory is a self-hosted web console for deploying and operating high-availability database clusters. The principal workflow is to register, discover, or deploy a cluster, then monitor its health and perform node, keeper, and database operations. The UI uses feature API clients to reach a Go server, which exposes domain services and database, keeper, and platform plugins. The README documents the product capabilities; some server-side connections are shown only as unverified because the relevant implementation was not excerpted.

Main entry points: [`app/shared/component/layout/Body.tsx`](https://github.com/veegres/ivory/blob/master/app/shared/component/layout/Body.tsx) (Page routing), [`app/features/node/component/keeper/Keeper.tsx`](https://github.com/veegres/ivory/blob/master/app/features/node/component/keeper/Keeper.tsx) (Node operations), [`app/features/query/api/QueryRouter.ts`](https://github.com/veegres/ivory/blob/master/app/features/query/api/QueryRouter.ts) (Query API client), [`server/features/query/query_service.go`](https://github.com/veegres/ivory/blob/master/server/features/query/query_service.go) (Query services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_app["Application shell<br/>[App.tsx]"]
  node_body["Page routing<br/>[Body.tsx]"]
  node_access_ui["Access and setup<br/>[ConfigBody.tsx]"]
end

subgraph group_cluster["Cluster operations"]
  node_cluster_ui["Cluster console<br/>[ClusterBody.tsx]"]
  node_cluster_api["Cluster API<br/>[ClusterRouter.ts]"]
  node_deployment_ui["Cluster deployment<br/>[ClusterDeploy.tsx]"]
  node_overview_ui["Health and HA<br/>[Overview.tsx]"]
  node_node_ui["Node operations<br/>[Keeper.tsx]"]
end

subgraph group_database["Database work"]
  node_database_ui["Query console<br/>[Query.tsx]"]
  node_query_api["Query API client<br/>[QueryRouter.ts]"]
  node_compact_ui["Table compaction<br/>[PgCompactTable.tsx]"]
end

subgraph group_server["Server services"]
  node_query_routes["Query endpoints<br/>[query_router.go]"]
  node_query_service["Query services<br/>[query_service.go]"]
  node_saved_queries[("Saved queries and logs")]
  node_compact_service["Compaction jobs"]
  node_auth_services["Authentication<br/>[auth_service.go]"]
  node_management_services["Management features"]
  node_storage[("Persistent storage<br/>[storage_db.go]")]
end

subgraph group_integrations["Runtime integrations"]
  node_platform_plugin["Host platform<br/>[platform_plugin.go]"]
  node_keeper_plugin{{"Keeper adapters<br/>[keeper_adapter.go]"}}
  node_database_plugins{{"Database adapters"}}
end

node_operator(("Operator"))

node_operator -->|"uses"| node_app
node_app -->|"renders"| node_body
node_body -->|"renders"| node_cluster_ui
node_body -->|"routes"| node_access_ui
node_operator -->|"manages clusters"| node_cluster_ui
node_cluster_ui -.->|"requests cluster actions"| node_cluster_api
node_operator -->|"deploys cluster"| node_deployment_ui
node_deployment_ui -.->|"submits deployment"| node_cluster_api
node_operator -->|"monitors and operates"| node_overview_ui
node_operator -->|"operates nodes"| node_node_ui
node_node_ui -.->|"controls host"| node_platform_plugin
node_node_ui -.->|"runs keeper actions"| node_keeper_plugin
node_operator -->|"runs queries"| node_database_ui
node_database_ui -->|"loads charts"| node_query_api
node_query_api -.->|"calls API"| node_query_routes
node_query_api -.->|"sends query requests"| node_query_routes
node_query_routes -.->|"dispatches"| node_query_service
node_query_service -.->|"executes database work"| node_database_plugins
node_query_service -.->|"reads and writes"| node_saved_queries
node_operator -->|"runs maintenance"| node_compact_ui
node_compact_ui -.->|"starts jobs"| node_compact_service
node_operator -->|"configures access"| node_access_ui
node_access_ui -.->|"authenticates"| node_auth_services
node_management_services -.->|"persists application data"| node_storage

click node_app "https://github.com/veegres/ivory/blob/master/app/core/App.tsx"
click node_body "https://github.com/veegres/ivory/blob/master/app/shared/component/layout/Body.tsx"
click node_cluster_ui "https://github.com/veegres/ivory/blob/master/app/core/pages/cluster/ClusterBody.tsx"
click node_cluster_api "https://github.com/veegres/ivory/blob/master/app/features/cluster/api/ClusterRouter.ts"
click node_deployment_ui "https://github.com/veegres/ivory/blob/master/app/features/cluster/component/ClusterDeploy.tsx"
click node_overview_ui "https://github.com/veegres/ivory/blob/master/app/core/pages/cluster/overview/Overview.tsx"
click node_node_ui "https://github.com/veegres/ivory/blob/master/app/features/node/component/keeper/Keeper.tsx"
click node_platform_plugin "https://github.com/veegres/ivory/blob/master/server/plugins/platform/platform_plugin.go"
click node_keeper_plugin "https://github.com/veegres/ivory/blob/master/server/plugins/keeper/keeper_adapter.go"
click node_database_ui "https://github.com/veegres/ivory/blob/master/app/features/query/component/Query.tsx"
click node_query_api "https://github.com/veegres/ivory/blob/master/app/features/query/api/QueryRouter.ts"
click node_query_routes "https://github.com/veegres/ivory/blob/master/server/features/query/query_router.go"
click node_query_service "https://github.com/veegres/ivory/blob/master/server/features/query/query_service.go"
click node_database_plugins "https://github.com/veegres/ivory/blob/master/server/plugins/database/database_adapter.go"
click node_saved_queries "https://github.com/veegres/ivory/blob/master/server/features/query/query_repository.go"
click node_compact_ui "https://github.com/veegres/ivory/blob/master/app/tools/pg_compacttable/component/PgCompactTable.tsx"
click node_compact_service "https://github.com/veegres/ivory/blob/master/server/tools/pg_compacttable/pg_compacttable_service.go"
click node_access_ui "https://github.com/veegres/ivory/blob/master/app/core/pages/config/ConfigBody.tsx"
click node_auth_services "https://github.com/veegres/ivory/blob/master/server/features/auth/auth_service.go"
click node_management_services "https://github.com/veegres/ivory/blob/master/server/features/management/management_service.go"
click node_storage "https://github.com/veegres/ivory/blob/master/server/clients/storage/storage_db.go"

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_body,node_access_ui toneBlue
class node_cluster_ui,node_cluster_api,node_deployment_ui,node_overview_ui,node_node_ui toneAmber
class node_database_ui,node_query_api,node_compact_ui toneMint
class node_query_routes,node_query_service,node_saved_queries,node_compact_service,node_auth_services,node_management_services,node_storage toneRose
class node_platform_plugin,node_keeper_plugin,node_database_plugins,node_operator toneIndigo
```

## Components

### Web application

- [Application shell](https://github.com/veegres/ivory/blob/master/app/core/App.tsx): `app/core/App.tsx`
- [Page routing](https://github.com/veegres/ivory/blob/master/app/shared/component/layout/Body.tsx): `app/shared/component/layout/Body.tsx`
- [Access and setup](https://github.com/veegres/ivory/blob/master/app/core/pages/config/ConfigBody.tsx): `app/core/pages/config/ConfigBody.tsx`

### Cluster operations

- [Cluster console](https://github.com/veegres/ivory/blob/master/app/core/pages/cluster/ClusterBody.tsx): `app/core/pages/cluster/ClusterBody.tsx`
- [Cluster API](https://github.com/veegres/ivory/blob/master/app/features/cluster/api/ClusterRouter.ts): `app/features/cluster/api/ClusterRouter.ts`
- [Cluster deployment](https://github.com/veegres/ivory/blob/master/app/features/cluster/component/ClusterDeploy.tsx): `app/features/cluster/component/ClusterDeploy.tsx`
- [Health and HA](https://github.com/veegres/ivory/blob/master/app/core/pages/cluster/overview/Overview.tsx): `app/core/pages/cluster/overview/Overview.tsx`
- [Node operations](https://github.com/veegres/ivory/blob/master/app/features/node/component/keeper/Keeper.tsx): `app/features/node/component/keeper/Keeper.tsx`

### Database work

- [Query console](https://github.com/veegres/ivory/blob/master/app/features/query/component/Query.tsx): `app/features/query/component/Query.tsx`
- [Query API client](https://github.com/veegres/ivory/blob/master/app/features/query/api/QueryRouter.ts): `app/features/query/api/QueryRouter.ts`
- [Table compaction](https://github.com/veegres/ivory/blob/master/app/tools/pg_compacttable/component/PgCompactTable.tsx): `app/tools/pg_compacttable/component/PgCompactTable.tsx`

### Server services

- [Query endpoints](https://github.com/veegres/ivory/blob/master/server/features/query/query_router.go): `server/features/query/query_router.go`
- [Query services](https://github.com/veegres/ivory/blob/master/server/features/query/query_service.go): `server/features/query/query_service.go`
- [Saved queries and logs](https://github.com/veegres/ivory/blob/master/server/features/query/query_repository.go): `server/features/query/query_repository.go`
- [Compaction jobs](https://github.com/veegres/ivory/blob/master/server/tools/pg_compacttable/pg_compacttable_service.go): `server/tools/pg_compacttable/pg_compacttable_service.go`
- [Authentication](https://github.com/veegres/ivory/blob/master/server/features/auth/auth_service.go): `server/features/auth/auth_service.go`
- [Management features](https://github.com/veegres/ivory/blob/master/server/features/management/management_service.go): `server/features/management/management_service.go`
- [Persistent storage](https://github.com/veegres/ivory/blob/master/server/clients/storage/storage_db.go): `server/clients/storage/storage_db.go`

### Runtime integrations

- [Host platform](https://github.com/veegres/ivory/blob/master/server/plugins/platform/platform_plugin.go): `server/plugins/platform/platform_plugin.go`
- [Keeper adapters](https://github.com/veegres/ivory/blob/master/server/plugins/keeper/keeper_adapter.go): `server/plugins/keeper/keeper_adapter.go`
- [Database adapters](https://github.com/veegres/ivory/blob/master/server/plugins/database/database_adapter.go): `server/plugins/database/database_adapter.go`

### Other components

- **Operator**

## Connections

- Operator → Application shell: uses
- Application shell → Page routing: renders (evidence: `app/core/App.tsx`)
- Page routing → Cluster console: renders (evidence: `app/shared/component/layout/Body.tsx`)
- Page routing → Access and setup: routes (evidence: `app/shared/component/layout/Body.tsx`)
- Operator → Cluster console: manages clusters
- Cluster console → Cluster API: requests cluster actions · Inferred; not shown in the code that was read.
- Operator → Cluster deployment: deploys cluster
- Cluster deployment → Cluster API: submits deployment · Inferred; not shown in the code that was read.
- Operator → Health and HA: monitors and operates
- Operator → Node operations: operates nodes
- Node operations → Host platform: controls host · Inferred; not shown in the code that was read.
- Node operations → Keeper adapters: runs keeper actions · Inferred; not shown in the code that was read.
- Operator → Query console: runs queries
- Query console → Query API client: loads charts
- Query API client → Query endpoints: calls API · Inferred; not shown in the code that was read. (evidence: `app/features/query/api/QueryRouter.ts`)
- Query API client → Query endpoints: sends query requests · Inferred; not shown in the code that was read.
- Query endpoints → Query services: dispatches · Inferred; not shown in the code that was read.
- Query services → Database adapters: executes database work · Inferred; not shown in the code that was read.
- Query services → Saved queries and logs: reads and writes · Inferred; not shown in the code that was read.
- Operator → Table compaction: runs maintenance
- Table compaction → Compaction jobs: starts jobs · Inferred; not shown in the code that was read.
- Operator → Access and setup: configures access
- Access and setup → Authentication: authenticates · Inferred; not shown in the code that was read.
- Management features → Persistent storage: persists application data · Inferred; not shown in the code that was read.
