Clinic queue

apps/api/src/app.ts

@@ -12,6 +12,7 @@ import { authRoutes } from './modules/auth/auth.controller';
 import { clinicOnboardingRoutes } from './modules/clinics/onboarding.controller';
 import { clinicSettingsRoutes } from './modules/clinics/settings.controller';
 import { paymentRoutes } from './modules/payments/payments.controller';
+import { queueRoutes } from './modules/queue/queue.controller';
 import { userRoutes } from './modules/users/users.controller';
 import { notesRoutes } from './modules/notes/notes.controller';
 import { vitalsRoutes } from './modules/vitals/vitals.controller';
@@ -28,6 +29,7 @@ app.use('/api/v1/clinics', clinicOnboardingRoutes);
 app.use('/api/v1/clinics', clinicSettingsRoutes);
 app.use('/api/v1/users', userRoutes);
 app.use('/api/v1/payments', paymentRoutes);
+app.use('/api/v1/queue', queueRoutes);
 app.use('/api/v1/patients', patientRoutes);
 app.use('/api/v1/vitals', vitalsRoutes);
 app.use('/api/v1/encounters', encounterRoutes);

apps/api/src/modules/queue/models/queue-encounter.model.ts

@@ -0,0 +1,63 @@
+import { Schema, model, models } from "mongoose";
+
+export type QueueStatus = "WAITING" | "TRIAGE" | "CONSULTATION";
+export type EncounterStatus = "OPEN" | "IN_PROGRESS" | "CLOSED";
+
+export interface QueueEncounterDocument {
+  clinicId: string;
+  patientName: string;
+  systemId: string;
+  queueStatus: QueueStatus;
+  encounterStatus: EncounterStatus;
+  openedAt: Date;
+}
+
+const queueEncounterSchema = new Schema<QueueEncounterDocument>(
+  {
+    clinicId: {
+      type: String,
+      required: true,
+      trim: true,
+      index: true,
+    },
+    patientName: {
+      type: String,
+      required: true,
+      trim: true,
+    },
+    systemId: {
+      type: String,
+      required: true,
+      trim: true,
+      index: true,
+    },
+    queueStatus: {
+      type: String,
+      enum: ["WAITING", "TRIAGE", "CONSULTATION"],
+      required: true,
+      index: true,
+    },
+    encounterStatus: {
+      type: String,
+      enum: ["OPEN", "IN_PROGRESS", "CLOSED"],
+      required: true,
+      default: "OPEN",
+      index: true,
+    },
+    openedAt: {
+      type: Date,
+      required: true,
+      default: () => new Date(),
+      index: true,
+    },
+  },
+  {
+    timestamps: true,
+    versionKey: false,
+  },
+);
+
+queueEncounterSchema.index({ clinicId: 1, openedAt: -1 });
+
+export const QueueEncounterModel =
+  models.QueueEncounter || model<QueueEncounterDocument>("QueueEncounter", queueEncounterSchema);

apps/api/src/modules/queue/queue.controller.ts

@@ -0,0 +1,210 @@
+import { Request, Response, Router } from "express";
+import { authorize, Roles } from "../../middlewares/rbac.middleware";
+import { validateRequest } from "../../middlewares/validate.middleware";
+import { verifyAccessToken } from "../auth/token.service";
+import { emitQueueUpdate, subscribeQueueUpdates } from "./queue.events";
+import { QueueEncounterModel } from "./models/queue-encounter.model";
+import {
+  QueueStreamQueryDto,
+  RouteQueueEncounterBodyDto,
+  RouteQueueEncounterParamsDto,
+  queueStreamQuerySchema,
+  routeQueueEncounterBodySchema,
+  routeQueueEncounterParamsSchema,
+} from "./queue.validation";
+
+const router = Router();
+const ALL_ROLES: Roles[] = Object.values(Roles);
+
+type RouteQueueEncounterRequest = Request<
+  RouteQueueEncounterParamsDto,
+  unknown,
+  RouteQueueEncounterBodyDto
+>;
+type QueueStreamRequest = Request<Record<string, string>, unknown, unknown, QueueStreamQueryDto>;
+
+const startOfDay = (date: Date) => {
+  const result = new Date(date);
+  result.setHours(0, 0, 0, 0);
+  return result;
+};
+
+const endOfDay = (date: Date) => {
+  const result = new Date(date);
+  result.setHours(23, 59, 59, 999);
+  return result;
+};
+
+const buildMockQueueRows = (clinicId: string) => {
+  const now = Date.now();
+  return [
+    {
+      clinicId,
+      patientName: "Amina Kato",
+      systemId: "LMN-2041",
+      queueStatus: "WAITING" as const,
+      encounterStatus: "OPEN" as const,
+      openedAt: new Date(now - 22 * 60_000),
+    },
+    {
+      clinicId,
+      patientName: "John Okello",
+      systemId: "LMN-2042",
+      queueStatus: "WAITING" as const,
+      encounterStatus: "OPEN" as const,
+      openedAt: new Date(now - 14 * 60_000),
+    },
+    {
+      clinicId,
+      patientName: "Sarah Ninsiima",
+      systemId: "LMN-2043",
+      queueStatus: "TRIAGE" as const,
+      encounterStatus: "IN_PROGRESS" as const,
+      openedAt: new Date(now - 9 * 60_000),
+    },
+    {
+      clinicId,
+      patientName: "David Mugisha",
+      systemId: "LMN-2044",
+      queueStatus: "CONSULTATION" as const,
+      encounterStatus: "IN_PROGRESS" as const,
+      openedAt: new Date(now - 31 * 60_000),
+    },
+    {
+      clinicId,
+      patientName: "Mercy Atwine",
+      systemId: "LMN-2045",
+      queueStatus: "TRIAGE" as const,
+      encounterStatus: "IN_PROGRESS" as const,
+      openedAt: new Date(now - 5 * 60_000),
+    },
+  ];
+};
+
+const ensureQueueSeed = async (clinicId: string) => {
+  const todayStart = startOfDay(new Date());
+  const todayEnd = endOfDay(new Date());
+
+  const existingCount = await QueueEncounterModel.countDocuments({
+    clinicId,
+    openedAt: { $gte: todayStart, $lte: todayEnd },
+    encounterStatus: { $in: ["OPEN", "IN_PROGRESS"] },
+  });
+
+  if (existingCount > 0) {
+    return;
+  }
+
+  await QueueEncounterModel.insertMany(buildMockQueueRows(clinicId));
+};
+
+const toPayload = (doc: {
+  _id: unknown;
+  patientName: string;
+  systemId: string;
+  queueStatus: "WAITING" | "TRIAGE" | "CONSULTATION";
+  encounterStatus: "OPEN" | "IN_PROGRESS" | "CLOSED";
+  openedAt: Date;
+}) => ({
+  id: String(doc._id),
+  patientName: doc.patientName,
+  systemId: doc.systemId,
+  queueStatus: doc.queueStatus,
+  encounterStatus: doc.encounterStatus,
+  openedAt: doc.openedAt.toISOString(),
+  waitMinutes: Math.max(0, Math.floor((Date.now() - doc.openedAt.getTime()) / 60_000)),
+});
+
+router.get("/today", authorize(ALL_ROLES), async (req: Request, res: Response) => {
+  const clinicId = req.user?.clinicId;
+  if (!clinicId) {
+    return res.status(401).json({
+      error: "Unauthorized",
+      message: "Authentication required",
+    });
+  }
+
+  await ensureQueueSeed(clinicId);
+
+  const todayStart = startOfDay(new Date());
+  const todayEnd = endOfDay(new Date());
+
+  const rows = await QueueEncounterModel.find({
+    clinicId,
+    openedAt: { $gte: todayStart, $lte: todayEnd },
+    encounterStatus: { $in: ["OPEN", "IN_PROGRESS"] },
+  })
+    .sort({ openedAt: 1 })
+    .lean();
+
+  return res.json({
+    status: "success",
+    data: rows.map((row) => toPayload(row as Parameters<typeof toPayload>[0])),
+  });
+});
+
+router.get(
+  "/stream",
+  validateRequest({ query: queueStreamQuerySchema }),
+  async (req: QueueStreamRequest, res: Response) => {
+    const user = verifyAccessToken(req.query.token);
+    if (!user) {
+      return res.status(401).json({
+        error: "Unauthorized",
+        message: "Invalid or expired token",
+      });
+    }
+
+    res.setHeader("Content-Type", "text/event-stream");
+    res.setHeader("Cache-Control", "no-cache, no-transform");
+    res.setHeader("Connection", "keep-alive");
+    res.flushHeaders?.();
+
+    res.write(`event: connected\ndata: ${JSON.stringify({ ok: true })}\n\n`);
+
+    subscribeQueueUpdates(user.clinicId, res);
+  },
+);
+
+router.patch(
+  "/:id/route",
+  authorize(ALL_ROLES),
+  validateRequest({ params: routeQueueEncounterParamsSchema, body: routeQueueEncounterBodySchema }),
+  async (req: RouteQueueEncounterRequest, res: Response) => {
+    const clinicId = req.user?.clinicId;
+    if (!clinicId) {
+      return res.status(401).json({
+        error: "Unauthorized",
+        message: "Authentication required",
+      });
+    }
+
+    const updated = await QueueEncounterModel.findOneAndUpdate(
+      { _id: req.params.id, clinicId, encounterStatus: { $in: ["OPEN", "IN_PROGRESS"] } },
+      {
+        $set: {
+          queueStatus: req.body.queueStatus,
+          encounterStatus: req.body.queueStatus === "CONSULTATION" ? "IN_PROGRESS" : "OPEN",
+        },
+      },
+      { new: true },
+    ).lean();
+
+    if (!updated) {
+      return res.status(404).json({
+        error: "NotFound",
+        message: "Queue item not found",
+      });
+    }
+
+    const payload = toPayload(updated as Parameters<typeof toPayload>[0]);
+    emitQueueUpdate(clinicId, { type: "queue.updated", item: payload });
+
+    return res.json({
+      status: "success",
+      data: payload,
+    });
+  },
+);
+
+export const queueRoutes = router;

apps/api/src/modules/queue/queue.events.ts

@@ -0,0 +1,52 @@
+import { Response } from "express";
+
+const subscribersByClinic = new Map<string, Set<Response>>();
+
+export const subscribeQueueUpdates = (clinicId: string, res: Response) => {
+  const clinicSubscribers = subscribersByClinic.get(clinicId) ?? new Set<Response>();
+  clinicSubscribers.add(res);
+  subscribersByClinic.set(clinicId, clinicSubscribers);
+
+  const heartbeat = setInterval(() => {
+    if (!res.writableEnded) {
+      res.write(`event: heartbeat\ndata: ${JSON.stringify({ ok: true })}\n\n`);
+    }
+  }, 15_000);
+
+  const cleanup = () => {
+    clearInterval(heartbeat);
+
+    const current = subscribersByClinic.get(clinicId);
+    if (!current) return;
+
+    current.delete(res);
+    if (current.size === 0) {
+      subscribersByClinic.delete(clinicId);
+    }
+  };
+
+  res.on("close", cleanup);
+  res.on("finish", cleanup);
+};
+
+export const emitQueueUpdate = (clinicId: string, payload: unknown) => {
+  const clinicSubscribers = subscribersByClinic.get(clinicId);
+  if (!clinicSubscribers || clinicSubscribers.size === 0) {
+    return;
+  }
+
+  const data = `event: queue.update\ndata: ${JSON.stringify(payload)}\n\n`;
+
+  clinicSubscribers.forEach((res) => {
+    if (res.writableEnded) {
+      clinicSubscribers.delete(res);
+      return;
+    }
+
+    res.write(data);
+  });
+
+  if (clinicSubscribers.size === 0) {
+    subscribersByClinic.delete(clinicId);
+  }
+};

apps/api/src/modules/queue/queue.validation.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+
+export const routeQueueEncounterParamsSchema = z.object({
+  id: z.string().regex(/^[0-9a-fA-F]{24}$/, "Queue encounter id must be a valid ObjectId"),
+});
+
+export const routeQueueEncounterBodySchema = z.object({
+  queueStatus: z.enum(["WAITING", "TRIAGE", "CONSULTATION"]),
+});
+
+export const queueStreamQuerySchema = z.object({
+  token: z.string().min(1, "token is required"),
+});
+
+export type RouteQueueEncounterParamsDto = z.infer<typeof routeQueueEncounterParamsSchema>;
+export type RouteQueueEncounterBodyDto = z.infer<typeof routeQueueEncounterBodySchema>;
+export type QueueStreamQueryDto = z.infer<typeof queueStreamQuerySchema>;