@access-dlsu/leapify 0.260602.1 → 0.260605.1

package/dist/index.js

@@ -1,6 +1,8 @@
-import { createTurnstileMiddleware, TURNSTILE_VERIFY_PATH, handleTurnstileVerify } from './chunk-WTA2QGY5.js';
+import { createTurnstileMiddleware, TURNSTILE_VERIFY_PATH, handleTurnstileVerify } from './chunk-WEW5LGZC.js';
 import { __export } from './chunk-PZ5AY32C.js';
 import { Hono } from 'hono';
+import { describeRoute, validator, openAPIRouteHandler } from 'hono-openapi';
+import { swaggerUI } from '@hono/swagger-ui';
 import { cors } from 'hono/cors';
 import { drizzle } from 'drizzle-orm/d1';
 import { sqliteTable, integer, text, index, uniqueIndex } from 'drizzle-orm/sqlite-core';
@@ -9,7 +11,6 @@ import { createMiddleware } from 'hono/factory';
 import { betterAuth } from 'better-auth';
 import { drizzleAdapter } from 'better-auth/adapters/drizzle';
 import { bearer } from 'better-auth/plugins';
-import { zValidator } from '@hono/zod-validator';
 import { z } from 'zod';
 
 // src/lib/errors.ts
@@ -578,8 +579,6 @@ var internalMiddleware = createMiddleware(async (c, next) => {
   }
   return next();
 });
-
-// src/routes/health.ts
 var healthRoute = new Hono();
 async function probeResend(apiKey) {
   const start = Date.now();
@@ -681,69 +680,87 @@ async function probeGForms(serviceAccountJson) {
     };
   }
 }
-healthRoute.get("/", async (c) => {
-  const env = c.env;
-  const hasSes = Boolean(env.SES_REGION) && Boolean(env.SES_ACCESS_KEY_ID) && Boolean(env.SES_SECRET_ACCESS_KEY);
-  const hasResend = Boolean(env.RESEND_API_KEY);
-  let hasGForms = false;
-  if (env.GFORMS_SERVICE_ACCOUNT_JSON) {
-    try {
-      const parsed = JSON.parse(env.GFORMS_SERVICE_ACCOUNT_JSON);
-      hasGForms = Boolean(parsed.client_email && parsed.private_key);
-    } catch {
+healthRoute.get(
+  "/",
+  describeRoute({
+    tags: ["Health"],
+    summary: "Service health check",
+    responses: { 200: { description: "Health status of configured services" } }
+  }),
+  async (c) => {
+    const env = c.env;
+    const hasSes = Boolean(env.SES_REGION) && Boolean(env.SES_ACCESS_KEY_ID) && Boolean(env.SES_SECRET_ACCESS_KEY);
+    const hasResend = Boolean(env.RESEND_API_KEY);
+    let hasGForms = false;
+    if (env.GFORMS_SERVICE_ACCOUNT_JSON) {
+      try {
+        const parsed = JSON.parse(env.GFORMS_SERVICE_ACCOUNT_JSON);
+        hasGForms = Boolean(parsed.client_email && parsed.private_key);
+      } catch {
+      }
     }
-  }
-  const probes = [];
-  if (hasSes) {
-    probes.push(
-      probeSes(env.SES_REGION, env.SES_ACCESS_KEY_ID, env.SES_SECRET_ACCESS_KEY).then(
-        (h) => ["ses", h]
-      )
-    );
-  }
-  if (hasResend) {
-    probes.push(
-      probeResend(env.RESEND_API_KEY).then((h) => ["resend", h])
-    );
-  }
-  if (hasGForms) {
-    probes.push(
-      probeGForms(env.GFORMS_SERVICE_ACCOUNT_JSON).then(
-        (h) => ["gforms", h]
-      )
-    );
-  }
-  const results = await Promise.all(probes);
-  const services = {};
-  for (const [name, health] of results) {
-    services[name] = health;
-  }
-  const allOk = results.length === 0 || results.every(([, h]) => h.ok);
-  return c.json({
-    data: {
-      status: allOk ? "OK" : "DEGRADED",
-      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      services
+    const probes = [];
+    if (hasSes) {
+      probes.push(
+        probeSes(env.SES_REGION, env.SES_ACCESS_KEY_ID, env.SES_SECRET_ACCESS_KEY).then(
+          (h) => ["ses", h]
+        )
+      );
     }
-  });
-});
-healthRoute.post("/queue-burst", authMiddleware, adminMiddleware, async (c) => {
-  if (!c.env.EMAIL_QUEUE) {
-    return c.json({ error: "Queue binding missing" }, 400);
-  }
-  const batch = Array.from({ length: 100 }, (_, i) => ({
-    body: {
-      type: "audit_log",
-      payload: {
-        action: "queue_load_test",
-        userId: "system",
-        meta: { index: i, time: Date.now() }
+    if (hasResend) {
+      probes.push(
+        probeResend(env.RESEND_API_KEY).then((h) => ["resend", h])
+      );
+    }
+    if (hasGForms) {
+      probes.push(
+        probeGForms(env.GFORMS_SERVICE_ACCOUNT_JSON).then(
+          (h) => ["gforms", h]
+        )
+      );
+    }
+    const results = await Promise.all(probes);
+    const services = {};
+    for (const [name, health] of results) {
+      services[name] = health;
+    }
+    const allOk = results.length === 0 || results.every(([, h]) => h.ok);
+    return c.json({
+      data: {
+        status: allOk ? "OK" : "DEGRADED",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        services
       }
+    });
+  }
+);
+healthRoute.post(
+  "/queue-burst",
+  describeRoute({
+    tags: ["Health"],
+    summary: "Queue load test (admin)",
+    responses: { 200: { description: "Items queued" } }
+  }),
+  authMiddleware,
+  adminMiddleware,
+  async (c) => {
+    if (!c.env.EMAIL_QUEUE) {
+      return c.json({ error: "Queue binding missing" }, 400);
     }
-  }));
-  await c.env.EMAIL_QUEUE.sendBatch(batch);
-  return c.json({ status: "queued", count: 100 });
-});
+    const batch = Array.from({ length: 100 }, (_, i) => ({
+      body: {
+        type: "audit_log",
+        payload: {
+          action: "queue_load_test",
+          userId: "system",
+          meta: { index: i, time: Date.now() }
+        }
+      }
+    }));
+    await c.env.EMAIL_QUEUE.sendBatch(batch);
+    return c.json({ status: "queued", count: 100 });
+  }
+);
 
 // src/services/cache.ts
 var CacheService = class {
@@ -1116,143 +1133,229 @@ var classesRoute = new Hono();
 function generateSlug(title) {
   return title.toLowerCase().trim().replace(/[^\w\s-]/g, "").replace(/[\s_-]+/g, "-").replace(/^-+|-+$/g, "");
 }
-classesRoute.get("/admin", authMiddleware, adminMiddleware, async (c) => {
-  const db = createDb(c.env.DB);
-  const data = await db.query.events.findMany({
-    with: { theme: true, organization: true },
-    orderBy: (e, { desc }) => [desc(e.createdAt)]
-  });
-  return c.json({ data });
-});
-classesRoute.post("/admin/publish", authMiddleware, adminMiddleware, async (c) => {
-  const body = await c.req.json();
-  const db = createDb(c.env.DB);
-  const cache = new CacheService(c.env.KV);
-  if (!body.ids?.length) {
-    return c.json({ error: "ids are required" }, 400);
-  }
-  if (body.releaseAt) {
-    await db.update(events).set({ releaseAt: body.releaseAt, status: "queued" }).where(
-      sql`${events.id} IN (${sql.join(
-        body.ids.map((id) => sql`${id}`),
-        sql`, `
-      )})`
+function serializeEvent(event) {
+  if (!event) return event;
+  const { dateTime, ...rest } = event;
+  return { ...rest, date: dateTime };
+}
+function serializeEvents(events2) {
+  return events2.map(serializeEvent);
+}
+classesRoute.get(
+  "/admin",
+  describeRoute({
+    tags: ["Events"],
+    summary: "List all events (admin)",
+    responses: { 200: { description: "List of all events" } }
+  }),
+  authMiddleware,
+  adminMiddleware,
+  async (c) => {
+    const db = createDb(c.env.DB);
+    const data = await db.query.events.findMany({
+      with: { theme: true, organization: true },
+      orderBy: (e, { desc }) => [desc(e.createdAt)]
+    });
+    return c.json({ data: serializeEvents(data) });
+  }
+);
+classesRoute.post(
+  "/admin/publish",
+  describeRoute({
+    tags: ["Events"],
+    summary: "Batch publish queued events",
+    responses: {
+      200: { description: "Events published successfully" },
+      400: { description: "Missing event IDs" }
+    }
+  }),
+  authMiddleware,
+  adminMiddleware,
+  async (c) => {
+    const body = await c.req.json();
+    const db = createDb(c.env.DB);
+    const cache = new CacheService(c.env.KV);
+    if (!body.ids?.length) {
+      return c.json({ error: "ids are required" }, 400);
+    }
+    if (body.releaseAt) {
+      await db.update(events).set({ releaseAt: body.releaseAt, status: "queued" }).where(
+        sql`${events.id} IN (${sql.join(
+          body.ids.map((id) => sql`${id}`),
+          sql`, `
+        )})`
+      );
+    } else {
+      await db.update(events).set({ status: "published", publishedAt: sql`(unixepoch())` }).where(
+        sql`${events.id} IN (${sql.join(
+          body.ids.map((id) => sql`${id}`),
+          sql`, `
+        )})`
+      );
+    }
+    await Promise.all([
+      cache.del(EVENTS_LIST_KV_KEY),
+      cache.del(EVENTS_ETAG_KV_KEY)
+    ]);
+    return c.json({ data: { updated: body.ids.length } });
+  }
+);
+classesRoute.get(
+  "/",
+  describeRoute({
+    tags: ["Events"],
+    summary: "List published events",
+    responses: { 200: { description: "List of published events with themes" } }
+  }),
+  eventsListRateLimit,
+  async (c) => {
+    const db = createDb(c.env.DB);
+    const cache = new CacheService(c.env.KV);
+    const [latest] = await db.select({ max: events.publishedAt }).from(events).where(eq(events.status, "published")).limit(1);
+    const etag = await cache.getOrSet(
+      EVENTS_ETAG_KV_KEY,
+      () => cache.generateETag(String(latest?.max ?? "0")),
+      300
+    );
+    const ifNoneMatch = c.req.header("If-None-Match");
+    if (ifNoneMatch === etag) {
+      return c.body(null, 304);
+    }
+    const data = await cache.getOrSet(
+      EVENTS_LIST_KV_KEY,
+      () => db.query.events.findMany({
+        where: eq(events.status, "published"),
+        with: {
+          theme: true,
+          organization: true
+        },
+        columns: {
+          id: true,
+          slug: true,
+          themeId: true,
+          organizationId: true,
+          title: true,
+          venue: true,
+          dateTime: true,
+          price: true,
+          backgroundImageUrl: true,
+          classCode: true,
+          startTime: true,
+          endTime: true,
+          registrationClosesAt: true,
+          isSpotlight: true,
+          maxSlots: true,
+          registeredSlots: true,
+          gformsUrl: true,
+          gformsEditorUrl: true,
+          publishedAt: true
+        }
+      }),
+      EVENTS_LIST_TTL
     );
-  } else {
-    await db.update(events).set({ status: "published", publishedAt: sql`(unixepoch())` }).where(
-      sql`${events.id} IN (${sql.join(
-        body.ids.map((id) => sql`${id}`),
-        sql`, `
-      )})`
+    c.header("ETag", etag);
+    c.header(
+      "Cache-Control",
+      "public, max-age=604800, stale-while-revalidate=86400"
     );
+    return c.json({ data: serializeEvents(data) });
   }
-  await Promise.all([
-    cache.del(EVENTS_LIST_KV_KEY),
-    cache.del(EVENTS_ETAG_KV_KEY)
-  ]);
-  return c.json({ data: { updated: body.ids.length } });
-});
-classesRoute.get("/", eventsListRateLimit, async (c) => {
-  const db = createDb(c.env.DB);
-  const cache = new CacheService(c.env.KV);
-  const [latest] = await db.select({ max: events.publishedAt }).from(events).where(eq(events.status, "published")).limit(1);
-  const etag = await cache.getOrSet(
-    EVENTS_ETAG_KV_KEY,
-    () => cache.generateETag(String(latest?.max ?? "0")),
-    300
-  );
-  const ifNoneMatch = c.req.header("If-None-Match");
-  if (ifNoneMatch === etag) {
-    return c.body(null, 304);
-  }
-  const data = await cache.getOrSet(
-    EVENTS_LIST_KV_KEY,
-    () => db.query.events.findMany({
-      where: eq(events.status, "published"),
+);
+classesRoute.get(
+  "/:slug",
+  describeRoute({
+    tags: ["Events"],
+    summary: "Get event by slug",
+    responses: {
+      200: { description: "Event details" },
+      404: { description: "Event not found" }
+    }
+  }),
+  async (c) => {
+    const { slug } = c.req.param();
+    const db = createDb(c.env.DB);
+    const event = await db.query.events.findFirst({
+      where: and(eq(events.slug, slug), eq(events.status, "published")),
       with: {
-        theme: true,
-        organization: true
-      },
-      columns: {
-        id: true,
-        slug: true,
-        themeId: true,
-        organizationId: true,
-        title: true,
-        venue: true,
-        dateTime: true,
-        price: true,
-        backgroundImageUrl: true,
-        classCode: true,
-        startTime: true,
-        endTime: true,
-        registrationClosesAt: true,
-        isSpotlight: true,
-        maxSlots: true,
-        registeredSlots: true,
-        gformsUrl: true,
-        gformsEditorUrl: true,
-        publishedAt: true
+        theme: true
       }
-    }),
-    EVENTS_LIST_TTL
-  );
-  c.header("ETag", etag);
-  c.header(
-    "Cache-Control",
-    "public, max-age=604800, stale-while-revalidate=86400"
-  );
-  return c.json({ data });
-});
-classesRoute.get("/:slug", async (c) => {
-  const { slug } = c.req.param();
-  const db = createDb(c.env.DB);
-  const event = await db.query.events.findFirst({
-    where: and(eq(events.slug, slug), eq(events.status, "published")),
-    with: {
-      theme: true
+    });
+    if (!event) throw notFound("Event");
+    return c.json({ data: serializeEvent(event) });
+  }
+);
+classesRoute.get(
+  "/:slug/slots",
+  describeRoute({
+    tags: ["Events"],
+    summary: "Get event slot availability",
+    responses: {
+      200: { description: "Slot availability info" },
+      404: { description: "Event not found" }
     }
-  });
-  if (!event) throw notFound("Event");
-  return c.json({ data: event });
-});
-classesRoute.get("/:slug/slots", eventsSlotsRateLimit, async (c) => {
-  const { slug } = c.req.param();
-  const db = createDb(c.env.DB);
-  const cache = new CacheService(c.env.KV);
-  const slotsService = new SlotsService(db, cache);
-  const info = await slotsService.getSlots(slug);
-  if (!info) throw notFound("Event");
-  c.header("Cache-Control", "public, max-age=5, stale-while-revalidate=5");
-  return c.json({ data: info });
-});
-classesRoute.post("/:slug/reconcile", authMiddleware, adminMiddleware, async (c) => {
-  const { slug } = c.req.param();
-  const db = createDb(c.env.DB);
-  const cache = new CacheService(c.env.KV);
-  const gforms = new GFormsService(c.env.GFORMS_SERVICE_ACCOUNT_JSON);
-  const slots = new SlotsService(db, cache);
-  const event = await db.query.events.findFirst({
-    where: eq(events.slug, slug),
-    columns: { gformsId: true }
-  });
-  if (!event) throw notFound("Event");
-  if (!event.gformsId) return c.json({ error: "No gformsId set for this event" }, 400);
-  try {
-    const googleCount = await gforms.getExactResponseCount(event.gformsId);
-    await slots.correctCount(slug, googleCount);
-    return c.json({ data: { registeredSlots: googleCount } });
-  } catch (err) {
-    const message = err?.message ?? "Failed to fetch from Google Forms API";
-    return c.json({ error: { code: "GFORMS_API_ERROR", message } }, 502);
+  }),
+  eventsSlotsRateLimit,
+  async (c) => {
+    const { slug } = c.req.param();
+    const db = createDb(c.env.DB);
+    const cache = new CacheService(c.env.KV);
+    const slotsService = new SlotsService(db, cache);
+    const info = await slotsService.getSlots(slug);
+    if (!info) throw notFound("Event");
+    c.header("Cache-Control", "public, max-age=5, stale-while-revalidate=5");
+    return c.json({ data: info });
   }
-});
+);
+classesRoute.post(
+  "/:slug/reconcile",
+  describeRoute({
+    tags: ["Events"],
+    summary: "Reconcile event slot count with Google Forms",
+    responses: {
+      200: { description: "Slot count reconciled" },
+      400: { description: "No gformsId set" },
+      404: { description: "Event not found" },
+      502: { description: "Google Forms API error" }
+    }
+  }),
+  authMiddleware,
+  adminMiddleware,
+  async (c) => {
+    const { slug } = c.req.param();
+    const db = createDb(c.env.DB);
+    const cache = new CacheService(c.env.KV);
+    const gforms = new GFormsService(c.env.GFORMS_SERVICE_ACCOUNT_JSON);
+    const slots = new SlotsService(db, cache);
+    const event = await db.query.events.findFirst({
+      where: eq(events.slug, slug),
+      columns: { gformsId: true }
+    });
+    if (!event) throw notFound("Event");
+    if (!event.gformsId) return c.json({ error: "No gformsId set for this event" }, 400);
+    try {
+      const googleCount = await gforms.getExactResponseCount(event.gformsId);
+      await slots.correctCount(slug, googleCount);
+      return c.json({ data: { registeredSlots: googleCount } });
+    } catch (err) {
+      const message = err?.message ?? "Failed to fetch from Google Forms API";
+      return c.json({ error: { code: "GFORMS_API_ERROR", message } }, 502);
+    }
+  }
+);
 classesRoute.post(
   "/",
+  describeRoute({
+    tags: ["Events"],
+    summary: "Create a new event",
+    responses: {
+      201: { description: "Event created successfully" },
+      422: { description: "Validation error" }
+    }
+  }),
   authMiddleware,
   adminMiddleware,
   adminEventsRateLimit,
-  zValidator("json", createEventSchema),
+  validator("json", createEventSchema),
   async (c) => {
     const body = c.req.valid("json");
     const db = createDb(c.env.DB);
@@ -1282,161 +1385,287 @@ classesRoute.post(
       cache.del(EVENTS_LIST_KV_KEY),
       cache.del(EVENTS_ETAG_KV_KEY)
     ]);
-    return c.json({ data: created }, 201);
+    return c.json({ data: serializeEvent(created) }, 201);
+  }
+);
+classesRoute.patch(
+  "/:slug",
+  describeRoute({
+    tags: ["Events"],
+    summary: "Update an event",
+    responses: {
+      200: { description: "Event updated successfully" },
+      404: { description: "Event not found" }
+    }
+  }),
+  authMiddleware,
+  adminMiddleware,
+  async (c) => {
+    const { slug } = c.req.param();
+    const body = await c.req.json();
+    const db = createDb(c.env.DB);
+    const cache = new CacheService(c.env.KV);
+    let newSlug;
+    if (body.title) {
+      newSlug = generateSlug(body.title);
+    }
+    const [updated] = await db.update(events).set(newSlug ? { ...body, slug: newSlug } : body).where(eq(events.slug, slug)).returning();
+    if (!updated) throw notFound("Event");
+    await Promise.all([
+      cache.del(EVENTS_LIST_KV_KEY),
+      cache.del(EVENTS_ETAG_KV_KEY)
+    ]);
+    return c.json({ data: serializeEvent(updated) });
+  }
+);
+classesRoute.delete(
+  "/:slug",
+  describeRoute({
+    tags: ["Events"],
+    summary: "Delete an event",
+    responses: {
+      204: { description: "Event deleted" },
+      404: { description: "Event not found" }
+    }
+  }),
+  authMiddleware,
+  adminMiddleware,
+  async (c) => {
+    const { slug } = c.req.param();
+    const db = createDb(c.env.DB);
+    const cache = new CacheService(c.env.KV);
+    const [deleted] = await db.delete(events).where(eq(events.slug, slug)).returning();
+    if (!deleted) throw notFound("Event");
+    await Promise.all([
+      cache.del(EVENTS_LIST_KV_KEY),
+      cache.del(EVENTS_ETAG_KV_KEY)
+    ]);
+    return c.body(null, 204);
   }
 );
-classesRoute.patch("/:slug", authMiddleware, adminMiddleware, async (c) => {
-  const { slug } = c.req.param();
-  const body = await c.req.json();
-  const db = createDb(c.env.DB);
-  const cache = new CacheService(c.env.KV);
-  let newSlug;
-  if (body.title) {
-    newSlug = generateSlug(body.title);
-  }
-  const [updated] = await db.update(events).set(newSlug ? { ...body, slug: newSlug } : body).where(eq(events.slug, slug)).returning();
-  if (!updated) throw notFound("Event");
-  await Promise.all([
-    cache.del(EVENTS_LIST_KV_KEY),
-    cache.del(EVENTS_ETAG_KV_KEY)
-  ]);
-  return c.json({ data: updated });
-});
-classesRoute.delete("/:slug", authMiddleware, adminMiddleware, async (c) => {
-  const { slug } = c.req.param();
-  const db = createDb(c.env.DB);
-  const cache = new CacheService(c.env.KV);
-  const [deleted] = await db.delete(events).where(eq(events.slug, slug)).returning();
-  if (!deleted) throw notFound("Event");
-  await Promise.all([
-    cache.del(EVENTS_LIST_KV_KEY),
-    cache.del(EVENTS_ETAG_KV_KEY)
-  ]);
-  return c.body(null, 204);
-});
 var VALID_ROLES = ["student", "admin", "super_admin"];
 var usersRoute = new Hono();
-usersRoute.get("/", authMiddleware, adminMiddleware, async (c) => {
-  const db = createDb(c.env.DB);
-  const data = await db.select().from(users);
-  return c.json({ data });
-});
-usersRoute.patch("/:id/role", authMiddleware, adminMiddleware, async (c) => {
-  const { id } = c.req.param();
-  const { role } = await c.req.json();
-  if (!role || !VALID_ROLES.includes(role)) {
-    throw badRequest("Role must be 'student', 'admin', or 'super_admin'.");
-  }
-  const db = createDb(c.env.DB);
-  const [updated] = await db.update(users).set({ role }).where(eq(users.id, id)).returning();
-  if (!updated) throw notFound("User");
-  return c.json({ data: updated });
-});
-usersRoute.post("/by-email", authMiddleware, adminMiddleware, async (c) => {
-  const { email, role } = await c.req.json();
-  if (!email || !role || !VALID_ROLES.includes(role)) {
-    throw badRequest("Email and valid role ('student', 'admin', 'super_admin') are required.");
-  }
-  const db = createDb(c.env.DB);
-  const existing = await db.query.users.findFirst({
-    where: eq(users.email, email)
-  });
-  if (existing) {
-    const [updated] = await db.update(users).set({ role }).where(eq(users.email, email)).returning();
+usersRoute.get(
+  "/",
+  describeRoute({
+    tags: ["Users"],
+    summary: "List all users (admin)",
+    responses: { 200: { description: "List of users" } }
+  }),
+  authMiddleware,
+  adminMiddleware,
+  async (c) => {
+    const db = createDb(c.env.DB);
+    const data = await db.select().from(users);
+    return c.json({ data });
+  }
+);
+usersRoute.patch(
+  "/:id/role",
+  describeRoute({
+    tags: ["Users"],
+    summary: "Change user role (admin)",
+    responses: {
+      200: { description: "Role updated" },
+      400: { description: "Invalid role" },
+      404: { description: "User not found" }
+    }
+  }),
+  authMiddleware,
+  adminMiddleware,
+  async (c) => {
+    const { id } = c.req.param();
+    const { role } = await c.req.json();
+    if (!role || !VALID_ROLES.includes(role)) {
+      throw badRequest("Role must be 'student', 'admin', or 'super_admin'.");
+    }
+    const db = createDb(c.env.DB);
+    const [updated] = await db.update(users).set({ role }).where(eq(users.id, id)).returning();
+    if (!updated) throw notFound("User");
     return c.json({ data: updated });
   }
-  const [created] = await db.insert(users).values({ betterAuthId: `pending:${email}`, email, name: email.split("@")[0], role }).returning();
-  return c.json({ data: created }, 201);
-});
-usersRoute.get("/me", optionalAuthMiddleware, async (c) => {
-  const user = c.get("user");
-  if (!user) return c.json({ data: null });
-  const db = createDb(c.env.DB);
-  const profile = await db.query.users.findFirst({
-    where: eq(users.id, user.dbId)
-  });
-  if (!profile) return c.json({ data: null });
-  const auth = await db.query.authUser.findFirst({
-    where: eq(authUser.id, profile.betterAuthId),
-    columns: { image: true }
-  });
-  return c.json({ data: { ...profile, image: auth?.image ?? null } });
-});
-usersRoute.get("/me/bookmarks", optionalAuthMiddleware, async (c) => {
-  const user = c.get("user");
-  if (!user) return c.json({ data: [] });
-  const db = createDb(c.env.DB);
-  const rows = await db.query.bookmarks.findMany({
-    where: eq(bookmarks.userId, user.dbId),
-    with: { event: true }
-  });
-  const data = rows.map((r) => ({ bookmarkedAt: r.createdAt, event: r.event }));
-  return c.json({ data });
-});
-usersRoute.post("/me/bookmarks/:eventId", authMiddleware, bookmarksRateLimit, async (c) => {
-  const { eventId } = c.req.param();
-  const user = c.get("user");
-  const db = createDb(c.env.DB);
-  const event = await db.query.events.findFirst({
-    where: eq(events.id, eventId),
-    columns: { id: true }
-  });
-  if (!event) throw notFound("Event");
-  const inserted = await db.insert(bookmarks).values({ userId: user.dbId, eventId }).onConflictDoNothing({ target: [bookmarks.userId, bookmarks.eventId] }).returning();
-  if (inserted.length > 0) {
-    return c.json({ data: { bookmarked: true } }, 201);
+);
+usersRoute.post(
+  "/by-email",
+  describeRoute({
+    tags: ["Users"],
+    summary: "Find or create user by email (admin)",
+    responses: {
+      200: { description: "User updated" },
+      201: { description: "User created" },
+      400: { description: "Invalid email or role" }
+    }
+  }),
+  authMiddleware,
+  adminMiddleware,
+  async (c) => {
+    const { email, role } = await c.req.json();
+    if (!email || !role || !VALID_ROLES.includes(role)) {
+      throw badRequest("Email and valid role ('student', 'admin', 'super_admin') are required.");
+    }
+    const db = createDb(c.env.DB);
+    const existing = await db.query.users.findFirst({
+      where: eq(users.email, email)
+    });
+    if (existing) {
+      const [updated] = await db.update(users).set({ role }).where(eq(users.email, email)).returning();
+      return c.json({ data: updated });
+    }
+    const [created] = await db.insert(users).values({ betterAuthId: `pending:${email}`, email, name: email.split("@")[0], role }).returning();
+    return c.json({ data: created }, 201);
   }
-  await db.delete(bookmarks).where(and(eq(bookmarks.userId, user.dbId), eq(bookmarks.eventId, eventId)));
-  return c.json({ data: { bookmarked: false } }, 200);
-});
-usersRoute.delete("/me/bookmarks/:eventId", authMiddleware, async (c) => {
-  const { eventId } = c.req.param();
-  const user = c.get("user");
-  const db = createDb(c.env.DB);
-  await db.delete(bookmarks).where(
-    and(eq(bookmarks.userId, user.dbId), eq(bookmarks.eventId, eventId))
-  );
-  return c.json({ data: { bookmarked: false } });
-});
-var siteConfigRoute = new Hono();
-siteConfigRoute.get("/", async (c) => {
-  const db = createDb(c.env.DB);
-  const rows = await db.query.siteConfig.findMany();
-  const config = Object.fromEntries(
-    rows.map((r) => [r.key, JSON.parse(r.value)])
-  );
-  return c.json({
-    data: {
-      comingSoonUntil: config.coming_soon_until ?? null,
-      siteEndsAt: config.site_ends_at ?? null,
-      siteName: config.site_name ?? null,
-      registrationGloballyOpen: config.registration_globally_open ?? true,
-      maintenanceMode: config.maintenance_mode ?? false,
-      allowedOrigins: config.allowed_origins ?? null,
-      now: Math.floor(Date.now() / 1e3)
+);
+usersRoute.get(
+  "/me",
+  describeRoute({
+    tags: ["Users"],
+    summary: "Get current user profile",
+    responses: { 200: { description: "Current user profile or null" } }
+  }),
+  optionalAuthMiddleware,
+  async (c) => {
+    const user = c.get("user");
+    if (!user) return c.json({ data: null });
+    const db = createDb(c.env.DB);
+    const profile = await db.query.users.findFirst({
+      where: eq(users.id, user.dbId)
+    });
+    if (!profile) return c.json({ data: null });
+    const auth = await db.query.authUser.findFirst({
+      where: eq(authUser.id, profile.betterAuthId),
+      columns: { image: true }
+    });
+    return c.json({ data: { ...profile, image: auth?.image ?? null } });
+  }
+);
+usersRoute.get(
+  "/me/bookmarks",
+  describeRoute({
+    tags: ["Users"],
+    summary: "Get current user's bookmarks",
+    responses: { 200: { description: "List of bookmarked events" } }
+  }),
+  optionalAuthMiddleware,
+  async (c) => {
+    const user = c.get("user");
+    if (!user) return c.json({ data: [] });
+    const db = createDb(c.env.DB);
+    const rows = await db.query.bookmarks.findMany({
+      where: eq(bookmarks.userId, user.dbId),
+      with: { event: true }
+    });
+    const data = rows.map((r) => ({ bookmarkedAt: r.createdAt, event: r.event }));
+    return c.json({ data });
+  }
+);
+usersRoute.post(
+  "/me/bookmarks/:eventId",
+  describeRoute({
+    tags: ["Users"],
+    summary: "Toggle bookmark for an event",
+    responses: {
+      201: { description: "Bookmark created" },
+      200: { description: "Bookmark removed" },
+      404: { description: "Event not found" }
     }
-  });
-});
-siteConfigRoute.patch("/:key", authMiddleware, adminMiddleware, async (c) => {
-  const key = c.req.param("key");
-  const { value } = await c.req.json();
-  if (key === "allowed_origins") {
+  }),
+  authMiddleware,
+  bookmarksRateLimit,
+  async (c) => {
+    const { eventId } = c.req.param();
     const user = c.get("user");
-    if (!user || user.role !== "super_admin") {
-      throw forbidden("Super Admin access required to change allowed origins");
+    const db = createDb(c.env.DB);
+    const event = await db.query.events.findFirst({
+      where: eq(events.id, eventId),
+      columns: { id: true }
+    });
+    if (!event) throw notFound("Event");
+    const inserted = await db.insert(bookmarks).values({ userId: user.dbId, eventId }).onConflictDoNothing({ target: [bookmarks.userId, bookmarks.eventId] }).returning();
+    if (inserted.length > 0) {
+      return c.json({ data: { bookmarked: true } }, 201);
     }
+    await db.delete(bookmarks).where(and(eq(bookmarks.userId, user.dbId), eq(bookmarks.eventId, eventId)));
+    return c.json({ data: { bookmarked: false } }, 200);
   }
-  const db = createDb(c.env.DB);
-  const now = Math.floor(Date.now() / 1e3);
-  await db.insert(siteConfig).values({ key, value: JSON.stringify(value), updatedAt: now }).onConflictDoUpdate({
-    target: siteConfig.key,
-    set: { value: JSON.stringify(value), updatedAt: now }
-  });
-  await c.env.KV.put(`config:${key}`, JSON.stringify(value), {
-    expirationTtl: 86400
-  });
-  return c.json({ data: { key, value } });
-});
+);
+usersRoute.delete(
+  "/me/bookmarks/:eventId",
+  describeRoute({
+    tags: ["Users"],
+    summary: "Remove bookmark for an event",
+    responses: { 200: { description: "Bookmark removed" } }
+  }),
+  authMiddleware,
+  async (c) => {
+    const { eventId } = c.req.param();
+    const user = c.get("user");
+    const db = createDb(c.env.DB);
+    await db.delete(bookmarks).where(
+      and(eq(bookmarks.userId, user.dbId), eq(bookmarks.eventId, eventId))
+    );
+    return c.json({ data: { bookmarked: false } });
+  }
+);
+var siteConfigRoute = new Hono();
+siteConfigRoute.get(
+  "/",
+  describeRoute({
+    tags: ["Site Config"],
+    summary: "Get public site configuration",
+    responses: { 200: { description: "Site configuration values" } }
+  }),
+  async (c) => {
+    const db = createDb(c.env.DB);
+    const rows = await db.query.siteConfig.findMany();
+    const config = Object.fromEntries(
+      rows.map((r) => [r.key, JSON.parse(r.value)])
+    );
+    return c.json({
+      data: {
+        comingSoonUntil: config.coming_soon_until ?? null,
+        siteEndsAt: config.site_ends_at ?? null,
+        siteName: config.site_name ?? null,
+        registrationGloballyOpen: config.registration_globally_open ?? true,
+        maintenanceMode: config.maintenance_mode ?? false,
+        allowedOrigins: config.allowed_origins ?? null,
+        now: Math.floor(Date.now() / 1e3)
+      }
+    });
+  }
+);
+siteConfigRoute.patch(
+  "/:key",
+  describeRoute({
+    tags: ["Site Config"],
+    summary: "Update a site configuration key (admin)",
+    responses: {
+      200: { description: "Config updated" },
+      403: { description: "Super admin required for this key" }
+    }
+  }),
+  authMiddleware,
+  adminMiddleware,
+  async (c) => {
+    const key = c.req.param("key");
+    const { value } = await c.req.json();
+    if (key === "allowed_origins") {
+      const user = c.get("user");
+      if (!user || user.role !== "super_admin") {
+        throw forbidden("Super Admin access required to change allowed origins");
+      }
+    }
+    const db = createDb(c.env.DB);
+    const now = Math.floor(Date.now() / 1e3);
+    await db.insert(siteConfig).values({ key, value: JSON.stringify(value), updatedAt: now }).onConflictDoUpdate({
+      target: siteConfig.key,
+      set: { value: JSON.stringify(value), updatedAt: now }
+    });
+    await c.env.KV.put(`config:${key}`, JSON.stringify(value), {
+      expirationTtl: 86400
+    });
+    return c.json({ data: { key, value } });
+  }
+);
 var FAQS_KV_KEY = "faqs:active";
 var FAQS_TTL = 600;
 var faqSchema = z.object({
@@ -1446,23 +1675,39 @@ var faqSchema = z.object({
   sortOrder: z.number().int().default(0)
 });
 var faqsRoute = new Hono();
-faqsRoute.get("/", async (c) => {
-  const db = createDb(c.env.DB);
-  const cache = new CacheService(c.env.KV);
-  const data = await cache.getOrSet(
-    FAQS_KV_KEY,
-    () => db.query.faqs.findMany({
-      orderBy: (t, { asc: asc2 }) => [asc2(t.sortOrder), asc2(t.createdAt)]
-    }),
-    FAQS_TTL
-  );
-  return c.json({ data });
-});
+faqsRoute.get(
+  "/",
+  describeRoute({
+    tags: ["FAQs"],
+    summary: "List all active FAQs",
+    responses: { 200: { description: "List of FAQs" } }
+  }),
+  async (c) => {
+    const db = createDb(c.env.DB);
+    const cache = new CacheService(c.env.KV);
+    const data = await cache.getOrSet(
+      FAQS_KV_KEY,
+      () => db.query.faqs.findMany({
+        orderBy: (t, { asc: asc2 }) => [asc2(t.sortOrder), asc2(t.createdAt)]
+      }),
+      FAQS_TTL
+    );
+    return c.json({ data });
+  }
+);
 faqsRoute.post(
   "/",
+  describeRoute({
+    tags: ["FAQs"],
+    summary: "Create a new FAQ (admin)",
+    responses: {
+      201: { description: "FAQ created" },
+      422: { description: "Validation error" }
+    }
+  }),
   authMiddleware,
   adminMiddleware,
-  zValidator("json", faqSchema),
+  validator("json", faqSchema),
   async (c) => {
     const body = c.req.valid("json");
     const db = createDb(c.env.DB);
@@ -1472,65 +1717,105 @@ faqsRoute.post(
     return c.json({ data: created }, 201);
   }
 );
-faqsRoute.patch("/:id", authMiddleware, adminMiddleware, async (c) => {
-  const { id } = c.req.param();
-  const body = await c.req.json();
-  const db = createDb(c.env.DB);
-  const cache = new CacheService(c.env.KV);
-  const now = Math.floor(Date.now() / 1e3);
-  const [updated] = await db.update(faqs).set({ ...body, updatedAt: now }).where(eq(faqs.id, id)).returning();
-  if (!updated) throw notFound("FAQ");
-  await cache.del(FAQS_KV_KEY);
-  return c.json({ data: updated });
-});
-faqsRoute.delete("/:id", authMiddleware, adminMiddleware, async (c) => {
-  const { id } = c.req.param();
-  const db = createDb(c.env.DB);
-  const cache = new CacheService(c.env.KV);
-  const [deleted] = await db.delete(faqs).where(eq(faqs.id, id)).returning();
-  if (!deleted) throw notFound("FAQ");
-  await cache.del(FAQS_KV_KEY);
-  return c.json({ data: { deleted: true } });
-});
-var gformsWebhookRoute = new Hono();
-gformsWebhookRoute.post("/", internalMiddleware, async (c) => {
-  const rawBody = await c.req.text();
-  const signature = c.req.header("X-Goog-Signature");
-  if (signature) {
-    const isValid = await verifyGoogSignature(
-      rawBody,
-      signature,
-      c.env.GFORMS_WEBHOOK_SECRET
-    );
-    if (!isValid) {
-      return c.json({ error: "Invalid signature" }, 403);
+faqsRoute.patch(
+  "/:id",
+  describeRoute({
+    tags: ["FAQs"],
+    summary: "Update an FAQ (admin)",
+    responses: {
+      200: { description: "FAQ updated" },
+      404: { description: "FAQ not found" }
+    }
+  }),
+  authMiddleware,
+  adminMiddleware,
+  async (c) => {
+    const { id } = c.req.param();
+    const body = await c.req.json();
+    const db = createDb(c.env.DB);
+    const cache = new CacheService(c.env.KV);
+    const now = Math.floor(Date.now() / 1e3);
+    const [updated] = await db.update(faqs).set({ ...body, updatedAt: now }).where(eq(faqs.id, id)).returning();
+    if (!updated) throw notFound("FAQ");
+    await cache.del(FAQS_KV_KEY);
+    return c.json({ data: updated });
+  }
+);
+faqsRoute.delete(
+  "/:id",
+  describeRoute({
+    tags: ["FAQs"],
+    summary: "Delete an FAQ (admin)",
+    responses: {
+      200: { description: "FAQ deleted" },
+      404: { description: "FAQ not found" }
     }
+  }),
+  authMiddleware,
+  adminMiddleware,
+  async (c) => {
+    const { id } = c.req.param();
+    const db = createDb(c.env.DB);
+    const cache = new CacheService(c.env.KV);
+    const [deleted] = await db.delete(faqs).where(eq(faqs.id, id)).returning();
+    if (!deleted) throw notFound("FAQ");
+    await cache.del(FAQS_KV_KEY);
+    return c.json({ data: { deleted: true } });
   }
-  let payload;
-  try {
-    payload = JSON.parse(rawBody);
-  } catch {
-    return c.json({ error: "Invalid payload" }, 400);
-  }
-  const { formId } = payload;
-  if (!formId) return c.json({ error: "Missing formId" }, 400);
-  const db = createDb(c.env.DB);
-  const cache = new CacheService(c.env.KV);
-  const event = await db.query.events.findFirst({
-    where: eq(events.gformsId, formId),
-    columns: { slug: true, maxSlots: true, registeredSlots: true }
-  });
-  if (!event) {
-    console.warn(`[gforms-webhook] Unknown formId: ${formId}`);
+);
+var gformsWebhookRoute = new Hono();
+gformsWebhookRoute.post(
+  "/",
+  describeRoute({
+    tags: ["Internal"],
+    summary: "Google Forms webhook receiver",
+    description: "Receives Google Forms Watch push notifications and increments slot counters.",
+    responses: {
+      200: { description: "Notification processed" },
+      400: { description: "Invalid payload" },
+      403: { description: "Invalid HMAC signature" }
+    }
+  }),
+  internalMiddleware,
+  async (c) => {
+    const rawBody = await c.req.text();
+    const signature = c.req.header("X-Goog-Signature");
+    if (signature) {
+      const isValid = await verifyGoogSignature(
+        rawBody,
+        signature,
+        c.env.GFORMS_WEBHOOK_SECRET
+      );
+      if (!isValid) {
+        return c.json({ error: "Invalid signature" }, 403);
+      }
+    }
+    let payload;
+    try {
+      payload = JSON.parse(rawBody);
+    } catch {
+      return c.json({ error: "Invalid payload" }, 400);
+    }
+    const { formId } = payload;
+    if (!formId) return c.json({ error: "Missing formId" }, 400);
+    const db = createDb(c.env.DB);
+    const cache = new CacheService(c.env.KV);
+    const event = await db.query.events.findFirst({
+      where: eq(events.gformsId, formId),
+      columns: { slug: true, maxSlots: true, registeredSlots: true }
+    });
+    if (!event) {
+      console.warn(`[gforms-webhook] Unknown formId: ${formId}`);
+      return c.json({ ok: true });
+    }
+    const slotsService = new SlotsService(db, cache);
+    const updated = await slotsService.increment(event.slug);
+    console.log(
+      `[gforms-webhook] Incremented "${event.slug}": ${updated?.registered}/${updated?.total}`
+    );
     return c.json({ ok: true });
   }
-  const slotsService = new SlotsService(db, cache);
-  const updated = await slotsService.increment(event.slug);
-  console.log(
-    `[gforms-webhook] Incremented "${event.slug}": ${updated?.registered}/${updated?.total}`
-  );
-  return c.json({ ok: true });
-});
+);
 async function verifyGoogSignature(body, signature, secret) {
   try {
     const key = await crypto.subtle.importKey(
@@ -1599,10 +1884,20 @@ async function reconcileSlots(env) {
 
 // src/routes/internal/reconcile-slots.ts
 var reconcileSlotsRoute = new Hono();
-reconcileSlotsRoute.post("/", internalMiddleware, async (c) => {
-  await reconcileSlots(c.env);
-  return c.json({ ok: true });
-});
+reconcileSlotsRoute.post(
+  "/",
+  describeRoute({
+    tags: ["Internal"],
+    summary: "Reconcile event slot counts",
+    description: "Triggers slot count reconciliation for all events with Google Forms.",
+    responses: { 200: { description: "Reconciliation complete" } }
+  }),
+  internalMiddleware,
+  async (c) => {
+    await reconcileSlots(c.env);
+    return c.json({ ok: true });
+  }
+);
 async function batchRelease(env) {
   const db = createDb(env.DB);
   const cache = new CacheService(env.KV);
@@ -1630,10 +1925,20 @@ async function batchRelease(env) {
 
 // src/routes/internal/batch-release.ts
 var batchReleaseRoute = new Hono();
-batchReleaseRoute.post("/", internalMiddleware, async (c) => {
-  await batchRelease(c.env);
-  return c.json({ ok: true });
-});
+batchReleaseRoute.post(
+  "/",
+  describeRoute({
+    tags: ["Internal"],
+    summary: "Batch release queued events",
+    description: "Triggers batch release of queued events whose releaseAt time has passed.",
+    responses: { 200: { description: "Batch release complete" } }
+  }),
+  internalMiddleware,
+  async (c) => {
+    await batchRelease(c.env);
+    return c.json({ ok: true });
+  }
+);
 function parseStartTimestamp(dateTime, startTime) {
   if (!dateTime) return null;
   const combined = startTime ? `${dateTime} ${startTime}` : dateTime;
@@ -1705,10 +2010,20 @@ async function reminderEmails(env) {
 
 // src/routes/internal/reminder-emails.ts
 var reminderEmailsRoute = new Hono();
-reminderEmailsRoute.post("/", internalMiddleware, async (c) => {
-  await reminderEmails(c.env);
-  return c.json({ ok: true });
-});
+reminderEmailsRoute.post(
+  "/",
+  describeRoute({
+    tags: ["Internal"],
+    summary: "Send reminder emails",
+    description: "Triggers reminder email processing for upcoming events.",
+    responses: { 200: { description: "Reminder emails processed" } }
+  }),
+  internalMiddleware,
+  async (c) => {
+    await reminderEmails(c.env);
+    return c.json({ ok: true });
+  }
+);
 var RENEWAL_WINDOW = 86400;
 async function renewWatches(env) {
   const db = createDb(env.DB);
@@ -1740,10 +2055,20 @@ async function renewWatches(env) {
 
 // src/routes/internal/renew-watches.ts
 var renewWatchesRoute = new Hono();
-renewWatchesRoute.post("/", internalMiddleware, async (c) => {
-  await renewWatches(c.env);
-  return c.json({ ok: true });
-});
+renewWatchesRoute.post(
+  "/",
+  describeRoute({
+    tags: ["Internal"],
+    summary: "Renew Google Forms watches",
+    description: "Triggers renewal of expiring Google Forms Watch subscriptions.",
+    responses: { 200: { description: "Watch renewal complete" } }
+  }),
+  internalMiddleware,
+  async (c) => {
+    await renewWatches(c.env);
+    return c.json({ ok: true });
+  }
+);
 var ALLOWED_MIME_TYPES = /* @__PURE__ */ new Set([
   "image/jpeg",
   "image/png",
@@ -1753,30 +2078,50 @@ var ALLOWED_MIME_TYPES = /* @__PURE__ */ new Set([
 ]);
 var MAX_FILE_SIZE = 10 * 1024 * 1024;
 var uploadsRoute = new Hono();
-uploadsRoute.get("/images/*", async (c) => {
-  const bucket = c.env.FILES;
-  if (!bucket) {
-    throw serviceUnavailable("File storage (R2) is not configured.");
-  }
-  const path = c.req.path.split("/uploads/images/")[1];
-  if (!path) throw notFound("Image");
-  const object = await bucket.get(path);
-  if (!object) throw notFound("Image");
-  const headers = {
-    etag: object.httpEtag,
-    // Cache at the edge/browser for 1 month
-    "Cache-Control": "public, max-age=2592000, immutable"
-  };
-  if (object.httpMetadata?.contentType) {
-    headers["Content-Type"] = object.httpMetadata.contentType;
-  }
-  if (object.httpMetadata?.cacheControl) {
-    headers["Cache-Control"] = object.httpMetadata.cacheControl;
+uploadsRoute.get(
+  "/images/*",
+  describeRoute({
+    tags: ["Uploads"],
+    summary: "Serve an image from R2 storage",
+    responses: {
+      200: { description: "Image file" },
+      404: { description: "Image not found" }
+    }
+  }),
+  async (c) => {
+    const bucket = c.env.FILES;
+    if (!bucket) {
+      throw serviceUnavailable("File storage (R2) is not configured.");
+    }
+    const path = c.req.path.split("/uploads/images/")[1];
+    if (!path) throw notFound("Image");
+    const object = await bucket.get(path);
+    if (!object) throw notFound("Image");
+    const headers = {
+      etag: object.httpEtag,
+      // Cache at the edge/browser for 1 month
+      "Cache-Control": "public, max-age=2592000, immutable"
+    };
+    if (object.httpMetadata?.contentType) {
+      headers["Content-Type"] = object.httpMetadata.contentType;
+    }
+    if (object.httpMetadata?.cacheControl) {
+      headers["Cache-Control"] = object.httpMetadata.cacheControl;
+    }
+    return c.body(object.body, 200, headers);
   }
-  return c.body(object.body, 200, headers);
-});
+);
 uploadsRoute.post(
   "/images",
+  describeRoute({
+    tags: ["Uploads"],
+    summary: "Upload an image to R2 storage (admin)",
+    responses: {
+      201: { description: "Image uploaded successfully" },
+      400: { description: "Invalid file or MIME type" },
+      503: { description: "R2 storage not configured" }
+    }
+  }),
   authMiddleware,
   adminMiddleware,
   async (c) => {
@@ -1861,16 +2206,33 @@ z.object({
   sortOrder: z.number().int().optional()
 });
 var themesRoute = new Hono();
-themesRoute.get("/", async (c) => {
-  const db = createDb(c.env.DB);
-  const data = await db.select().from(themes).orderBy(asc(themes.sortOrder), asc(themes.createdAt));
-  return c.json({ data });
-});
+themesRoute.get(
+  "/",
+  describeRoute({
+    tags: ["Themes"],
+    summary: "List all themes",
+    responses: { 200: { description: "List of themes" } }
+  }),
+  async (c) => {
+    const db = createDb(c.env.DB);
+    const data = await db.select().from(themes).orderBy(asc(themes.sortOrder), asc(themes.createdAt));
+    return c.json({ data });
+  }
+);
 themesRoute.post(
   "/",
+  describeRoute({
+    tags: ["Themes"],
+    summary: "Create a new theme (admin)",
+    responses: {
+      201: { description: "Theme created" },
+      409: { description: "Theme already exists" },
+      422: { description: "Validation error" }
+    }
+  }),
   authMiddleware,
   adminMiddleware,
-  zValidator("json", createThemeSchema),
+  validator("json", createThemeSchema),
   async (c) => {
     const body = c.req.valid("json");
     const db = createDb(c.env.DB);
@@ -1888,6 +2250,15 @@ themesRoute.post(
 );
 themesRoute.patch(
   "/:id",
+  describeRoute({
+    tags: ["Themes"],
+    summary: "Update a theme (admin)",
+    responses: {
+      200: { description: "Theme updated" },
+      404: { description: "Theme not found" },
+      409: { description: "Theme already exists" }
+    }
+  }),
   authMiddleware,
   adminMiddleware,
   async (c) => {
@@ -1910,13 +2281,26 @@ themesRoute.patch(
     }
   }
 );
-themesRoute.delete("/:id", authMiddleware, adminMiddleware, async (c) => {
-  const { id } = c.req.param();
-  const db = createDb(c.env.DB);
-  const [deleted] = await db.delete(themes).where(eq(themes.id, id)).returning();
-  if (!deleted) throw notFound("Theme");
-  return c.body(null, 204);
-});
+themesRoute.delete(
+  "/:id",
+  describeRoute({
+    tags: ["Themes"],
+    summary: "Delete a theme (admin)",
+    responses: {
+      204: { description: "Theme deleted" },
+      404: { description: "Theme not found" }
+    }
+  }),
+  authMiddleware,
+  adminMiddleware,
+  async (c) => {
+    const { id } = c.req.param();
+    const db = createDb(c.env.DB);
+    const [deleted] = await db.delete(themes).where(eq(themes.id, id)).returning();
+    if (!deleted) throw notFound("Theme");
+    return c.body(null, 204);
+  }
+);
 var createOrganizationSchema = z.object({
   name: z.string().min(1),
   acronym: z.string().min(1),
@@ -1924,16 +2308,33 @@ var createOrganizationSchema = z.object({
   link: z.string().url().nullable().optional()
 });
 var organizationsRoute = new Hono();
-organizationsRoute.get("/", async (c) => {
-  const db = createDb(c.env.DB);
-  const data = await db.select().from(organizations);
-  return c.json({ data });
-});
+organizationsRoute.get(
+  "/",
+  describeRoute({
+    tags: ["Organizations"],
+    summary: "List all organizations",
+    responses: { 200: { description: "List of organizations" } }
+  }),
+  async (c) => {
+    const db = createDb(c.env.DB);
+    const data = await db.select().from(organizations);
+    return c.json({ data });
+  }
+);
 organizationsRoute.post(
   "/",
+  describeRoute({
+    tags: ["Organizations"],
+    summary: "Create a new organization (admin)",
+    responses: {
+      201: { description: "Organization created" },
+      409: { description: "Organization already exists" },
+      422: { description: "Validation error" }
+    }
+  }),
   authMiddleware,
   adminMiddleware,
-  zValidator("json", createOrganizationSchema),
+  validator("json", createOrganizationSchema),
   async (c) => {
     const body = c.req.valid("json");
     const db = createDb(c.env.DB);
@@ -1950,6 +2351,15 @@ organizationsRoute.post(
 );
 organizationsRoute.patch(
   "/:id",
+  describeRoute({
+    tags: ["Organizations"],
+    summary: "Update an organization (admin)",
+    responses: {
+      200: { description: "Organization updated" },
+      404: { description: "Organization not found" },
+      409: { description: "Organization already exists" }
+    }
+  }),
   authMiddleware,
   adminMiddleware,
   async (c) => {
@@ -1968,13 +2378,26 @@ organizationsRoute.patch(
     }
   }
 );
-organizationsRoute.delete("/:id", authMiddleware, adminMiddleware, async (c) => {
-  const { id } = c.req.param();
-  const db = createDb(c.env.DB);
-  const [deleted] = await db.delete(organizations).where(eq(organizations.id, id)).returning();
-  if (!deleted) throw notFound("Organization");
-  return c.body(null, 204);
-});
+organizationsRoute.delete(
+  "/:id",
+  describeRoute({
+    tags: ["Organizations"],
+    summary: "Delete an organization (admin)",
+    responses: {
+      204: { description: "Organization deleted" },
+      404: { description: "Organization not found" }
+    }
+  }),
+  authMiddleware,
+  adminMiddleware,
+  async (c) => {
+    const { id } = c.req.param();
+    const db = createDb(c.env.DB);
+    const [deleted] = await db.delete(organizations).where(eq(organizations.id, id)).returning();
+    if (!deleted) throw notFound("Organization");
+    return c.body(null, 204);
+  }
+);
 
 // src/app.ts
 function createApp(options = {}) {
@@ -2032,6 +2455,27 @@ function createApp(options = {}) {
   app.route("/internal/batch-release", batchReleaseRoute);
   app.route("/internal/reminder-emails", reminderEmailsRoute);
   app.route("/internal/renew-watches", renewWatchesRoute);
+  app.get(
+    "/api/openapi.json",
+    authMiddleware,
+    adminMiddleware,
+    openAPIRouteHandler(app, {
+      documentation: {
+        info: {
+          title: "Leapify API",
+          version: "0.260605.1" ,
+          description: "DLSU CSO LEAP backend API"
+        },
+        openapi: "3.1.0"
+      }
+    })
+  );
+  app.get(
+    "/api/docs",
+    authMiddleware,
+    adminMiddleware,
+    swaggerUI({ url: "/api/openapi.json" })
+  );
   app.onError(errorHandler);
   app.notFound(
     (c) => c.json({ error: { code: "NOT_FOUND", message: "Route not found" } }, 404)
@@ -2652,6 +3096,8 @@ var API_PREFIXES = [
   "/api/themes",
   "/api/config",
   "/api/uploads",
+  "/api/docs",
+  "/api/openapi.json",
   "/health",
   "/internal/",
   "/.well-known/"