feat(backend): add isolated v2 foundation stack and query service scaffold

backend/query-api/src/app.js

@@ -0,0 +1,28 @@
+import express from 'express';
+import pino from 'pino';
+import pinoHttp from 'pino-http';
+import { requestContext } from './middleware/request-context.js';
+import { errorHandler, notFoundHandler } from './middleware/error-handler.js';
+import { healthRouter } from './routes/health.js';
+
+const logger = pino({ level: process.env.LOG_LEVEL || 'info' });
+
+export function createApp() {
+  const app = express();
+
+  app.use(requestContext);
+  app.use(
+    pinoHttp({
+      logger,
+      customProps: (req) => ({ requestId: req.requestId }),
+    })
+  );
+  app.use(express.json({ limit: '2mb' }));
+
+  app.use(healthRouter);
+
+  app.use(notFoundHandler);
+  app.use(errorHandler);
+
+  return app;
+}

backend/query-api/src/lib/errors.js

@@ -0,0 +1,26 @@
+export class AppError extends Error {
+  constructor(code, message, status = 400, details = {}) {
+    super(message);
+    this.name = 'AppError';
+    this.code = code;
+    this.status = status;
+    this.details = details;
+  }
+}
+
+export function toErrorEnvelope(error, requestId) {
+  const status = error?.status && Number.isInteger(error.status) ? error.status : 500;
+  const code = error?.code || 'INTERNAL_ERROR';
+  const message = error?.message || 'Unexpected error';
+  const details = error?.details || {};
+
+  return {
+    status,
+    body: {
+      code,
+      message,
+      details,
+      requestId,
+    },
+  };
+}

backend/query-api/src/middleware/error-handler.js

@@ -0,0 +1,25 @@
+import { toErrorEnvelope } from '../lib/errors.js';
+
+export function notFoundHandler(req, res) {
+  res.status(404).json({
+    code: 'NOT_FOUND',
+    message: `Route not found: ${req.method} ${req.path}`,
+    details: {},
+    requestId: req.requestId,
+  });
+}
+
+export function errorHandler(error, req, res, _next) {
+  const envelope = toErrorEnvelope(error, req.requestId);
+  if (req.log) {
+    req.log.error(
+      {
+        errCode: envelope.body.code,
+        status: envelope.status,
+        details: envelope.body.details,
+      },
+      envelope.body.message
+    );
+  }
+  res.status(envelope.status).json(envelope.body);
+}

backend/query-api/src/middleware/request-context.js

@@ -0,0 +1,9 @@
+import { randomUUID } from 'node:crypto';
+
+export function requestContext(req, res, next) {
+  const incoming = req.get('X-Request-Id');
+  req.requestId = incoming || randomUUID();
+  res.setHeader('X-Request-Id', req.requestId);
+  res.locals.startedAt = Date.now();
+  next();
+}

backend/query-api/src/routes/health.js

@@ -0,0 +1,15 @@
+import { Router } from 'express';
+
+export const healthRouter = Router();
+
+function healthHandler(req, res) {
+  res.status(200).json({
+    ok: true,
+    service: 'krow-query-api',
+    version: process.env.SERVICE_VERSION || 'dev',
+    requestId: req.requestId,
+  });
+}
+
+healthRouter.get('/health', healthHandler);
+healthRouter.get('/healthz', healthHandler);

backend/query-api/src/server.js

@@ -0,0 +1,9 @@
+import { createApp } from './app.js';
+
+const port = Number(process.env.PORT || 8080);
+const app = createApp();
+
+app.listen(port, () => {
+  // eslint-disable-next-line no-console
+  console.log(`krow-query-api listening on port ${port}`);
+});