Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,17 +4,19 @@ 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)
- `/judges`: the submission requirements mapped to 14 Cloudinary capabilities, live URLs and a 90-second test; revision reel on `/saved` (Phase 20)
- 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`.
Expand Down
65 changes: 55 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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.
Expand All @@ -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

Expand Down
7 changes: 7 additions & 0 deletions docs/API.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
50 changes: 50 additions & 0 deletions docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
53 changes: 53 additions & 0 deletions docs/BUSINESS.md
Original file line number Diff line number Diff line change
@@ -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.
2 changes: 2 additions & 0 deletions docs/COST.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`).
2 changes: 2 additions & 0 deletions docs/DEMO.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
1 change: 1 addition & 0 deletions docs/IMPLEMENTATION_PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -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) |
4 changes: 4 additions & 0 deletions docs/OBSERVABILITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 2 additions & 0 deletions docs/SUBMISSION_CHECKLIST.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
Loading
Loading