103 lines
3.2 KiB
Markdown
103 lines
3.2 KiB
Markdown
# Architecture
|
|
|
|
## Goals
|
|
|
|
- Production-oriented structure instead of a demo-only MVP
|
|
- Strict backend authorization for every data/schema action
|
|
- Safe SQL execution with explicit policy checks
|
|
- Clean separation between UI, API, and persistence concerns
|
|
- Deployable through Docker Compose and extensible toward Kubernetes
|
|
|
|
## High-level design
|
|
|
|
### Backend
|
|
|
|
Layered Node.js/Express application:
|
|
|
|
- `routes` expose HTTP endpoints
|
|
- `controllers` translate HTTP into service calls
|
|
- `services` contain business logic and authorization-aware workflows
|
|
- `repositories` talk to PostgreSQL metadata/business tables
|
|
- `middleware` handles auth, sessions, RBAC context, validation, errors
|
|
- `db` contains application pool and SQL bootstrap migrations
|
|
|
|
Two PostgreSQL access modes are used:
|
|
|
|
1. Application database access for auth, RBAC, audit, and metadata.
|
|
2. Controlled administrative SQL access for schema/data operations against managed tables.
|
|
|
|
### Frontend
|
|
|
|
SPA with modular vanilla JavaScript:
|
|
|
|
- `pages` assemble route-level screens
|
|
- `components` provide reusable UI blocks
|
|
- `api` isolates HTTP communication
|
|
- `styles` keeps tokens/layout/components separated
|
|
|
|
This keeps the UI light while preserving clean boundaries. It can later be migrated to React/Vue without backend changes.
|
|
|
|
## Request flow
|
|
|
|
1. Session-authenticated user calls API.
|
|
2. Auth middleware loads session user.
|
|
3. Permission middleware resolves table group and required action.
|
|
4. Service validates identifiers and allowed SQL patterns.
|
|
5. Repository or admin-query utility executes parameterized SQL.
|
|
6. Audit service stores action metadata and outcome.
|
|
7. Structured response is returned to frontend.
|
|
|
|
## RBAC model
|
|
|
|
Core entities:
|
|
|
|
- `users`
|
|
- `roles`
|
|
- `permissions`
|
|
- `role_permissions`
|
|
- `user_roles`
|
|
- `table_groups`
|
|
- `table_group_tables`
|
|
|
|
Permission key shape:
|
|
|
|
- resource: `group`, `table`, `sql_console`, `logs`, `users`, `roles`, `audit`
|
|
- action: `read`, `write`, `delete`, `schema`, `execute`
|
|
|
|
Built-in model:
|
|
|
|
- `root`: unrestricted
|
|
- `group_admin`: scoped by assigned table groups, can manage schema/data per granted actions
|
|
- `viewer` / `editor`: least-privilege table access
|
|
|
|
## Security model
|
|
|
|
- `express-session` with secure cookie settings
|
|
- password hashing with `bcrypt`
|
|
- `helmet`, CORS allowlist, request size limits
|
|
- `zod` validation for request payloads
|
|
- identifier allowlisting and quoting for schema/table/column names
|
|
- parameterized queries for data paths
|
|
- SQL console denylist for dangerous statements and optional read-only mode by role
|
|
- audit log for auth, SQL, DML, DDL
|
|
- rate limiting for auth and console routes
|
|
|
|
## Scalability
|
|
|
|
- Stateless API except for shared session store abstraction
|
|
- Service/repository boundaries allow splitting modules later
|
|
- Docker-ready and twelve-factor env configuration
|
|
- Easy switch from in-memory session store to Redis/Postgres-backed store
|
|
- API can be horizontally scaled behind a reverse proxy
|
|
|
|
## Production improvements to add next
|
|
|
|
- Redis session store
|
|
- background jobs for heavy exports/imports
|
|
- row-level policies / policy engine
|
|
- WebSocket query progress / tailing logs
|
|
- metrics (`/metrics`) with Prometheus
|
|
- OpenTelemetry tracing
|
|
- optimistic UI with saved query tabs
|
|
- soft approvals for risky DDL actions
|