# mahendranmahendran/dbaas-ui-v2 architecture

> Architecture diagram of the GitHub repository mahendranmahendran/dbaas-ui-v2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mahendranmahendran/dbaas-ui-v2
- Repository: https://github.com/mahendranmahendran/dbaas-ui-v2

## Overview

##### Project Type & Purpose
- This is a single-page application (SPA) built with React and Vite.
- Its primary purpose is to demonstrate/test ClickHouse Role-Based Access Control (RBAC) in a browser-based UI.
- The “backend” in this case is the ClickHouse database itself, configured with multiple test users and roles via the provided scripts and config files.

##### File Structure
Top-level items:
- config/… – ClickHouse server XML configs (CORS, users)
- docker-compose.yml – Spins up a ClickHouse server for local/dev.
- scripts/… – Shell scripts to initialize ClickHouse RBAC (users / roles).
- src/… – React application code:
– pages/… – Route-level pages (Landing, Monitoring, SQLPlayground, Billing, Settings, Admin, Auth, Error)
– components/… – Reusable UI widgets (AuthWrapper, NavMenu, ErrorBoundary, ThemeToggler)
– rbac/… – RBAC logic, contexts, utilities, SQL setup
– utils/… – ClickHouse API wrappers, custom hooks (useAuth, useRBAC, etc.)
- public/, index.html, package.json, vite.config.js – Standard Vite/React scaffold.

##### README for Additional Insights
- Spells out how to run ClickHouse in Docker, set env vars, run scripts.
- Lists test users and their roles, and how to log in via the UI to verify access.
- No separate auth service – the app uses ClickHouse HTTP interface and credentials for login.

a. Main Components
1. Client Browser
– Loads index.html + bundled JS/CSS (served by Vite dev server or static host).
– Runs the React SPA.
2. React SPA
– Routing & Pages (Landing, Auth, SQL Playground, Monitoring, etc.)
– RBAC Layer (Context, Hooks, wrappers)
– API Layer (utils/clickhouse-browser.js)
3. Vite Development Server (or Static File Host in prod)
4. ClickHouse DB Server
– HTTP interface on port 8123 (CORS enabled via config).
– Native interface on port 9000 (if used).
– User/role definitions loaded from config and setup scripts.
5. Initialization Scripts & Docker Compose
– Scripts/setup-clickhouse-rbac.sh invoked by docker-compose to bootstrap roles.

b. Relationships & Interactions
– User enters credentials in React Auth page → calls API layer
→ HTTP request to ClickHouse HTTP endpoint → ClickHouse authenticates & enforces RBAC → returns query results or metadata.
– React RBAC Context consumes user’s role and exposes allowed pages/components via wrappers (AuthWrapper, RBACWrapper).
– Monitoring and SQL Playground pages issue read or write queries through the API layer.
– Admin pages issue management queries (e.g., user management, system settings).
– Scripts run once at container startup to populate roles/users in ClickHouse.

c. Architectural Patterns & Principles
– SPA pattern with client-side routing.
– Component-based UI (atomic components, page shells).
– Context + Hooks for cross-cutting concerns (authentication, RBAC).
– Separation of concerns: UI vs. Data-access vs. DB configuration.
– Infrastructure as code: Docker compose + shell scripts for reproducible setup.

d. Key Technologies & Frameworks
– React 18 + Vite (fast HMR, ES modules).
– Tailwind CSS (via postcss/tailwind.config.js).
– ESLint for code quality, Prettier optional.
– ClickHouse database (HTTP interface, custom RBAC).
– Shell scripts for DB setup; Docker Compose for orchestration.

##### Essential Details, Avoid Overcomplexity
- Call out key backend configs: config/clickhouse/users.xml, cors.xml.
- That roles are inherited hierarchically.
- Don’t attempt to model every single React component—group them by layer (Pages, Components, Hooks).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Client["Client Browser"]:::ui
    Client -->|"GET index.html"| ViteDev["Vite Dev Server"]:::infra
    ViteDev -->|"Serves index.html & JS/CSS"| Client
    ViteDev -->|"Serves Bundles"| ReactSPA

    click Client "https://github.com/mahendranmahendran/dbaas-ui-v2/blob/main/public/index.html"
    click ViteDev "https://github.com/mahendranmahendran/dbaas-ui-v2/blob/main/vite.config.js"

    %% React SPA Layer
    ReactSPA["React SPA"]:::frontend
    ReactSPA -->|Initializes| Main
    ReactSPA -->|Renders| App
    ReactSPA -->|Loads| Assets
    ReactSPA -->|Uses| Pages
    ReactSPA -->|Uses| Components
    ReactSPA -->|Uses| RBAC_Layer
    ReactSPA -->|Uses| API_Layer
    ReactSPA -->|Uses| Hooks

    subgraph "SPA Structure"
        Main["Entry Point\nsrc/main.jsx"]:::frontend
        App["App & Routing\nsrc/App.jsx"]:::frontend
        Assets["Assets & Styles\nsrc/assets/, src/styles/"]:::frontend
        Pages["Pages\nsrc/pages/"]:::frontend
        Components["UI Components\nsrc/components/"]:::frontend
        RBAC_Layer["RBAC Layer\nsrc/rbac/"]:::logic
        API_Layer["Data Access/API\nsrc/utils/clickhouse-browser.js"]:::data
        Hooks["Custom Hooks\nsrc/utils/hooks/"]:::logic
    end

    click Main "https://github.com/mahendranmahendran/dbaas-ui-v2/blob/main/src/main.jsx"
    click App "https://github.com/mahendranmahendran/dbaas-ui-v2/blob/main/src/App.jsx"
    click Assets "https://github.com/mahendranmahendran/dbaas-ui-v2/tree/main/src/assets/icons/"
    click Assets "https://github.com/mahendranmahendran/dbaas-ui-v2/blob/main/src/styles/index.css"
    click Pages "https://github.com/mahendranmahendran/dbaas-ui-v2/tree/main/src/pages/"
    click Components "https://github.com/mahendranmahendran/dbaas-ui-v2/tree/main/src/components/"
    click RBAC_Layer "https://github.com/mahendranmahendran/dbaas-ui-v2/blob/main/src/rbac/context.jsx"
    click API_Layer "https://github.com/mahendranmahendran/dbaas-ui-v2/blob/main/src/utils/clickhouse-browser.js"
    click Hooks "https://github.com/mahendranmahendran/dbaas-ui-v2/tree/main/src/utils/hooks/"

    %% Data Store Layer
    ReactSPA -->|"HTTP Queries"| CH_HTTP["ClickHouse HTTP API\n(port 8123)"]:::db
    CH_HTTP -->|"Delegates"| CH_DB[(ClickHouse Server)]:::db

    %% Docker & Initialization
    subgraph "Infrastructure Setup"
        Docker["Docker Compose\ndocker-compose.yml"]:::infra
        Scripts["RBAC Init Script\nscripts/setup-clickhouse-rbac.sh"]:::infra
        Configs["ClickHouse Configs\nconfig/clickhouse/"]:::infra
    end

    Docker --> CH_DB
    Docker --> Scripts
    Scripts --> CH_DB
    ClickHouse_CORS["CORS Policy\nconfig/clickhouse/cors.xml"]:::infra
    ClickHouse_Users["User/Role Definitions\nconfig/clickhouse/users.xml"]:::infra
    Configs --> ClickHouse_CORS
    Configs --> ClickHouse_Users

    click Docker "https://github.com/mahendranmahendran/dbaas-ui-v2/blob/main/docker-compose.yml"
    click Scripts "https://github.com/mahendranmahendran/dbaas-ui-v2/blob/main/scripts/setup-clickhouse-rbac.sh"
    click Configs "https://github.com/mahendranmahendran/dbaas-ui-v2/blob/main/config/clickhouse/users.xml"
    click ClickHouse_CORS "https://github.com/mahendranmahendran/dbaas-ui-v2/blob/main/config/clickhouse/cors.xml"
    click ClickHouse_Users "https://github.com/mahendranmahendran/dbaas-ui-v2/blob/main/config/clickhouse/users.xml"

    %% Styles
    classDef ui fill:#D0EBFF,stroke:#339AF0,color:#1C7ED6;
    classDef infra fill:#F8F9FA,stroke:#ADB5BD,color:#495057;
    classDef frontend fill:#E7F5FF,stroke:#74C0FC,color:#1864AB;
    classDef logic fill:#E6FCF5,stroke:#51CF66,color:#2B8A3E;
    classDef data fill:#FFF4E6,stroke:#FFA94D,color:#C05600;
    classDef db fill:#F8F0FC,stroke:#CC5DE8,color:#7950F2;
```
