Freezmo: self-hosted notes-to-activities study app

Next.js 15 app that turns photos, PDFs, DOCX/PPTX and text into a swipeable
feed of AI-generated activities (flashcards, multiple choice, true/false,
fill-in-the-blank, matching, ordering, short answer) using the user's own
Ollama models.

Highlights:
- All AI calls run in server route handlers; the browser never talks to Ollama.
- Bring-your-own-key mode (default): the key lives only in the browser and is
  sent per-request; server, local-daemon and shared-key modes also supported.
- Client-side document extraction (pdf.js, mammoth, jszip) with scanned-PDF
  page rendering for the vision model; notes stay in their original language.
- ChatGPT-style shell: collapsible sidebar / mobile drawer, neutral token-based
  light + dark themes, folder organisation, PWA (manifest, SW, offline page).
- Strict JSON validation with zod + auto-repair, rate limiting, and request
  guards (cross-origin, body-size, API-key sanitising).
- setup.sh bootstraps deps, .env.local and a production build.

Gitignore excludes .env*, the generated pdf.js worker and local scratch files.

lib/rate-limit.ts

@@ -0,0 +1,106 @@
+/**
+ * In-memory sliding-window rate limiter.
+ *
+ * Deliberately dependency-free and good enough for a self-hosted, single
+ * instance app: each key (route + client IP) gets N requests per window.
+ * Counters live in memory and reset on restart, and a busy instance cannot
+ * share state with others — fine for Freezmo, documented in the README.
+ */
+
+type Hits = { timestamps: number[] };
+
+/**
+ * Kept on globalThis so dev-mode hot reloads (and any module re-evaluation)
+ * don't silently reset everybody's counters.
+ */
+const globalStore = globalThis as unknown as { __freezmoRateLimit?: Map<string, Hits> };
+const buckets: Map<string, Hits> = (globalStore.__freezmoRateLimit ??= new Map());
+const MAX_BUCKETS = 5_000;
+
+export type RateLimitResult = {
+  allowed: boolean;
+  limit: number;
+  remaining: number;
+  /** Seconds until the oldest hit falls out of the window (0 when allowed). */
+  retryAfter: number;
+  resetAt: number;
+};
+
+export function rateLimit(key: string, limit: number, windowMs: number): RateLimitResult {
+  const now = Date.now();
+  const windowStart = now - windowMs;
+
+  let bucket = buckets.get(key);
+  if (!bucket) {
+    if (buckets.size >= MAX_BUCKETS) prune(now, windowMs);
+    bucket = { timestamps: [] };
+    buckets.set(key, bucket);
+  }
+
+  bucket.timestamps = bucket.timestamps.filter((timestamp) => timestamp > windowStart);
+
+  if (bucket.timestamps.length >= limit) {
+    const oldest = bucket.timestamps[0];
+    const retryAfter = Math.max(1, Math.ceil((oldest + windowMs - now) / 1000));
+    return {
+      allowed: false,
+      limit,
+      remaining: 0,
+      retryAfter,
+      resetAt: oldest + windowMs,
+    };
+  }
+
+  bucket.timestamps.push(now);
+  return {
+    allowed: true,
+    limit,
+    remaining: Math.max(0, limit - bucket.timestamps.length),
+    retryAfter: 0,
+    resetAt: now + windowMs,
+  };
+}
+
+/** Drop stale buckets so long-running servers don't grow without bound. */
+function prune(now: number, windowMs: number): void {
+  const cutoff = now - windowMs;
+  for (const [key, bucket] of buckets) {
+    if (bucket.timestamps.length === 0 || bucket.timestamps[bucket.timestamps.length - 1] < cutoff) {
+      buckets.delete(key);
+    }
+    if (buckets.size < MAX_BUCKETS / 2) break;
+  }
+}
+
+/** Best-effort client identity: proxy headers first, then a shared bucket. */
+export function clientKey(request: Request): string {
+  const forwarded = request.headers.get("x-forwarded-for");
+  if (forwarded) {
+    const first = forwarded.split(",")[0]?.trim();
+    if (first) return first;
+  }
+  return (
+    request.headers.get("x-real-ip") ??
+    request.headers.get("cf-connecting-ip") ??
+    "local"
+  );
+}
+
+export function rateLimitResponse(result: RateLimitResult, message?: string): Response {
+  return Response.json(
+    {
+      error:
+        message ??
+        `Too many requests — this app allows ${result.limit} per window. Try again in ${result.retryAfter}s.`,
+      kind: "rate_limited",
+      retryAfter: result.retryAfter,
+    },
+    {
+      status: 429,
+      headers: {
+        "Retry-After": String(result.retryAfter),
+        "Cache-Control": "no-store",
+      },
+    },
+  );
+}