testpf/docs/architecture.md

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