# fixn222/qube architecture

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

- Interactive diagram: https://gitdiagram.com/fixn222/qube
- Repository: https://github.com/fixn222/qube

## Overview

Qube is a PostgreSQL developer workspace: users manage organizations and isolated project schemas through a Next.js dashboard or the qube-js SDK, while a NestJS API provides schema, data, SQL, REST, realtime, storage, and analytics capabilities. The graph follows the documented user-to-API-to-database flow and preserves major product branches. Some API internals are unsampled; those nodes use exact paths from the repository tree, and links are included only where the README or shown source supports them.

Main entry points: [`apps/web/src/app`](https://github.com/fixn222/qube/tree/main/apps/web/src/app) (Workspace UI), [`apps/api/src/db/schema`](https://github.com/fixn222/qube/tree/main/apps/api/src/db/schema) (Qube metadata), [`packages/qube-js/src/client.ts`](https://github.com/fixn222/qube/blob/main/packages/qube-js/src/client.ts) (Qube client), [`apps/api/src/real-time`](https://github.com/fixn222/qube/tree/main/apps/api/src/real-time) (Realtime streams)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Dashboard"]
  node_dashboard_ui["Workspace UI"]
end

subgraph group_api["API services"]
  node_org_members["Organizations and members"]
  node_auth["Authentication"]
  node_projects["Project provisioning"]
  node_schema["Schema workspace"]
  node_table_editor["Table editor"]
  node_sql["SQL editor"]
  node_project_rest["Generated REST"]
  node_realtime["Realtime streams"]
  node_storage["Project storage<br/>[storage.service.ts]"]
  node_analytics["Analytics"]
end

subgraph group_data["Data and events"]
  node_metadata[("Qube metadata")]
  node_postgres[("Project PostgreSQL")]
end

subgraph group_sdk["JavaScript SDK"]
  node_sdk_client["Qube client<br/>[client.ts]"]
  node_sdk_db["Database query builder<br/>[query-builder.ts]"]
  node_sdk_realtime["Realtime SDK<br/>[index.ts]"]
  node_sdk_storage["Storage SDK<br/>[index.ts]"]
end

node_user(("User"))
node_uploadthing["UploadThing"]

node_user -->|"uses workspace"| node_dashboard_ui
node_dashboard_ui -->|"authenticates via"| node_auth
node_dashboard_ui -->|"manages access"| node_org_members
node_dashboard_ui -->|"creates projects"| node_projects
node_dashboard_ui -->|"inspects schema"| node_schema
node_dashboard_ui -->|"edits tables"| node_table_editor
node_dashboard_ui -->|"runs SQL"| node_sql
node_dashboard_ui -->|"explores endpoints"| node_project_rest
node_dashboard_ui -->|"configures streams"| node_realtime
node_dashboard_ui -->|"manages files"| node_storage
node_dashboard_ui -->|"reviews activity"| node_analytics
node_dashboard_ui -.->|"views project data"| node_postgres
node_auth -.->|"stores accounts"| node_metadata
node_org_members -.->|"stores membership"| node_metadata
node_projects -.->|"records projects"| node_metadata
node_projects -->|"provisions schema"| node_postgres
node_schema -->|"inspects schema"| node_postgres
node_table_editor -->|"changes tables"| node_postgres
node_sql -->|"executes queries"| node_postgres
node_project_rest -->|"serves table data"| node_postgres
node_realtime -->|"listens for changes"| node_postgres
node_realtime -->|"streams events"| node_user
node_analytics -.->|"records telemetry"| node_metadata
node_storage -->|"stores object records"| node_metadata
node_storage -->|"delegates uploads"| node_uploadthing
node_user -->|"uses client"| node_sdk_client
node_sdk_client -->|"provides queries"| node_sdk_db
node_sdk_client -->|"provides realtime"| node_sdk_realtime
node_sdk_client -->|"provides storage"| node_sdk_storage
node_sdk_db -->|"queries endpoints"| node_project_rest
node_sdk_realtime -->|"connects streams"| node_realtime
node_sdk_storage -->|"uses storage API"| node_storage

click node_dashboard_ui "https://github.com/fixn222/qube/tree/main/apps/web/src/app"
click node_org_members "https://github.com/fixn222/qube/tree/main/apps/api/src/orgs"
click node_auth "https://github.com/fixn222/qube/tree/main/apps/api/src/auth"
click node_projects "https://github.com/fixn222/qube/blob/main/apps/api/src/projects/create-projects.service.ts"
click node_schema "https://github.com/fixn222/qube/tree/main/apps/api/src/schema-introspection"
click node_table_editor "https://github.com/fixn222/qube/blob/main/apps/api/src/table-editor/table-editor.service.ts"
click node_sql "https://github.com/fixn222/qube/tree/main/apps/api/src/sql-editor"
click node_project_rest "https://github.com/fixn222/qube/blob/main/apps/api/src/project-api/project-api.service.ts"
click node_realtime "https://github.com/fixn222/qube/tree/main/apps/api/src/real-time"
click node_storage "https://github.com/fixn222/qube/blob/main/apps/api/src/storage/storage.service.ts"
click node_analytics "https://github.com/fixn222/qube/blob/main/apps/api/src/analytics/analytics.service.ts"
click node_metadata "https://github.com/fixn222/qube/tree/main/apps/api/src/db/schema"
click node_sdk_client "https://github.com/fixn222/qube/blob/main/packages/qube-js/src/client.ts"
click node_sdk_db "https://github.com/fixn222/qube/blob/main/packages/qube-js/src/db/query-builder.ts"
click node_sdk_realtime "https://github.com/fixn222/qube/blob/main/packages/qube-js/src/realtime/index.ts"
click node_sdk_storage "https://github.com/fixn222/qube/blob/main/packages/qube-js/src/storage/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_dashboard_ui,node_user toneBlue
class node_org_members,node_auth,node_projects,node_schema,node_table_editor,node_sql,node_project_rest,node_realtime,node_storage,node_analytics toneAmber
class node_metadata,node_postgres toneMint
class node_sdk_client,node_sdk_db,node_sdk_realtime,node_sdk_storage toneRose
class node_uploadthing toneIndigo
```

## Components

### Dashboard

- [Workspace UI](https://github.com/fixn222/qube/tree/main/apps/web/src/app): `apps/web/src/app`

### API services

- [Organizations and members](https://github.com/fixn222/qube/tree/main/apps/api/src/orgs): `apps/api/src/orgs`
- [Authentication](https://github.com/fixn222/qube/tree/main/apps/api/src/auth): `apps/api/src/auth`
- [Project provisioning](https://github.com/fixn222/qube/blob/main/apps/api/src/projects/create-projects.service.ts): `apps/api/src/projects/create-projects.service.ts`
- [Schema workspace](https://github.com/fixn222/qube/tree/main/apps/api/src/schema-introspection): `apps/api/src/schema-introspection`
- [Table editor](https://github.com/fixn222/qube/blob/main/apps/api/src/table-editor/table-editor.service.ts): `apps/api/src/table-editor/table-editor.service.ts`
- [SQL editor](https://github.com/fixn222/qube/tree/main/apps/api/src/sql-editor): `apps/api/src/sql-editor`
- [Generated REST](https://github.com/fixn222/qube/blob/main/apps/api/src/project-api/project-api.service.ts): `apps/api/src/project-api/project-api.service.ts`
- [Realtime streams](https://github.com/fixn222/qube/tree/main/apps/api/src/real-time): `apps/api/src/real-time`
- [Project storage](https://github.com/fixn222/qube/blob/main/apps/api/src/storage/storage.service.ts): `apps/api/src/storage/storage.service.ts`
- [Analytics](https://github.com/fixn222/qube/blob/main/apps/api/src/analytics/analytics.service.ts): `apps/api/src/analytics/analytics.service.ts`

### Data and events

- [Qube metadata](https://github.com/fixn222/qube/tree/main/apps/api/src/db/schema): `apps/api/src/db/schema`
- **Project PostgreSQL**

### JavaScript SDK

- [Qube client](https://github.com/fixn222/qube/blob/main/packages/qube-js/src/client.ts): `packages/qube-js/src/client.ts`
- [Database query builder](https://github.com/fixn222/qube/blob/main/packages/qube-js/src/db/query-builder.ts): `packages/qube-js/src/db/query-builder.ts`
- [Realtime SDK](https://github.com/fixn222/qube/blob/main/packages/qube-js/src/realtime/index.ts): `packages/qube-js/src/realtime/index.ts`
- [Storage SDK](https://github.com/fixn222/qube/blob/main/packages/qube-js/src/storage/index.ts): `packages/qube-js/src/storage/index.ts`

### Other components

- **User**
- **UploadThing**

## Connections

- User → Workspace UI: uses workspace
- Workspace UI → Authentication: authenticates via
- Workspace UI → Organizations and members: manages access
- Workspace UI → Project provisioning: creates projects
- Workspace UI → Schema workspace: inspects schema
- Workspace UI → Table editor: edits tables
- Workspace UI → SQL editor: runs SQL
- Workspace UI → Generated REST: explores endpoints
- Workspace UI → Realtime streams: configures streams
- Workspace UI → Project storage: manages files
- Workspace UI → Analytics: reviews activity
- Workspace UI → Project PostgreSQL: views project data
- Authentication → Qube metadata: stores accounts (evidence: `apps/api/src/auth/guards/orgRole.guard.ts`)
- Organizations and members → Qube metadata: stores membership
- Project provisioning → Qube metadata: records projects
- Project provisioning → Project PostgreSQL: provisions schema
- Schema workspace → Project PostgreSQL: inspects schema
- Table editor → Project PostgreSQL: changes tables
- SQL editor → Project PostgreSQL: executes queries
- Generated REST → Project PostgreSQL: serves table data
- Realtime streams → Project PostgreSQL: listens for changes
- Realtime streams → User: streams events
- Analytics → Qube metadata: records telemetry
- Project storage → Qube metadata: stores object records (evidence: `apps/api/src/storage/storage.service.ts`)
- Project storage → UploadThing: delegates uploads
- User → Qube client: uses client
- Qube client → Database query builder: provides queries (evidence: `packages/qube-js/src/client.ts`)
- Qube client → Realtime SDK: provides realtime (evidence: `packages/qube-js/src/client.ts`)
- Qube client → Storage SDK: provides storage (evidence: `packages/qube-js/src/client.ts`)
- Database query builder → Generated REST: queries endpoints
- Realtime SDK → Realtime streams: connects streams
- Storage SDK → Project storage: uses storage API