server-setup

Server Setup Specification

Express Server

Single Express app serving three concerns:

1. Static files: serve the Vite-built SPA from dist/client/
2. REST API: prefixed with /api/
3. WebSocket: upgrade at /ws

// src/server/index.ts
import express from "express";
import { createServer } from "http";
import { setupWebSocket } from "./ws";
import { setupRoutes } from "./routes";
import { getClaudeHome } from "./config";

const app = express();
const server = createServer(app);

setupRoutes(app, getClaudeHome());
setupWebSocket(server, getClaudeHome());

// Serve SPA in production
app.use(express.static("dist/client"));
app.get("*", (req, res) => res.sendFile("index.html", { root: "dist/client" }));

const PORT = process.env.PORT || 4117;
server.listen(PORT, () => console.log(`Noctrace running at http://localhost:${PORT}`));

REST API Endpoints

GET /api/projects

Returns list of Claude Code projects.

// Response
interface ProjectListResponse {
  projects: {
    slug: string;         // encoded path (e.g., "-Users-jane-myapp")
    path: string;         // decoded path (e.g., "/Users/jane/myapp")
    sessionCount: number;
    lastModified: string; // ISO-8601
  }[];
}

Implementation: read directory listing of ~/.claude/projects/, decode slugs by replacing - with /, count JSONL files per project, get latest mtime.

GET /api/projects/:slug/sessions

Returns sessions for a project, sorted by most recent.

interface SessionListResponse {
  sessions: {
    id: string;           // session UUID (filename without .jsonl)
    summary: string;      // first user message or auto-summary
    messageCount: number;
    startTime: string;
    endTime: string;
    hasErrors: boolean;
  }[];
}

Implementation: read sessions-index.json if it exists, otherwise parse first/last lines of each JSONL file for timestamps and first user message.

GET /api/sessions/:id

Returns parsed waterfall data for a session.