From 096e68c3814a44f8df6c3f8357e761837c456a26 Mon Sep 17 00:00:00 2001 From: im-rk Date: Sat, 3 Oct 2026 14:51:59 +0530 Subject: [PATCH 1/3] feat(status): a public status page with live health, AI model probes and Cloudinary credits --- src/app/api/status/route.ts | 12 +++ src/app/layout.tsx | 4 + src/app/sitemap.ts | 1 + src/app/status/page.tsx | 169 ++++++++++++++++++++++++++++++++ src/lib/status-level.ts | 40 ++++++++ src/lib/status.ts | 137 ++++++++++++++++++++++++++ tests/e2e/status.spec.ts | 23 +++++ tests/unit/status-level.test.ts | 46 +++++++++ 8 files changed, 432 insertions(+) create mode 100644 src/app/api/status/route.ts create mode 100644 src/app/status/page.tsx create mode 100644 src/lib/status-level.ts create mode 100644 src/lib/status.ts create mode 100644 tests/e2e/status.spec.ts create mode 100644 tests/unit/status-level.test.ts diff --git a/src/app/api/status/route.ts b/src/app/api/status/route.ts new file mode 100644 index 0000000..1c9c7cf --- /dev/null +++ b/src/app/api/status/route.ts @@ -0,0 +1,12 @@ +import { NextResponse } from "next/server"; + +import { getStatus } from "@/lib/status"; + +export const dynamic = "force-dynamic"; + +// The same data as /status: public, aggregate and secret-free. 200 unless the database is unreachable (503), +// so an uptime monitor can watch it. AI probes and Cloudinary usage are cached server-side (src/lib/status.ts). +export async function GET() { + const status = await getStatus(); + return NextResponse.json(status, { status: status.level === "outage" ? 503 : 200, headers: { "Cache-Control": "no-store" } }); +} diff --git a/src/app/layout.tsx b/src/app/layout.tsx index 6f7479c..4f8f9ba 100644 --- a/src/app/layout.tsx +++ b/src/app/layout.tsx @@ -107,6 +107,10 @@ export default function RootLayout({ children }: { children: React.ReactNode }) Terms {" "} + ·{" "} + + Status + {" "} · Built on Cloudinary · Team Code Blooded ·{" "} GitHub diff --git a/src/app/sitemap.ts b/src/app/sitemap.ts index e858ce7..41f32fc 100644 --- a/src/app/sitemap.ts +++ b/src/app/sitemap.ts @@ -18,6 +18,7 @@ export default async function sitemap(): Promise { { url: `${base}/learn`, changeFrequency: "monthly", priority: 0.6 }, { url: `${base}/concepts`, changeFrequency: "weekly", priority: 0.7 }, { url: `${base}/judges`, changeFrequency: "monthly", priority: 0.5 }, + { url: `${base}/status`, changeFrequency: "always", priority: 0.3 }, { url: `${base}/try`, changeFrequency: "monthly", priority: 0.6 }, { url: `${base}/privacy`, changeFrequency: "yearly", priority: 0.2 }, { url: `${base}/terms`, changeFrequency: "yearly", priority: 0.2 }, diff --git a/src/app/status/page.tsx b/src/app/status/page.tsx new file mode 100644 index 0000000..be559c2 --- /dev/null +++ b/src/app/status/page.tsx @@ -0,0 +1,169 @@ +import type { Metadata } from "next"; +import { Suspense } from "react"; + +import { aiStatus, fastStatus, verdict, type FastStatus } from "@/lib/status"; +import type { FailureKind, Overall } from "@/lib/status-level"; + +export const dynamic = "force-dynamic"; + +export const metadata: Metadata = { + title: "Status — Pravaha", + description: "Live health of Pravaha: the database, every AI model, Cloudinary credits and what the library holds.", +}; + +const HEADLINE: Record = { + operational: { text: "All systems operational", tone: "border-ready/50 bg-ready/10 text-ready" }, + degraded: { text: "Degraded: working, with a problem", tone: "border-processing/50 bg-processing/10 text-processing" }, + outage: { text: "Outage", tone: "border-failed/50 bg-failed/10 text-failed" }, +}; + +const KIND: Record = { quota: "quota or rate limit", overloaded: "provider overloaded", error: "error" }; + +const card = "rounded-2xl border border-border bg-surface p-5"; +const h2 = "text-sm font-semibold tracking-wide text-muted uppercase"; + +function Dot({ ok }: { ok: boolean }) { + return ; +} + +// The quick checks render at once; the AI probe (five small model calls, cached for 5 minutes) streams in after. +export default async function StatusPage() { + const fast = await fastStatus(); + const c = fast.cloudinary; + const bar = c ? (c.level === "critical" ? "bg-failed" : c.level === "warn" ? "bg-processing" : "bg-accent") : ""; + + return ( +
+

Status

+

Pravaha checks itself live: the database, every AI model and the Cloudinary credits the media runs on.

+ + }> + + + +
+
+

+ Database +

+

+ + {fast.database.ok ? "Reachable" : "Unreachable"} + {fast.database.ms} ms +

+

Neon Postgres: sessions, time-coded moments and the full-text index.

+
+ +
+

+ Cloudinary credits +

+ {c ? ( + <> +

+ + {c.used.toFixed(1)} of {c.limit} + + {c.pct}% used +

+
+
+
+

+ Transformations {c.transformations.toFixed(2)} · storage {c.storage.toFixed(2)} · bandwidth {c.bandwidth.toFixed(2)} + {c.reportedOn ? ` · reported ${c.reportedOn}` : ""} +

+ + ) : ( +

Usage couldn't be read right now.

+ )} +
+
+ + }> + + + + {fast.library && ( +
+

+ In the library +

+
+ {[ + [fast.library.sessions, "published sessions"], + [fast.library.moments, "moments indexed"], + [fast.library.studyPacks, "Study Packs"], + [fast.library.questionsAsked, "questions asked"], + ].map(([n, label]) => ( +
+
{n}
+
{label}
+
+ ))} +
+
+ )} + +

+ Version {fast.version} · checked {new Date(fast.checkedAt).toLocaleTimeString("en-IN")} · JSON at{" "} + /api/status +

+
+ ); +} + +async function Verdict({ fast }: { fast: FastStatus }) { + const { level, reasons } = verdict(fast, await aiStatus()); + const head = HEADLINE[level]; + return ( +
+

{head.text}

+ {reasons.map((r) => ( +

+ {r} +

+ ))} +
+ ); +} + +async function AiCard() { + const ai = await aiStatus(); + const up = ai.models?.filter((m) => m.ok).length ?? 0; + return ( +
+

+ AI models +

+ {ai.models ? ( + <> +

+ {up} of {ai.models.length} answering. Ask tries them in order, so one failing model doesn't stop answers. If all fail, it shows the closest clips. +

+
    + {ai.models.map((m) => ( +
  • + + + {m.model} + + {m.ok ? `${m.ms} ms` : m.kind ? KIND[m.kind] : "error"} +
  • + ))} +
+ {ai.probedAt &&

Probed {new Date(ai.probedAt).toLocaleTimeString("en-IN")}; refreshed every 5 minutes.

} + + ) : ( +

No AI provider is configured. Ask shows the most relevant clips without an AI answer.

+ )} +
+ ); +} diff --git a/src/lib/status-level.ts b/src/lib/status-level.ts new file mode 100644 index 0000000..926871c --- /dev/null +++ b/src/lib/status-level.ts @@ -0,0 +1,40 @@ +// How the public status page turns raw checks into one plain verdict. Pure, so it is unit-tested. + +export type CreditLevel = "ok" | "warn" | "critical"; +export type Overall = "operational" | "degraded" | "outage"; + +export const CREDIT_WARN_PCT = 80; +export const CREDIT_CRITICAL_PCT = 95; + +export function creditLevel(usedPct: number): CreditLevel { + return usedPct >= CREDIT_CRITICAL_PCT ? "critical" : usedPct >= CREDIT_WARN_PCT ? "warn" : "ok"; +} + +// Public pages show a category, never a raw provider error. +export type FailureKind = "quota" | "overloaded" | "error"; + +export function failureKind(message: string | undefined): FailureKind { + if (!message) return "error"; + if (/\b(401|403|429)\b|RESOURCE_EXHAUSTED|PERMISSION_DENIED|quota|rate.?limit/i.test(message)) return "quota"; + if (/\b(500|502|503|504)\b|UNAVAILABLE|high demand|overloaded/i.test(message)) return "overloaded"; + return "error"; +} + +type Inputs = { + database: boolean; + aiConfigured: boolean; + aiOk: number | null; // models answering, or null when no live probe is available + aiTotal: number; + credits: CreditLevel | null; // null when Cloudinary's usage couldn't be read +}; + +// outage: learners can't be served (no database). degraded: the product works but something that matters is +// failing, so say so (no AI model answering means Ask falls back to showing clips; credits nearly gone means +// new clips and reels could stop). Anything else is operational; individual model failures are shown, not alarmed. +export function overallStatus({ database, aiConfigured, aiOk, aiTotal, credits }: Inputs): { level: Overall; reasons: string[] } { + if (!database) return { level: "outage", reasons: ["The database isn't reachable."] }; + const reasons: string[] = []; + if (aiConfigured && aiTotal > 0 && aiOk === 0) reasons.push("No AI model is answering. Ask falls back to showing the most relevant clips."); + if (credits === "critical") reasons.push("Cloudinary credits are almost used up. New clips and reels may stop generating."); + return { level: reasons.length ? "degraded" : "operational", reasons }; +} diff --git a/src/lib/status.ts b/src/lib/status.ts new file mode 100644 index 0000000..16c95c2 --- /dev/null +++ b/src/lib/status.ts @@ -0,0 +1,137 @@ +import "server-only"; + +import { probeModels } from "@/lib/ai"; +import { cld } from "@/lib/cloudinary"; +import { query } from "@/lib/db"; +import { env } from "@/lib/env"; +import { log } from "@/lib/log"; +import { creditLevel, failureKind, overallStatus, type CreditLevel, type FailureKind, type Overall } from "@/lib/status-level"; + +// The public status page's data: database, every AI model, Cloudinary credits and what the library holds. +// Expensive checks are cached per server instance so a busy page can't spend tokens or API calls: +// AI probes (five tiny calls) every 5 minutes, Cloudinary's usage report every 10. + +const AI_TTL_MS = 5 * 60_000; +const USAGE_TTL_MS = 10 * 60_000; +const DB_TIMEOUT_MS = 3000; + +function cached(ttlMs: number, load: () => Promise): () => Promise { + let value: { at: number; data: T } | null = null; + let inflight: Promise | null = null; + return async () => { + if (value && Date.now() - value.at < ttlMs) return value.data; + inflight ??= load() + .then((data) => { + value = { at: Date.now(), data }; + return data; + }) + .finally(() => { + inflight = null; + }); + return inflight; + }; +} + +export type ModelStatus = { model: string; ok: boolean; ms: number; kind?: FailureKind }; +export type CloudinaryUsage = { + used: number; + limit: number; + pct: number; + level: CreditLevel; + transformations: number; + storage: number; + bandwidth: number; + reportedOn: string | null; +}; + +const aiModels = cached(AI_TTL_MS, async (): Promise<{ models: ModelStatus[]; at: string } | null> => { + const { GEMINI_API_KEY, GROQ_API_KEY } = env(); + if (!GEMINI_API_KEY && !GROQ_API_KEY) return null; + try { + const probes = await probeModels(); + return { at: new Date().toISOString(), models: probes.map((p) => ({ model: p.model, ok: p.ok, ms: p.ms, ...(p.ok ? {} : { kind: failureKind(p.error) }) })) }; + } catch (error) { + log("status.ai_probe_failed", { error: error instanceof Error ? error.message.slice(0, 120) : String(error) }); + return null; + } +}); + +const cloudinaryUsage = cached(USAGE_TTL_MS, async (): Promise => { + try { + const u = await cld().api.usage(); + const used = Number(u.credits?.usage ?? 0); + const limit = Number(u.credits?.limit ?? 0); + if (!limit) return null; + const pct = Math.round((used / limit) * 1000) / 10; + return { + used, + limit, + pct, + level: creditLevel(pct), + transformations: Number(u.transformations?.credits_usage ?? 0), + storage: Number(u.storage?.credits_usage ?? 0), + bandwidth: Number(u.bandwidth?.credits_usage ?? 0), + reportedOn: typeof u.last_updated === "string" ? u.last_updated : null, + }; + } catch (error) { + log("status.usage_failed", { error: error instanceof Error ? error.message.slice(0, 120) : String(error) }); + return null; + } +}); + +async function database(): Promise<{ ok: boolean; ms: number }> { + const started = Date.now(); + const ok = await Promise.race([query("SELECT 1").then(() => true), new Promise((r) => setTimeout(() => r(false), DB_TIMEOUT_MS))]).catch(() => false); + return { ok, ms: Date.now() - started }; +} + +async function libraryCounts() { + const [row] = await query<{ sessions: string; moments: string; packs: string; asked: string }>( + `SELECT (SELECT count(*) FROM lectures WHERE status = 'ready' AND visibility = 'public' AND trial_expires_at IS NULL) AS sessions, + (SELECT count(*) FROM segments s JOIN lectures l ON l.id = s.lecture_id + WHERE l.status = 'ready' AND l.visibility = 'public' AND l.trial_expires_at IS NULL) AS moments, + (SELECT count(*) FROM study_packs) AS packs, + (SELECT count(*) FROM ask_log) AS asked`, + ); + return { sessions: Number(row?.sessions ?? 0), moments: Number(row?.moments ?? 0), studyPacks: Number(row?.packs ?? 0), questionsAsked: Number(row?.asked ?? 0) }; +} + +type Library = { sessions: number; moments: number; studyPacks: number; questionsAsked: number }; + +export type AiStatus = { providers: string[]; models: ModelStatus[] | null; probedAt: string | null }; + +export const aiStatus = async (): Promise => { + const { GEMINI_API_KEY, GROQ_API_KEY } = env(); + const ai = await aiModels(); + return { + providers: [GEMINI_API_KEY && "gemini", GROQ_API_KEY && "groq"].filter((p): p is string => Boolean(p)), + models: ai?.models ?? null, + probedAt: ai?.at ?? null, + }; +}; + +// The quick checks (milliseconds), so the page can show them while the slower AI probe is still running. +export type FastStatus = { version: string; checkedAt: string; database: { ok: boolean; ms: number }; cloudinary: CloudinaryUsage | null; library: Library | null }; + +export async function fastStatus(): Promise { + const [db, cloudinary] = await Promise.all([database(), cloudinaryUsage()]); + const library = db.ok ? await libraryCounts().catch(() => null) : null; + return { version: process.env.VERCEL_GIT_COMMIT_SHA?.slice(0, 7) ?? "local", checkedAt: new Date().toISOString(), database: db, cloudinary, library }; +} + +export function verdict(fast: FastStatus, ai: AiStatus): { level: Overall; reasons: string[] } { + return overallStatus({ + database: fast.database.ok, + aiConfigured: ai.providers.length > 0, + aiOk: ai.models ? ai.models.filter((m) => m.ok).length : null, + aiTotal: ai.models?.length ?? 0, + credits: fast.cloudinary?.level ?? null, + }); +} + +export type Status = FastStatus & { ai: AiStatus; level: Overall; reasons: string[] }; + +export async function getStatus(): Promise { + const [fast, ai] = await Promise.all([fastStatus(), aiStatus()]); + return { ...verdict(fast, ai), ...fast, ai }; +} diff --git a/tests/e2e/status.spec.ts b/tests/e2e/status.spec.ts new file mode 100644 index 0000000..8830e75 --- /dev/null +++ b/tests/e2e/status.spec.ts @@ -0,0 +1,23 @@ +import { expect, test } from "@playwright/test"; + +// The public status page and its JSON twin (run against the deployed app, like smoke.spec.ts). + +test("the status page shows a verdict, the database, Cloudinary credits and the AI models", async ({ page }) => { + await page.goto("/status"); + await expect(page.getByRole("heading", { name: "Status", exact: true })).toBeVisible(); + await expect(page.getByRole("status")).toContainText(/operational|degraded|outage/i); + await expect(page.getByRole("heading", { name: "Database" })).toBeVisible(); + await expect(page.getByRole("heading", { name: "Cloudinary credits" })).toBeVisible(); + await expect(page.getByRole("heading", { name: "AI models" })).toBeVisible(); +}); + +test("/api/status is secret-free JSON an uptime monitor can watch", async ({ request }) => { + const res = await request.get("/api/status"); + expect([200, 503]).toContain(res.status()); + const body = await res.json(); + expect(["operational", "degraded", "outage"]).toContain(body.level); + expect(typeof body.database.ok).toBe("boolean"); + expect(body.cloudinary === null || typeof body.cloudinary.pct === "number").toBe(true); + const text = JSON.stringify(body); + expect(text).not.toMatch(/api[_-]?key|secret|postgres:\/\/|gsk_|AIza/i); +}); diff --git a/tests/unit/status-level.test.ts b/tests/unit/status-level.test.ts new file mode 100644 index 0000000..c9482f8 --- /dev/null +++ b/tests/unit/status-level.test.ts @@ -0,0 +1,46 @@ +import { describe, expect, it } from "vitest"; + +import { creditLevel, failureKind, overallStatus } from "@/lib/status-level"; + +const healthy = { database: true, aiConfigured: true, aiOk: 5, aiTotal: 5, credits: "ok" as const }; + +describe("creditLevel", () => { + it("warns at 80% and goes critical at 95%", () => { + expect([0, 79.9, 80, 94.9, 95, 100].map(creditLevel)).toEqual(["ok", "ok", "warn", "warn", "critical", "critical"]); + }); +}); + +describe("failureKind", () => { + it("shows a category, never the raw error", () => { + expect(failureKind('{"error":{"code":429,"message":"quota exceeded"}}')).toBe("quota"); + expect(failureKind("RESOURCE_EXHAUSTED")).toBe("quota"); + expect(failureKind('{"error":{"code":503,"message":"This model is currently experiencing high demand"}}')).toBe("overloaded"); + expect(failureKind("invalid JSON")).toBe("error"); + expect(failureKind(undefined)).toBe("error"); + }); +}); + +describe("overallStatus", () => { + it("is operational when everything works, and when only some models are down", () => { + expect(overallStatus(healthy)).toEqual({ level: "operational", reasons: [] }); + expect(overallStatus({ ...healthy, aiOk: 2 }).level).toBe("operational"); + expect(overallStatus({ ...healthy, credits: "warn" }).level).toBe("operational"); + }); + + it("is an outage when the database is down", () => { + expect(overallStatus({ ...healthy, database: false }).level).toBe("outage"); + }); + + it("is degraded, with a plain reason, when no AI model answers or credits are nearly gone", () => { + const noAi = overallStatus({ ...healthy, aiOk: 0 }); + expect(noAi.level).toBe("degraded"); + expect(noAi.reasons[0]).toMatch(/closest|relevant clips/i); + expect(overallStatus({ ...healthy, credits: "critical" }).reasons[0]).toMatch(/credits/i); + expect(overallStatus({ ...healthy, aiOk: 0, credits: "critical" }).reasons).toHaveLength(2); + }); + + it("doesn't alarm about AI when none is configured or no probe is available", () => { + expect(overallStatus({ ...healthy, aiConfigured: false, aiOk: null, aiTotal: 0 }).level).toBe("operational"); + expect(overallStatus({ ...healthy, aiOk: null, aiTotal: 0, credits: null }).level).toBe("operational"); + }); +}); From e0d95f5da0cbd298b56da87681a4eec1f4363c74 Mon Sep 17 00:00:00 2001 From: im-rk Date: Sat, 3 Oct 2026 14:51:59 +0530 Subject: [PATCH 2/3] docs(business): who pays, unit economics, pricing hypothesis and a whole-system diagram --- README.md | 65 +++++++++++++++++++++++++++++++++++++------- docs/ARCHITECTURE.md | 50 ++++++++++++++++++++++++++++++++++ docs/BUSINESS.md | 53 ++++++++++++++++++++++++++++++++++++ docs/COST.md | 2 ++ 4 files changed, 160 insertions(+), 10 deletions(-) create mode 100644 docs/BUSINESS.md diff --git a/README.md b/README.md index d0070b4..c371e0c 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,7 @@ Hackathon project by Team Code Blooded - [hackindia-team:pixels-to-products-clou - [What Pravaha does](#what-pravaha-does) - [Screenshots](#screenshots) - [How Cloudinary powers it](#how-cloudinary-powers-it) +- [Business case](#business-case) - [Architecture](#architecture) - [How to test it](#how-to-test-it) - [Quick start](#quick-start) @@ -141,19 +142,62 @@ Every session page and answer has a **Cloudinary under the hood** panel that lis Full detail: [`docs/CLOUDINARY.md`](docs/CLOUDINARY.md). +## Business case + +Track 3 asks for something you could pitch. Pravaha's pitch, in short (full version, with every number tagged actual, estimate or assumption: [`docs/BUSINESS.md`](docs/BUSINESS.md)): + +- **Who pays:** coaching institutes first (their recorded classes are their product, and doubts cost teacher time), then college departments, then companies with recorded trainings. +- **Why it wins:** the answer is a clip of *their own teacher* saying it, never a chatbot's guess; it says "not covered" instead of bluffing, and that becomes a knowledge-gap report. Each institute's corpus and learner questions become a moat. +- **Why Cloudinary's pricing fits:** no transcoding farm, no GPUs. Transcripts, chapters, streams, crops, reels and share cards are generated on demand and cached, so cost follows what is *watched*, not what is stored. Hosting one hour of content is about 28.8 Cloudinary credits if every rendition is generated, and Ask costs a fraction of a cent. +- **Pricing hypothesis (to validate, nobody has paid yet):** a free pilot for one batch, then a one-time processing fee per content-hour plus a monthly fee per active learner. +- **The binding constraint, shown live:** Cloudinary credits. [`/status`](https://pravaha-cyan.vercel.app/status) shows usage and warns at 80% and 95%. + ## Architecture ```mermaid -flowchart LR - O[Organizer · Studio] -- signed upload --> C[(Cloudinary)] - C -- signed webhook --> API[Next.js API on Vercel] - API -- segments + full-text index --> DB[(Neon Postgres)] - L[Learner] -- question --> API - API -- retrieve --> DB - API -- top segments --> G[Gemini · Groq backup] - G -- answer + citations --> API - API -- validated citations + clip URLs --> L - C -- HLS · Moments · Reels · thumbnails --> L +flowchart TB + subgraph Org["Organizer"] + O["Studio · upload · Insights"] + end + subgraph Learn["Learner · phone or laptop"] + L["Ask · Find · Watch · Concepts · Learn · Saved · Notes"] + end + + subgraph Cloudinary["Cloudinary: the media plane"] + U["Signed upload preset"] + AI["auto_transcription · auto_chaptering · hi-IN translate"] + T["Transformations on demand: Moments · Reels · cards · previews · data saver"] + S["HLS streaming · f_auto · q_auto"] + X["Tags + context + Search API"] + end + + subgraph App["Next.js 16 on Vercel: the knowledge plane"] + W["Signed webhook"] + R["Retrieval · question understanding"] + G["Grounded answer + citation validation"] + P["Study Packs · Learning Paths · Concept Map · Notes"] + ST["/status · /api/health"] + end + + DB[("Neon Postgres: segments · full-text index · packs · insights")] + M["Gemini → Groq fallback chain · circuit breaker"] + + O -- video bytes, signed --> U + U --> AI + AI -- webhook --> W + W -- time-coded segments --> DB + W -- study pack --> P + P -- tags and context --> X + L -- question --> R + R --> DB + R --> G + G <--> M + G -- validated citations + clip URLs --> L + T -- clips · reels · shorts --> L + S -- adaptive video --> L + ST -. checks .-> DB + ST -. checks .-> M + ST -. credits .-> Cloudinary ``` - **One Next.js 16 app** (App Router: frontend and API together), deployed on Vercel. @@ -177,6 +221,7 @@ Open the live app at **[pravaha-cyan.vercel.app](https://pravaha-cyan.vercel.app 6. Press `/` or `Ctrl/⌘ K` anywhere to jump to the Ask bar. 7. Open **[Try it](https://pravaha-cyan.vercel.app/try)** and upload any short video with speech (up to 50 MB). Follow the live pipeline, then ask it "What is this video about?" on its page. 8. Open **[Studio](https://pravaha-cyan.vercel.app/studio)**: a read-only demo of the organizer side, with every session's pipeline output and live Insights (knowledge gaps, most asked questions, answers rated helpful). Uploading to the main library and publishing need the organizer passcode at `/studio/sign-in`. +9. Open **[Status](https://pravaha-cyan.vercel.app/status)**: live database health, every AI model, and the Cloudinary credits the media runs on. ## Quick start diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index be60d89..c2bdd5b 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -2,6 +2,56 @@ Read `PRD.md`, `CLOUDINARY.md` and `TRD.md` first; these diagrams show those decisions in motion. +## 0. Whole system (Oct 3) + +The current shape of the product, including Learning Paths, the Concept Map, study notes, data saver, the Cloudinary asset index and the status page. The diagrams below it are the original design views. + +```mermaid +flowchart TB + subgraph Org["Organizer"] + O["Studio · upload · Insights"] + end + subgraph Learn["Learner · phone or laptop"] + L["Ask · Find · Watch · Concepts · Learn · Saved · Notes"] + end + + subgraph Cloudinary["Cloudinary: the media plane"] + U["Signed upload preset"] + AI["auto_transcription · auto_chaptering · hi-IN translate"] + T["Transformations on demand: Moments · Reels · cards · previews · data saver"] + S["HLS streaming · f_auto · q_auto"] + X["Tags + context + Search API"] + end + + subgraph App["Next.js 16 on Vercel: the knowledge plane"] + W["Signed webhook"] + R["Retrieval · question understanding"] + G["Grounded answer + citation validation"] + P["Study Packs · Learning Paths · Concept Map · Notes"] + ST["/status · /api/health"] + end + + DB[("Neon Postgres: segments · full-text index · packs · insights")] + M["Gemini → Groq fallback chain · circuit breaker"] + + O -- video bytes, signed --> U + U --> AI + AI -- webhook --> W + W -- time-coded segments --> DB + W -- study pack --> P + P -- tags and context --> X + L -- question --> R + R --> DB + R --> G + G <--> M + G -- validated citations + clip URLs --> L + T -- clips · reels · shorts --> L + S -- adaptive video --> L + ST -. checks .-> DB + ST -. checks .-> M + ST -. credits .-> Cloudinary +``` + ## 1. System Context ```mermaid diff --git a/docs/BUSINESS.md b/docs/BUSINESS.md new file mode 100644 index 0000000..7bf4fc7 --- /dev/null +++ b/docs/BUSINESS.md @@ -0,0 +1,53 @@ +# Business case — Pravaha + +Track 3 asks for something you could pitch as a startup. This is the pitch, with every number tagged **ACTUAL** (measured or fixed by a plan's mechanics), **ESTIMATE** (derived from ACTUAL figures) or **ASSUMPTION** (a hypothesis to validate). No customer has paid yet; the pricing below is a hypothesis for design-partner conversations, not a result. + +## The problem, in one line +Institutions record hundreds of hours of lectures, classes and talks that nobody rewatches, because nothing inside a video can be found. Learners ask a chatbot instead, and get an answer with no source and no teacher. + +## Who pays +| Customer | Why they pay | How Pravaha helps | +|---|---|---| +| **Coaching institutes** (first wedge) | Their recorded classes are their product. Doubts cost teacher time, and a searchable archive is a retention and sales tool | "Ask any doubt, get your own teacher's answer as a clip." Knowledge gaps tell them what to re-teach | +| **College departments** | Lecture capture is already paid for but unused | The archive becomes searchable, askable and shareable; Insights show what students didn't understand | +| **Companies** (later) | Recorded trainings and all-hands are write-only | Same pipeline on internal recordings | + +**Who uses it:** students on phones and mobile data (hence data saver, Hindi, vertical Moments), and organizers who upload and read Insights. + +## Why this is hard to copy +- **The answer is a video of the teacher, not text.** Every claim links to a Cloudinary-cut clip of the moment it was said. A general chatbot can't do this because it doesn't have the institute's recordings. +- **It refuses to bluff.** Answers are validated against retrieved moments, and "not covered" is a first-class result that becomes a knowledge-gap report. +- **A growing moat:** each institute's corpus, its curated Moments, and what its learners actually ask. That is data no general tool has. +- **A growth loop:** every shared Moment is a branded vertical clip on WhatsApp or Instagram that links back to the full session. + +## Why Cloudinary's usage pricing fits +A video product normally needs a transcoding farm, GPU speech-to-text, an image service and a CDN. Pravaha has none of them: Cloudinary does the transcript, the chapters, the adaptive streams, the AI crops, the reels and the share cards, **on demand, only when someone asks, then cached on the CDN**. So cost follows what is actually watched, not what is stored, and a new institute adds usage, not infrastructure. + +## Unit economics +| Item | Figure | Tag | +|---|---|---| +| Streaming ladder (`hd_lean`) | about 8 transformations per second of video, so **28.8 credits per hour of content** if every rendition is generated, once | **ACTUAL** mechanics (`COST.md`) | +| Data-saver ladder (`sd`) | generated only the first time someone views in that mode | **ACTUAL** | +| Credit price | about $0.40 (a paid plan around $89 for 225 credits); verify on cloudinary.com/pricing | **ASSUMPTION** | +| **Cost to host one hour of content** | **about $11.50 worst case** (all of it watched), about $3.50 if a third is watched, plus Cloudinary's transcription and chaptering add-ons (not priced here; check the account) | **ESTIMATE** | +| Cost of one Ask | a fraction of a cent (about 2–3k tokens on a Flash-class model) | **ASSUMPTION** (`COST.md`) | +| Clips, reels, Moments, previews | generated on first request, then CDN-cached; hover previews and reels cost only when used | **ACTUAL** design | + +What keeps it cheap, all built: `hd_lean` instead of a six-rendition ladder, lazy generation of everything derived, 60-second caps on public trial uploads, 5-clip and 90-second caps on reels, and data saver. + +## Pricing hypothesis (to validate) +| Plan | Price | For | +|---|---|---| +| **Pilot** | free for one department or batch, up to 20 hours | design partners; the feedback is the price | +| **Institute** | processing per content-hour (one-time, about ₹1,500) plus a monthly fee per active learner | coaching institutes, colleges | +| **Enterprise** | per seat, private libraries, SSO | companies, later | + +Check against the unit costs above: ₹1,500 is about $18 at current exchange rates, against $3.50–$11.50 to host an hour, so processing alone covers hosting even in the worst case, and the per-learner fee pays for delivery and Ask. **ASSUMPTION** throughout. + +## Where it goes +Near-term (built or designed): institute workspaces and multiple organizers, more Indian-language subtitles, LMS embeds (built), quiz and weak-spot revision (built). The full roadmap is in [`VISION.md`](VISION.md). + +## Honest risks +- **Cloudinary credits are the binding constraint on the free plan** (25 per month; the status page at `/status` shows the live figure and warns at 80% and 95%). +- **AI free tiers rate-limit.** Ask walks a chain of Gemini and Groq models with a circuit breaker, and falls back to showing the closest clips. +- **Rights.** Organizers confirm they have the right to publish a recording; trials are private and deleted after 24 hours. diff --git a/docs/COST.md b/docs/COST.md index 2ca4e10..92fe32f 100644 --- a/docs/COST.md +++ b/docs/COST.md @@ -17,4 +17,6 @@ Free tiers cover everything except Gemini beyond its free tier, whose worst case ## At Scale (pitch answer) +The full unit-economics and pricing hypothesis are in [`BUSINESS.md`](BUSINESS.md); live credit use is at `/status`. + Cost per institute scales with minutes uploaded (Cloudinary transcription + storage), minutes watched (delivery) and questions asked (Gemini) — all usage-priced, all passed through in a per-seat or per-hour-of-content plan (`VISION.md`). From 54563d66cd6b6ebd45f429d4a133f466935ad4d3 Mon Sep 17 00:00:00 2001 From: im-rk Date: Sat, 3 Oct 2026 14:52:00 +0530 Subject: [PATCH 3/3] docs(phase-24): status page, API, observability, judges page and changelog --- CHANGELOG.md | 8 +++++--- docs/API.md | 7 +++++++ docs/DEMO.md | 2 ++ docs/IMPLEMENTATION_PLAN.md | 1 + docs/OBSERVABILITY.md | 4 ++++ docs/SUBMISSION_CHECKLIST.md | 2 ++ .../PHASE-24-status-page-business-case.md | 20 +++++++++++++++++++ openapi.yaml | 8 ++++++++ src/app/judges/page.tsx | 1 + 9 files changed, 50 insertions(+), 3 deletions(-) create mode 100644 docs/phases/PHASE-24-status-page-business-case.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 16ab1f8..caf5bf4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,10 +4,9 @@ Format: [Keep a Changelog](https://keepachangelog.com/); versioning: [SemVer](ht ## [Unreleased] -### Fixed -- Phone header: Studio, data saver and the theme switch were off-screen below ~560 px. Header, Studio and /try now fit 360 px (Phase 23) - ### Added +- Public status page `/status` and `GET /api/status`: live database, every AI model and Cloudinary credits, with warnings at 80% and 95% (Phase 24) +- Business case (`docs/BUSINESS.md`, README) and one whole-system architecture diagram (Phase 24) - Weak spots on Saved: wrong quiz answers become a personal revision reel of the explanations you missed (Phase 22) - Study notes `/notes/[id]` and `GET /api/lectures/[id]/notes`: a timestamp-linked study sheet per session, as Markdown or PDF (Phase 22) - Data saver: a header switch (automatic on Save-Data and 2G/3G) that serves lighter Cloudinary renditions and the `sd` streaming ladder; 33–76% fewer bytes measured (Phase 21) @@ -15,6 +14,9 @@ Format: [Keep a Changelog](https://keepachangelog.com/); versioning: [SemVer](ht - Concept Map `/concepts` and Compare view `/concepts/[key]`: the same concept from every teacher as one Compare Reel (Phase 19) - Cloudinary asset index: tags and contextual metadata on each session's asset, synced from the Studio and read back with the Search API (Phase 19) +### Fixed +- Phone header: Studio, data saver and the theme switch were off-screen below ~560 px. Header, Studio and /try now fit 360 px (Phase 23) + ## [1.0.0] — 2026-10-03 The hackathon submission. Live at https://pravaha-cyan.vercel.app; PR numbers refer to `Monolithic-Dev/Pravaha`. diff --git a/docs/API.md b/docs/API.md index cb78633..c734024 100644 --- a/docs/API.md +++ b/docs/API.md @@ -168,3 +168,10 @@ Retrieval now rewrites a question into the library's vocabulary when it is in an - **Query:** `format=md` returns Markdown (`text/markdown`); add `download=1` for a `Content-Disposition: attachment` `.md` file. Without `format`, JSON - **Response (JSON):** `{ title, speaker, durationS, watchUrl, summary[], concepts[{ name, t, label, url }], chapters[{ title, t, label, url }], quiz[{ question, answer, explanation, t, label, url }] }`; every `url` opens the session at that second - **Errors:** `404` the session isn't ready, doesn't exist, or has no summary, chapters or quiz yet + +## Phase 24 additions + +### `GET /api/status` +- **Auth:** public, `Cache-Control: no-store` +- **Response:** `{ level: "operational"|"degraded"|"outage", reasons[], version, checkedAt, database: { ok, ms }, ai: { providers[], models: [{ model, ok, ms, kind? }] | null, probedAt }, cloudinary: { used, limit, pct, level, transformations, storage, bandwidth, reportedOn } | null, library: { sessions, moments, studyPacks, questionsAsked } | null }` +- `503` only when the database is unreachable. AI probes are cached 5 minutes and Cloudinary usage 10 minutes per server instance. `kind` is `quota`, `overloaded` or `error`, never a raw provider message. No secrets or config values diff --git a/docs/DEMO.md b/docs/DEMO.md index ccf6f79..06a7f26 100644 --- a/docs/DEMO.md +++ b/docs/DEMO.md @@ -28,6 +28,8 @@ Never show setup, code, dashboards or waiting. Every shot is the problem, the pr **Study shots (if there is time):** answer a quiz question wrong → `/saved` → **Play my weak-spot reel** ("What you get wrong comes back as video.") → a session’s **Study notes** → **Download .md** ("Every point links to the second the teacher said it.") +**Proof shot (10 s):** open `/status`: "The product watches itself: database, every AI model and the Cloudinary credits it runs on." + **Bonus shot (if there is time):** header → **Data saver** on → the same answer reel and thumbnails reload visibly lighter. Voice-over: "Built for India’s mobile data: one switch, and Cloudinary serves everything at a fraction of the bytes." ## Phase 18–20 scenes (Oct 3) — swap in for the 2:06–2:35 shots if time is tight diff --git a/docs/IMPLEMENTATION_PLAN.md b/docs/IMPLEMENTATION_PLAN.md index a6b5a5a..42bd9d3 100644 --- a/docs/IMPLEMENTATION_PLAN.md +++ b/docs/IMPLEMENTATION_PLAN.md @@ -98,3 +98,4 @@ The core loop (Phases 01–09) is built and verified on real Cloudinary + Neon. | 22 | Weak spots & study notes | Quiz mistakes become a personal revision reel; every session exports a timestamp-linked study sheet (Markdown / print) | ✅ done (Oct 3) | | 20 | Judges page & revision reel | `/judges` maps the brief to Cloudinary capabilities with live URLs; saved moments replay as one reel | ✅ done (Oct 3) | | 23 | Phone layout | Header, Studio and /try fit a 360 px phone; e2e guard | ✅ done (Oct 3) | +| 24 | Status page & business case | Live health, AI probes and Cloudinary credits at `/status`; who pays, unit economics and pricing hypothesis; whole-system diagram | ✅ done (Oct 3) | diff --git a/docs/OBSERVABILITY.md b/docs/OBSERVABILITY.md index 927727c..7554e16 100644 --- a/docs/OBSERVABILITY.md +++ b/docs/OBSERVABILITY.md @@ -24,6 +24,10 @@ Never logged: transcript text, questions verbatim (only length), IPs, secrets. - Ask status mix — a rising `fallback` or `not_found` share means a broken prompt or retrieval - `dropped` citations per answer — how often the model tried to cite something it wasn't given (should be ~0) +## The public status page + +`/status` (and `GET /api/status`, `503` only when the database is unreachable) shows what the logs would tell you, live: database reachability, a real probe of every AI model (five tiny calls, cached 5 minutes per server instance), and Cloudinary credits with warnings at 80% and 95% (the usage report is cached 10 minutes). Failures show a category (quota, overloaded, error), never a raw provider message. An uptime monitor can watch `/api/status`. + ## Error tracking, tracing, monitoring Vercel's function logs and analytics. No Sentry, no tracing backend — `lectureId` on every line is the trace at this scale. Considered and declined, not forgotten. diff --git a/docs/SUBMISSION_CHECKLIST.md b/docs/SUBMISSION_CHECKLIST.md index 1581d54..375e9ac 100644 --- a/docs/SUBMISSION_CHECKLIST.md +++ b/docs/SUBMISSION_CHECKLIST.md @@ -15,6 +15,8 @@ Deadline: submit by **Oct 3, 2026**; code freeze **Oct 4, 00:15 IST**. Submit vi - [x] Learner flows (Watch, Find, Ask, Moments) work without login (Oct 2: Playwright smoke tests 12/12 against production, desktop and mobile) - [x] Demo library: 6 public sessions (NPTEL excerpts, CC BY-NC-SA, credited in the README), uploaded through the production pipeline on Oct 2 - [x] Organizer and enterprise features merged and checked on Vercel previews (Oct 2–3): demo Studio, Insights charts and CSV export, LMS embed, Privacy and Terms, health endpoint +- [x] Public status page `/status` shows live credits (warns at 80% and 95%), AI model health and database reachability (Phase 24) +- [x] Business case for the Track 3 pitch: `docs/BUSINESS.md` and the README (Phase 24) - [ ] **Cloudinary credits:** the Admin API reported 14.1 of 25 used (56%) at its last update (Oct 2). Every new reel, Moment and Compare Reel spends some, so avoid regenerating them in bulk before judging, and re-check `api.usage()` on submission day - [ ] Trials decision after that: keep `/try` paused (`TRIALS_PER_DAY=0`) or re-enable (`TRIALS_PER_DAY=5`, then redeploy) diff --git a/docs/phases/PHASE-24-status-page-business-case.md b/docs/phases/PHASE-24-status-page-business-case.md new file mode 100644 index 0000000..2e8d5c9 --- /dev/null +++ b/docs/phases/PHASE-24-status-page-business-case.md @@ -0,0 +1,20 @@ +# Phase 24 — Status page and business case + +**Status: DONE (Oct 3)** · branch `feature/status-page-business-case` + +## Why +Two gaps a judge would notice. Track 3 is "a startup you could pitch", but the repo had no business model. And the product depends on things that can silently run out (Cloudinary credits, AI free-tier quotas) with nothing watching them. + +## What shipped +1. **Public status page** (`/status`, `GET /api/status`; `src/lib/status.ts`, `src/lib/status-level.ts`): one verdict (operational, degraded, outage), database reachability, a real probe of every AI model, Cloudinary credits with warnings at 80% and 95%, and what the library holds. The quick checks render at once and the AI probe streams in. Probes are cached per server instance (AI 5 minutes, Cloudinary usage 10) so a busy page cannot spend tokens or API calls. Failures show a category (quota, overloaded, error), never a raw provider message. The verdict rules are pure and unit-tested: no database is an outage; no AI model answering or credits above 95% is degraded; some models down is shown but not alarmed. +2. **Business case** (`docs/BUSINESS.md`, README "Business case"): who pays, why it is hard to copy, why Cloudinary's usage pricing fits, unit economics and a pricing hypothesis. Every number is tagged ACTUAL, ESTIMATE or ASSUMPTION, and the page says plainly that nobody has paid yet. +3. **One architecture diagram** of the whole system (README and `docs/ARCHITECTURE.md` section 0), including the knowledge/media plane split, the fallback AI chain and the status checks. + +## Decisions +- No uptime history. A page that shows a "99.9%" it didn't measure is worse than none; `/api/status` is built for an external monitor to record it. +- The status page is public and shows credit usage: it holds no secret, and the transparency is the point. +- Cost per hour is given as a range with its assumptions, not a single confident number: `28.8` credits per content-hour if every rendition is generated is mechanics, the dollar figure is an assumption to verify. + +## Verification +- 6 new unit tests for the verdict rules. +- Live against the real database, Cloudinary and AI models: verdict "operational", database reachable, credits 15.4 of 25 (61.6%), five of five models answering, 6 sessions / 72 moments / 8 Study Packs. diff --git a/openapi.yaml b/openapi.yaml index 89d22a0..3ff9a8d 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -504,3 +504,11 @@ paths: responses: '200': { description: Notes as JSON, or Markdown with format=md, content: { application/json: { schema: { type: object } }, text/markdown: { schema: { type: string } } } } '404': { description: No notes for this session, content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } } + /status: + get: + summary: Live status, the database, every AI model, Cloudinary credits and library size + operationId: getStatus + security: [{}] + responses: + '200': { description: Operational or degraded, content: { application/json: { schema: { type: object } } } } + '503': { description: Outage, the database is unreachable, content: { application/json: { schema: { type: object } } } } diff --git a/src/app/judges/page.tsx b/src/app/judges/page.tsx index e5e0132..d8f9945 100644 --- a/src/app/judges/page.tsx +++ b/src/app/judges/page.tsx @@ -20,6 +20,7 @@ const REQUIREMENTS: [string, string][] = [ ["Upload, manage, transform, optimize, search, deliver", "Signed upload · tags and context · Search API · splice, crop, caption, preview transformations · f_auto/q_auto · HLS delivery."], ["A live working demo", "This site. Six real NPTEL sessions, no login for learners."], ["Public repo with setup instructions", "github.com/Monolithic-Dev/Pravaha, SETUP.md."], + ["It is monitored, and a real business", "/status shows live database, AI model and Cloudinary-credit health. The business case is in docs/BUSINESS.md and the README."], ["README: track, problem, Cloudinary usage, how to test", "Track 3 (Your Media-Savvy Startup); see the README."], ];