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
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@ Format: [Keep a Changelog](https://keepachangelog.com/); versioning: [SemVer](ht
## [Unreleased]

### Added
- Answer reuse: an identical question returns the stored answer (no AI call, about 1 s) until a session changes or 24 hours pass; `pnpm prewarm` warms the demo (Phase 25)
- Voice question: a microphone in the Ask bar, English or Hindi, using the browser's speech recognition (Phase 25)
- Installable app: web app manifest, icons, shortcuts and an offline page (Phase 25)
- 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)
Expand All @@ -15,6 +18,9 @@ Format: [Keep a Changelog](https://keepachangelog.com/); versioning: [SemVer](ht
- 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
- The `Permissions-Policy` header blocked the microphone on every page; it now allows it for Pravaha's own pages (Phase 25)
- Hindi answers ended sentences with the Chinese full stop (。) instead of the danda (।)
- Smoke tests: the anonymous-upload check sends well-formed params, and the Ask check tolerates two "Source 1" buttons on mobile
- `/search` (Find and Ask results) crashed with "Something went wrong" since the data saver release: `ResultCard` called a client hook without `"use client"`. Fixed, with a unit test that fails the build for any hook used outside a client file
- 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)

Expand Down
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,8 @@ Colleges, clubs and coaching institutes record hundreds of hours of lectures and
| **Weak spots** | Quiz mistakes are remembered on your device and come back as **one Cloudinary reel of exactly the explanations you missed**, with the answer and the second to jump to. Get a question right and it leaves the list. |
| **Study notes** | Every session has a study sheet at `/notes/[id]`: summary, key concepts, chapters and the quiz with answers, each point linked to its timestamp. Copy it as Markdown, download it, or save it as a PDF. |
| **Revision reel** | On `/saved`, the latest saved moments from any sessions play as one labelled video: a revision reel for the night before an exam. |
| **Voice** | Tap the microphone in the Ask bar and say the question, in English or Hindi. The browser turns speech into text, so no audio reaches Pravaha. |
| **Installable** | Add Pravaha to a phone's home screen; it opens full-screen and shows a friendly page when offline. |
| **Study Packs** | Every session gets a summary, key concepts, a quiz whose explanations **play the moment** the teacher explains it, and a "Session in 60 seconds" highlight reel. Pravaha generates them automatically from the transcript. |
| **Moments** | One tap turns any cited clip into a vertical, AI-cropped, subtitled short for WhatsApp or Instagram, with its own share page and preview card. The short is just a Cloudinary URL; nothing is rendered. |
| **Insights** | Organizers see what learners ask, the **knowledge gaps** the library can't answer yet (what to record next), and which Moments get shared. Every report downloads as CSV. Visitors can explore a read-only demo of the Studio. |
Expand Down Expand Up @@ -223,6 +225,8 @@ Open the live app at **[pravaha-cyan.vercel.app](https://pravaha-cyan.vercel.app
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.

10. Tap the **microphone** in the Ask bar (Chrome or Safari) and ask by voice, or switch it to Hindi with the EN / हिं button.

## Quick start

**Prerequisites:**
Expand Down
5 changes: 5 additions & 0 deletions docs/API.md
Original file line number Diff line number Diff line change
Expand Up @@ -175,3 +175,8 @@ Retrieval now rewrites a question into the library's vocabulary when it is in an
- **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

## Phase 25 additions

### `POST /api/ask` (answer reuse)
An identical question (normalised: case, whitespace and trailing punctuation ignored) in the same scope (the whole library, or the same `lectureId`) is answered from the stored answer when it is under 24 hours old and no session has been added, published or changed since. The response is the stored one plus `"cached": true`, with the same `answerId`. No AI call is made and the rate limit still applies.
1 change: 1 addition & 0 deletions docs/DATABASE.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,7 @@ Transcripts can identify people. Logs reference `lectureId`, never transcript te
| `003_study_packs_insights.sql` | `study_packs` (one validated pack per session), `ask_log` (question text + outcome, **no identity**), `moment_events` (anonymous open/share counts) |
| `005_trials.sql` | `lectures.trial_expires_at`, `lectures.trial_ip_hash` (salted hash, rate limiting only) and a check that trials stay `unlisted`: public trial sessions from `/try`, deleted with their Cloudinary assets after expiry (`src/lib/trials.ts`) |
| `004_shared_answers.sql` | `answers`: each answered Ask stored as shown (random 10-character id, question, result JSONB) for the share page `/a/[id]`, plus anonymous `helpful` / `unhelpful` counters. **No identity** |
| `007_answer_cache.sql` | `answers.question_key` (the normalised question) and `answers.lecture_id` (the session an Ask was scoped to, NULL for the whole library) plus an index, so an identical recent question can reuse its stored answer. Older rows have NULLs and are never matched |

Applied with `pnpm db:migrate` (tracked in `schema_migrations`, each file once, in a transaction).

Expand Down
4 changes: 4 additions & 0 deletions docs/DEMO.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,10 @@ 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.")

**Before recording:** run `APP_URL=https://pravaha-cyan.vercel.app pnpm prewarm` so every demo question answers instantly and every reel is already generated.

**Voice shot (10 s):** tap the microphone and ask in Hindi ("The question is spoken, the answer comes back in Hindi.")

**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."
Expand Down
1 change: 1 addition & 0 deletions docs/IMPLEMENTATION_PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,3 +99,4 @@ The core loop (Phases 01–09) is built and verified on real Cloudinary + Neon.
| 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) |
| 25 | Answer reuse, voice questions, installable app | Identical questions reuse the stored answer (no AI call); ask by voice in English or Hindi; manifest, icons and an offline page; Hindi punctuation fix | ✅ done (Oct 3) |
2 changes: 1 addition & 1 deletion docs/SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,4 +81,4 @@ Rights confirmation is required before upload (`rights_confirmed_at`), sessions

## HTTP Security Headers

Every response carries (`next.config.ts`): `Strict-Transport-Security` (2 years, subdomains, preload), `X-Content-Type-Options: nosniff`, `Referrer-Policy: strict-origin-when-cross-origin`, `X-Frame-Options: DENY` plus `Content-Security-Policy: frame-ancestors 'none'; base-uri 'self'; form-action 'self'; object-src 'none'` (no clickjacking, no base-tag or plugin injection; the one exception is `/embed/*`, the sign-in-free Ask box an LMS frames, whose `frame-ancestors` is `https:` or the `EMBED_FRAME_ANCESTORS` list; see [`EMBED.md`](EMBED.md)), and a `Permissions-Policy` that turns off camera, microphone, geolocation, payment and USB. `X-Powered-By` is removed. A full script-source CSP is deliberately not set yet: the Cloudinary Video Player loads scripts, styles and HLS segments from several hosts, so that policy needs testing against every player feature first.
Every response carries (`next.config.ts`): `Strict-Transport-Security` (2 years, subdomains, preload), `X-Content-Type-Options: nosniff`, `Referrer-Policy: strict-origin-when-cross-origin`, `X-Frame-Options: DENY` plus `Content-Security-Policy: frame-ancestors 'none'; base-uri 'self'; form-action 'self'; object-src 'none'` (no clickjacking, no base-tag or plugin injection; the one exception is `/embed/*`, the sign-in-free Ask box an LMS frames, whose `frame-ancestors` is `https:` or the `EMBED_FRAME_ANCESTORS` list; see [`EMBED.md`](EMBED.md)), and a `Permissions-Policy` that turns off camera, geolocation, payment and USB and allows the microphone for Pravaha's own pages only (the voice question: audio never reaches Pravaha, the browser turns it into text). `X-Powered-By` is removed. A full script-source CSP is deliberately not set yet: the Cloudinary Video Player loads scripts, styles and HLS segments from several hosts, so that policy needs testing against every player feature first.
1 change: 1 addition & 0 deletions docs/SUBMISSION_CHECKLIST.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ Deadline: submit by **Oct 3, 2026**; code freeze **Oct 4, 00:15 IST**. Submit vi
- [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)
- [ ] Run `pnpm prewarm` against production shortly before judging and before recording the demo (answers are reused for 24 hours or until a session changes, so run it after the last publish)
- [ ] **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
23 changes: 23 additions & 0 deletions docs/phases/PHASE-25-answer-cache-voice-pwa.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# Phase 25 — Answer reuse, voice questions, installable app

**Status: DONE (Oct 3)** · branch `feature/answer-cache-voice-ask-pwa`

## Why
Three things that decide whether a live demo and a real learner's phone work: judges will ask the *same* suggested questions (each one a fresh AI call against a free-tier quota), most learners hold a phone not a keyboard, and a web app that can't be installed feels like a website.

## What shipped
1. **Answer reuse** (`migrations/007_answer_cache.sql`, `src/lib/answers.ts`, `src/lib/question-key.ts`): an identical question (case, spacing and a trailing "?" ignored) in the same scope returns the stored answer, with the same citations and share link, with **no retrieval and no AI call**. A repeat took about 1 s against about 12 s cold, and spends no Gemini or Groq quota. A reused answer expires after 24 hours and, more importantly, **whenever any session is added, published or changed** (`answers.created_at >= max(lectures.updated_at)`), so it can never cite a library that has since changed. A session-scoped Ask is never served to a library-wide one. Reused answers still count in Insights. Best-effort: any failure just means the question is answered normally. `pnpm prewarm` (`scripts/prewarm.mjs`) asks the demo questions and opens their reels so the first judge gets instant results; it stops if Cloudinary credits are above 90%.
2. **Voice question** (`src/components/VoiceButton.tsx`, `src/lib/voice.ts`): a microphone in the Ask bar, English (India) or Hindi, using the browser's own speech recognition. The words appear as they are heard and the question is asked when the speaker stops. Audio never reaches Pravaha. Hidden in browsers without speech recognition (Firefox). Plain-language messages for blocked microphone, silence, no microphone and no network. **The site's `Permissions-Policy` had `microphone=()`, which would have blocked it everywhere; it is now `microphone=(self)`.**
3. **Installable app** (`src/app/manifest.ts`, `src/app/pwa-icon/[size]/route.tsx`, `public/sw.js`, `/offline`): a web app manifest, 192 / 512 / maskable PNG icons drawn from the logo, shortcuts (Ask, Learn, Saved) and an offline page. The service worker is deliberately tiny: it caches **one page** (`/offline`) and answers only failed navigations. It caches no scripts, API responses or video, so a deploy can never leave anyone on stale code. Registered in production only.
4. **Hindi punctuation:** models sometimes ended Hindi sentences with the Chinese full stop (。). They now end with the danda (।) (Bengali and Punjabi too; a plain full stop for other scripts).

## Decisions
- Reuse is keyed on the normalised question text, not on meaning. Two differently worded questions are two answers: a cheap, predictable rule beats an embedding lookup that could serve the wrong answer.
- The invalidation rule errs toward answering again: any lecture change anywhere clears the cache, which is rare in a demo and always safe.
- No push notifications and no asset caching in the service worker: the offline page is the whole job.

## Verification
- 160 unit tests (12 new: question key, punctuation, voice helpers).
- Live against the real database: three phrasings of one question gave one answer id, 12.1 s then 1.4 s then 0.8 s.
- Real browser with a simulated recogniser: the spoken question reaches `/search?q=…` and an answer appears; the button is absent without speech support; the bar fits a 360 px phone.
- Manifest, all three icons (visually checked), `sw.js` headers and `/offline` verified.
8 changes: 8 additions & 0 deletions migrations/007_answer_cache.sql
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
-- Answer reuse: an identical question gets the stored answer back instead of another AI call.
-- question_key is the question normalised (src/lib/question-key.ts); lecture_id is the session an Ask was
-- scoped to (NULL = the whole library), so a session-scoped answer is never served to a library-wide ask.
-- Older rows have NULLs, so they are never matched. Backwards compatible: code from before this migration
-- keeps working (it just doesn't fill the new columns).
ALTER TABLE answers ADD COLUMN question_key TEXT;
ALTER TABLE answers ADD COLUMN lecture_id UUID;
CREATE INDEX idx_answers_cache ON answers (question_key, created_at DESC) WHERE question_key IS NOT NULL;
11 changes: 10 additions & 1 deletion next.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,8 @@ const baseHeaders = [
{ key: "Strict-Transport-Security", value: "max-age=63072000; includeSubDomains; preload" },
{ key: "X-Content-Type-Options", value: "nosniff" },
{ key: "Referrer-Policy", value: "strict-origin-when-cross-origin" },
{ key: "Permissions-Policy", value: "camera=(), microphone=(), geolocation=(), payment=(), usb=()" },
// microphone=(self): only Pravaha's own pages may ask for it, which the voice question needs (components/VoiceButton.tsx).
{ key: "Permissions-Policy", value: "camera=(), microphone=(self), geolocation=(), payment=(), usb=()" },
];
const policy = (ancestors: string) => `frame-ancestors ${ancestors}; base-uri 'self'; form-action 'self'; object-src 'none'`;

Expand All @@ -31,6 +32,14 @@ const nextConfig: NextConfig = {
{ key: "Content-Security-Policy", value: policy("'none'") },
],
},
// The service worker must always be re-fetched, so a fix to it reaches every device on the next visit.
{
source: "/sw.js",
headers: [
{ key: "Cache-Control", value: "no-cache, no-store, must-revalidate" },
{ key: "Service-Worker-Allowed", value: "/" },
],
},
{ source: "/embed/:path*", headers: [{ key: "Content-Security-Policy", value: policy(embedAncestors) }] },
];
},
Expand Down
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
"test": "vitest run",
"test:e2e": "playwright test",
"eval:ask": "node scripts/eval-ask.mjs",
"prewarm": "node scripts/prewarm.mjs",
"db:migrate": "node scripts/migrate.mjs",
"spike": "node scripts/spike.mjs",
"e2e:local": "node scripts/e2e-local.mjs",
Expand Down
23 changes: 23 additions & 0 deletions public/sw.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
// Pravaha's service worker, deliberately tiny: it makes the app installable and gives a friendly page when a
// navigation fails because the device is offline. It caches ONE page (/offline) and nothing else: no scripts,
// no API responses, no video, so a deploy can never leave anyone on stale code.
const CACHE = "pravaha-offline-v1";
const OFFLINE_URL = "/offline";

self.addEventListener("install", (event) => {
event.waitUntil(caches.open(CACHE).then((cache) => cache.add(new Request(OFFLINE_URL, { cache: "reload" }))));
self.skipWaiting();
});

self.addEventListener("activate", (event) => {
event.waitUntil(
caches.keys().then((keys) => Promise.all(keys.filter((k) => k !== CACHE).map((k) => caches.delete(k)))).then(() => self.clients.claim()),
);
});

self.addEventListener("fetch", (event) => {
if (event.request.mode !== "navigate") return; // everything else goes straight to the network
event.respondWith(
fetch(event.request).catch(async () => (await caches.match(OFFLINE_URL)) ?? Response.error()),
);
});
Loading
Loading