# 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
```