eshmeshek
801d0cce5f
Phase 1: Test/Prod Database Configurations - Migration 010: test_* columns on databases table, environment column on request_logs - DatabasePoolManager: dual-pool strategy (prod + test), getPool(id, env) with fallback - SqlExecutor, ScriptExecutor, IsolatedScriptExecutor, AqlExecutor: environment param threaded through all execution paths - dynamicApiController: X-Environment header detection, environment in logging - databaseManagementController: CRUD for test credentials, testConnection with ?env=test - Frontend: test env form in DatabaseModal, env toggle in EndpointEditor test panel Phase 2: Endpoint Versioning - Migration 011: endpoint_versions table with full snapshots, backfill v1 for existing endpoints - VersionService: createVersion, saveDraft, publishVersion, rollbackToVersion, getHistory - endpointController: auto-versioning on update, 6 new version management handlers - dynamicApiController: draft serving when environment=test and draft exists - Frontend: Save Draft button, version history panel with publish/rollback actions Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
73 lines
2.9 KiB
Markdown
73 lines
2.9 KiB
Markdown
# KIS API Builder
|
|
|
|
Dynamic API construction system for KIS/PMU/CR_PPAK databases. Allows creating HTTP endpoints (SQL queries, JS/Python scripts, AQL HTTP calls) via web UI, serving them at `/api/v1/*`, and syncing via CLI (`kisync`).
|
|
|
|
## Stack
|
|
|
|
- **Backend:** Node.js, Express 4.18, TypeScript, PostgreSQL (metadata store), PM2
|
|
- **Frontend:** React 18, TypeScript, Vite 5, Tailwind CSS, Zustand, Monaco Editor
|
|
- **CLI (`kisync`):** TypeScript, Commander.js, Node-Fetch
|
|
- **Target DBs:** PostgreSQL, MySQL, MSSQL, AQL (custom HTTP API)
|
|
|
|
## Project structure
|
|
|
|
```
|
|
backend/ # Express API server
|
|
src/
|
|
config/ # database.ts, environment.ts, dynamicSwagger.ts
|
|
controllers/ # endpointController, dynamicApiController, syncController
|
|
middleware/ # auth.ts (JWT), apiKey.ts
|
|
migrations/ # 001-009 sequential SQL migrations
|
|
routes/ # REST + dynamic wildcard router
|
|
services/ # SqlExecutor, ScriptExecutor, IsolatedScriptExecutor, AqlExecutor, DatabasePoolManager
|
|
types/ # index.ts — all interfaces
|
|
frontend/ # React SPA
|
|
src/
|
|
pages/ # Endpoints, Folders, ApiKeys, DatabaseManagement, SqlWorkbench
|
|
components/ # Reusable UI components
|
|
services/ # api.ts (Axios client)
|
|
stores/ # Zustand stores (auth, endpoints, etc.)
|
|
cli/ # kisync CLI tool
|
|
src/
|
|
commands/ # init, pull, push, status, update
|
|
api.ts # HTTP client to backend
|
|
files.ts # Endpoint ↔ filesystem serialization
|
|
hash.ts # SHA256 change detection
|
|
```
|
|
|
|
## Key concepts
|
|
|
|
- **Endpoint execution types:** `sql` (direct query), `script` (JS in VM / Python subprocess), `aql` (HTTP proxy)
|
|
- **Dynamic routing:** `router.all('*')` at `/api/v1/` matches endpoints by path + method from DB
|
|
- **Auth:** JWT for web UI, API keys (`X-API-Key` header) for external consumers
|
|
- **Permissions:** endpoint-level or folder-level (`folder:<id>`), with parent chain traversal
|
|
- **CLI sync:** hash-based change detection, conflict resolution via `_base_updated_at`
|
|
- **Query safety:** DDL/DML blocklist (DROP, TRUNCATE, ALTER, CREATE, DELETE FROM), single-statement only
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
npm run dev # concurrently backend (nodemon) + frontend (vite)
|
|
npm run build # tsc + vite build
|
|
npm run migrate # run SQL migrations
|
|
npm run start:prod # PM2 production (port 10805)
|
|
```
|
|
|
|
## Production
|
|
|
|
- PM2 fork mode, port 10805, max 500MB RAM
|
|
- Frontend served as static files from `frontend/dist`
|
|
- SPA fallback for non-API routes
|
|
|
|
## Pipeline (agent workflow)
|
|
|
|
```
|
|
analyst -> spec.md
|
|
planner -> plan.md (reads spec)
|
|
developer -> code + testing-instructions.md (reads spec + plan)
|
|
tester-ui -> testing results (replay-loop with developer on FAIL)
|
|
code-reviewer -> review.md (APPROVE | REQUEST_CHANGES | BLOCK)
|
|
deployer -> deployment record (pre-step: safety-reviewer)
|
|
tech-writer -> updates docs + CLAUDE.md
|
|
```
|