feat(api): initialize Fastify API with health check endpoints and testing setup

- Added Fastify server setup with CORS support.
- Implemented health check endpoints (`GET /` and `GET /health`).
- Created test suite using Vitest and Playwright for health check endpoints.
- Included configuration files and README for development instructions.
- Added .gitignore for node-related files.

Author: nchopra

apps/api/.gitignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+.env
+.env.local
+*.log

apps/api/README.md

@@ -0,0 +1,57 @@
+# RefRef API
+
+Fastify API server for RefRef platform.
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run in development mode with hot reload
+pnpm dev
+
+# Run tests
+pnpm test              # Run tests in watch mode
+pnpm test:run          # Run tests once
+pnpm test:ui           # Run tests with UI
+
+# Type checking
+pnpm typecheck
+
+# Build for production
+pnpm build
+
+# Start production server
+pnpm start
+```
+
+## Environment Variables
+
+```bash
+PORT=3001           # Server port (default: 3001)
+HOST=0.0.0.0       # Server host (default: 0.0.0.0)
+LOG_LEVEL=info     # Logging level (default: info)
+NODE_ENV=development
+```
+
+## Testing
+
+The API uses Vitest and Playwright for integration testing. Tests start a real server instance and make HTTP requests to validate responses.
+
+Test structure:
+- `test/utils/testServer.ts` - Test server utilities for starting/stopping the server
+- `test/health.test.ts` - Health endpoint tests
+
+Each test suite:
+1. Starts a test server on a random port
+2. Creates a Playwright API request context
+3. Runs tests against real endpoints
+4. Cleans up resources after tests complete
+
+## Endpoints
+
+- `GET /` - Root health check endpoint
+  - Returns: `{ok: true, service: "refref-api"}`
+- `GET /health` - Health check endpoint
+  - Returns: `{ok: true, service: "refref-api"}`

apps/api/api.http

@@ -0,0 +1,7 @@
+@host = http://localhost:3001
+
+### Health Check - Root
+GET {{host}}/
+
+### Health Check - Health Endpoint
+GET {{host}}/health

apps/api/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@refref/api",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:run": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write ."
+  },
+  "dependencies": {
+    "@fastify/cors": "^10.0.1",
+    "fastify": "^5.2.0",
+    "fastify-plugin": "^5.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@vitest/ui": "^2.1.8",
+    "pino-pretty": "^13.0.0",
+    "playwright": "^1.49.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}

apps/api/src/app.ts

@@ -0,0 +1,33 @@
+import Fastify, { FastifyInstance } from "fastify";
+import cors from "@fastify/cors";
+import { healthHandler } from "./handlers/health.js";
+
+export async function buildApp(): Promise<FastifyInstance> {
+  const app = Fastify({
+    logger: {
+      level: process.env.LOG_LEVEL || "info",
+      transport:
+        process.env.NODE_ENV !== "production"
+          ? {
+              target: "pino-pretty",
+              options: {
+                translateTime: "HH:MM:ss Z",
+                ignore: "pid,hostname",
+                colorize: true,
+              },
+            }
+          : undefined,
+    },
+  });
+
+  // Register CORS plugin
+  await app.register(cors, {
+    origin: true,
+  });
+
+  // Register health check routes
+  app.get("/", healthHandler);
+  app.get("/health", healthHandler);
+
+  return app;
+}

apps/api/src/handlers/health.ts

@@ -0,0 +1,11 @@
+import { FastifyReply, FastifyRequest } from "fastify";
+
+export async function healthHandler(
+  request: FastifyRequest,
+  reply: FastifyReply
+) {
+  return reply.send({
+    ok: true,
+    service: "refref-api",
+  });
+}

apps/api/src/index.ts

@@ -0,0 +1,29 @@
+import { buildApp } from "./app.js";
+
+const start = async () => {
+  try {
+    const app = await buildApp();
+
+    const port = Number(process.env.PORT) || 3001;
+    const host = process.env.HOST || "0.0.0.0";
+
+    await app.listen({ port, host });
+
+    app.log.info(`Server listening on ${host}:${port}`);
+
+    // Graceful shutdown handlers
+    const signals = ["SIGINT", "SIGTERM"] as const;
+    for (const signal of signals) {
+      process.on(signal, async () => {
+        app.log.info(`Received ${signal}, closing server gracefully...`);
+        await app.close();
+        process.exit(0);
+      });
+    }
+  } catch (err) {
+    console.error(err);
+    process.exit(1);
+  }
+};
+
+start();

apps/api/test/health.test.ts

@@ -0,0 +1,90 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { request } from "playwright";
+import { startTestServer, stopTestServer } from "./utils/testServer.js";
+import type { APIRequestContext } from "playwright";
+
+describe("Health Endpoints", () => {
+  let apiContext: APIRequestContext;
+  let baseURL: string;
+
+  beforeAll(async () => {
+    // Start test server
+    const { url } = await startTestServer();
+    baseURL = url;
+
+    // Create Playwright API request context
+    apiContext = await request.newContext({
+      baseURL,
+    });
+  });
+
+  afterAll(async () => {
+    // Clean up
+    await apiContext.dispose();
+    await stopTestServer();
+  });
+
+  describe("GET /health", () => {
+    it("should return ok: true and service name", async () => {
+      const response = await apiContext.get("/health");
+
+      expect(response.ok()).toBe(true);
+      expect(response.status()).toBe(200);
+
+      const body = await response.json();
+
+      expect(body).toEqual({
+        ok: true,
+        service: "refref-api",
+      });
+    });
+
+    it("should have correct content-type header", async () => {
+      const response = await apiContext.get("/health");
+
+      const contentType = response.headers()["content-type"];
+      expect(contentType).toContain("application/json");
+    });
+
+    it("should respond quickly", async () => {
+      const startTime = Date.now();
+      const response = await apiContext.get("/health");
+      const endTime = Date.now();
+
+      expect(response.ok()).toBe(true);
+      expect(endTime - startTime).toBeLessThan(1000); // Should respond within 1 second
+    });
+  });
+
+  describe("GET /", () => {
+    it("should return ok: true and service name", async () => {
+      const response = await apiContext.get("/");
+
+      expect(response.ok()).toBe(true);
+      expect(response.status()).toBe(200);
+
+      const body = await response.json();
+
+      expect(body).toEqual({
+        ok: true,
+        service: "refref-api",
+      });
+    });
+
+    it("should have correct content-type header", async () => {
+      const response = await apiContext.get("/");
+
+      const contentType = response.headers()["content-type"];
+      expect(contentType).toContain("application/json");
+    });
+
+    it("should respond quickly", async () => {
+      const startTime = Date.now();
+      const response = await apiContext.get("/");
+      const endTime = Date.now();
+
+      expect(response.ok()).toBe(true);
+      expect(endTime - startTime).toBeLessThan(1000); // Should respond within 1 second
+    });
+  });
+});

apps/api/test/utils/testServer.ts

@@ -0,0 +1,29 @@
+import { FastifyInstance } from "fastify";
+import { buildApp } from "../../src/app.js";
+
+let testServer: FastifyInstance | null = null;
+
+export async function startTestServer(): Promise<{
+  server: FastifyInstance;
+  url: string;
+}> {
+  if (testServer) {
+    throw new Error("Test server is already running");
+  }
+
+  testServer = await buildApp();
+
+  const port = Math.floor(Math.random() * 10000) + 30000; // Random port between 30000-40000
+  await testServer.listen({ port, host: "127.0.0.1" });
+
+  const url = `http://127.0.0.1:${port}`;
+
+  return { server: testServer, url };
+}
+
+export async function stopTestServer(): Promise<void> {
+  if (testServer) {
+    await testServer.close();
+    testServer = null;
+  }
+}

apps/api/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "lib": ["ES2022"],
+    "moduleResolution": "bundler",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}