123

docs/architecture.md

@@ -0,0 +1,102 @@
+# 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