How mahendranmahendran/dbaas-ui-v2 works
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).