# OQENS Platform & DBaaS v2 — Master Architecture & API Specification
> Single-source reference for AI coding assistants, agentic workflows, and LLM tooling.

## Infrastructure & Topology
- **Platform Name**: OQENS (Database Cloud Studio & Multi-Tenant Cloud OS)
- **Primary URL**: https://echo.oqens.me
- **DBaaS Studio SPA**: https://db.echo.oqens.me
- **TypeScript SDK**: `@oqens/db` (v1.0.0 on npm registry)
- **SDK Docs**: https://sdk.echo.oqens.me
- **Master Docs**: https://docs.echo.oqens.me
- **Incident Status**: https://status.echo.oqens.me

---

## Compute Topology
- **VM1 (Primary / Gateway)**: 80.225.220.63 (Nginx Gateway, TLS 1.3 termination, PostgreSQL 14 Master, Gunicorn Node 1)
- **VM2 (Secondary / Worker)**: 144.24.123.252 (Private IP: 10.0.0.143, Gunicorn Node 2, Cloud OS Worker)
- **Cluster Load Balancing**: `5:5 least_conn` balancing across VM1 (127.0.0.1:5000) and VM2 (10.0.0.143:80 -> 5001)

---

## Database Isolation & Security
- **Tenant Databases**: Isolated PostgreSQL databases named `db_<slug>_<tenant_id>` with unprivileged users `usr_<slug>_<tenant_id>`
- **Banned SQL Commands**: DROP DATABASE, ALTER SYSTEM, COPY ... TO/FROM PROGRAM, PG_READ_FILE, PG_WRITE_FILE
- **Hard Query Timeout**: 15,000ms (15 seconds)
- **CORS Configuration**: Open CORS (`*`) on all `/api/dbaas/v2/*` endpoints with automated OPTIONS preflight handling

---

## DBaaS v2 REST API Endpoints
- `GET /api/dbaas/v2/tenant/quota` — Tenant database quota, active projects count, and limits
- `GET /api/dbaas/v2/projects` — List tenant database projects
- `POST /api/dbaas/v2/projects` — Create project + provision PostgreSQL DB (`{ name, limit_mb }`)
- `POST /api/dbaas/v2/projects/:slug/query` — Execute SQL (`{ query, limit }`)
- `GET /api/dbaas/v2/projects/:slug/tables` — List all tables with row counts and disk sizes
- `GET /api/dbaas/v2/projects/:slug/tables/:table` — Fetch paginated table rows (`?limit=50&page=1&sort_col=...&sort_dir=...`)
- `POST /api/dbaas/v2/projects/:slug/tables/:table` — Insert row with RETURNING * (`{ col: val }`)
- `DELETE /api/dbaas/v2/projects/:slug/tables/:table/row` — Delete row (`?pk_col=id&pk_val=...`)
- `POST /api/dbaas/v2/projects/:slug/auth/signup` — End-user registration (`{ email, password, data }`)
- `POST /api/dbaas/v2/projects/:slug/auth/signin` — End-user authentication (returns 24-hr access JWT)
- `GET /api/dbaas/v2/projects/:slug/schema` — Full relational schema with foreign key relationships
- `GET /api/dbaas/v2/projects/:slug/storage/overview` — Storage buckets overview & quota usage
- `POST /api/dbaas/v2/projects/:slug/storage/buckets` — Create storage bucket (`{ bucket_name, is_public }`)