From ccfcd277270e5f07b88a780f402f0125a7ffae5a Mon Sep 17 00:00:00 2001 From: Mahakisore7 Date: Sun, 20 Sep 2026 18:24:24 +0530 Subject: [PATCH 1/7] docs: add AWS Builder Center article fields and cover-image prompt Ready-to-paste title/description/tags for the "Create an article" form, plus an image-generation prompt for the optional cover image (abstract, no text/logos, AWS orange + indigo palette) since that field needs an actual uploaded file this repo can't produce on its own. Co-Authored-By: Claude Sonnet 5 --- docs/SUBMISSION-FORM.md | 49 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/docs/SUBMISSION-FORM.md b/docs/SUBMISSION-FORM.md index 3a41030..b774d81 100644 --- a/docs/SUBMISSION-FORM.md +++ b/docs/SUBMISSION-FORM.md @@ -110,6 +110,55 @@ the PN-Counter/vector-clock design decisions, the load-bearing hardening pass caught. Nothing left to do but publish it and paste the link._ +### AWS Builder Center "Create an article" form — ready-to-paste fields + +**Title** (short, descriptive, unique): + +``` +Two billing counters, one bad connection, and the bug that erases a sale +``` + +**Description** (1–2 sentences, doesn't repeat the title): + +``` +How a hackathon inventory-sync engine uses vector clocks, a PN-Counter +CRDT, and SQS FIFO ordering on AWS to guarantee two offline point-of-sale +counters can never silently overwrite each other's sales — plus a real +concurrency bug a dedicated hardening pass caught before launch. +``` + +**Tags** (pick the closest 5 available in the dropdown — it's a +controlled vocabulary, so exact matches may not exist): + +``` +AWS, Serverless, DynamoDB, TypeScript, Distributed Systems +``` + +**Body:** copy the full contents of [`docs/BLOG-POST.md`](BLOG-POST.md) +(everything after the title line) into the body editor — it's already +written in Markdown, and the editor's toolbar shows a Markdown cheatsheet +that confirms the same syntax (headers, bold, code fences, links) works +as-is. No reformatting needed. + +**Cover image (optional, 1200×675px, no text in the image):** this field +needs an actual image file, which I can't generate directly. Use the +prompt below in an image generator (e.g. Midjourney, DALL·E, Stable +Diffusion) and upload the result: + +``` +A clean, modern tech-editorial illustration for a software engineering +blog post about distributed systems and offline data synchronization. +Two abstract point-of-sale terminal icons on the left and right, each +glowing softly, connected by flowing data-stream lines that merge into a +single glowing node in the center, symbolizing conflict-free merge of +concurrent data. Isometric flat-design style, dark navy background +(#0F1629) with vibrant orange (#FF9900) and indigo (#4F46E5) accent +lighting on the connection lines and nodes. Minimalist, high-contrast, +no text, no logos, no people, no wordmarks — purely abstract +geometric/network shapes. 1200x675 landscape aspect ratio, suitable as a +blog cover image. +``` + --- ## Team leader's contributions * From 29cf822fe791fa7820ef038601b7ea0a987f07d5 Mon Sep 17 00:00:00 2001 From: Mahakisore7 Date: Sun, 20 Sep 2026 18:28:06 +0530 Subject: [PATCH 2/7] docs: replace the blog post's wide ASCII diagram with a vertical step list MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The boxed ASCII architecture diagram forced horizontal scrolling in the AWS Builder Center article editor (screenshotted: only ~half the diagram fit before the code block cut off). Blog platforms aren't guaranteed to render Mermaid the way GitHub does, so this replaces it with an ordered list that reads the same pipeline top to bottom with no fixed-width box-drawing characters — renders correctly in any Markdown editor. Co-Authored-By: Claude Sonnet 5 --- docs/BLOG-POST.md | 36 +++++++++++++++++++++++------------- 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/docs/BLOG-POST.md b/docs/BLOG-POST.md index 317c988..ead7413 100644 --- a/docs/BLOG-POST.md +++ b/docs/BLOG-POST.md @@ -70,19 +70,29 @@ advisory-only: it explains, it never decides. ## The architecture, and why each piece is load-bearing -``` -StockSync Counter (React, IndexedDB offline queue) - │ POST /transactions ▲ WSS live push - ▼ │ -API Gateway (REST + WebSocket) - │ - ▼ -Lambda: write-intake → SQS FIFO (MessageGroupId = item_id) → Lambda: conflict-resolver - │ idempotency check │ vector-clock / PN-Counter merge - │ │ TransactWriteItems (record + audit + dedup) - ▼ │ Bedrock explanation (non-blocking) - Amazon DynamoDB ▼ -``` +A write makes one trip down this pipeline, and the live push back to +every open counter is a separate hop off the same event: + +1. **StockSync Counter** (React, IndexedDB offline queue) sends + `POST /transactions` — queued locally first, so a flaky connection + never blocks a sale. +2. **API Gateway** (REST) receives it and hands off to Lambda. +3. **Lambda `write-intake`** does the idempotency check, then enqueues. +4. **SQS FIFO**, grouped by `MessageGroupId = item_id` — not by which + counter sent it — so every write touching one item is processed in + strict order, no matter how many counters are concurrently active. +5. **Lambda `conflict-resolver`** does the actual merge: vector-clock + comparison, PN-Counter arithmetic for stock, field-level merge for + everything else. It commits the record, its audit-log entry, and its + idempotency claim together via `TransactWriteItems`, and — only on a + genuine same-field conflict — asks **Amazon Bedrock** for a + plain-language explanation, non-blocking. +6. **Amazon DynamoDB** is the single source of truth the whole pipeline + converges on. +7. A DynamoDB Streams event off that same write fans out through + **API Gateway's WebSocket API** as a live push (`WSS`) back to every + other open counter — so a second screen sees the new stock count + arrive without ever polling for it. The detail that matters most and is easiest to get wrong: the **SQS FIFO queue's `MessageGroupId` is the inventory item's ID, not the sending From 47b56ce8cc1b474893482298b93e312900eff01b Mon Sep 17 00:00:00 2001 From: Mahakisore7 Date: Sun, 20 Sep 2026 18:30:22 +0530 Subject: [PATCH 3/7] docs: split submission-form team contributions across three members MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replaces the solo-build draft with role-based splits across the three team members (Maha Kisore, Ramkumar, Yashwanth) — correctness core/CDK, client/auth/UI, and observability/notifications/AI respectively. Still flagged for the team to review and adjust before submitting, since this is a drafted split rather than a verified record of who did what. Co-Authored-By: Claude Sonnet 5 --- docs/SUBMISSION-FORM.md | 47 ++++++++++++++++++++++++++++------------- 1 file changed, 32 insertions(+), 15 deletions(-) diff --git a/docs/SUBMISSION-FORM.md b/docs/SUBMISSION-FORM.md index b774d81..6c46a64 100644 --- a/docs/SUBMISSION-FORM.md +++ b/docs/SUBMISSION-FORM.md @@ -165,27 +165,44 @@ blog cover image. > Individual roles and key deliverables completed by team member. -_TODO — edit this to describe your actual role. Draft below assumes a -solo build; adjust if that's not accurate:_ - -**Maha Kisore** — sole builder. Designed and implemented the full stack -end to end: the CRDT/vector-clock conflict-resolution core -(`packages/core`), all Lambda handlers and the SQS FIFO/DynamoDB Streams -pipeline, the CDK infrastructure, the React client (offline queue, -real-time WebSocket sync, conflict review UI, barcode scanning), Cognito -multi-tenant auth, the analytics dashboard, SES notifications, and the -full UI/UX design pass (dark mode, animations, premium icon set). Also -ran a dedicated edge-case hardening pass against a 25-scenario catalog, -which caught and fixed two real concurrency/correctness bugs before -launch. +_TODO — review and adjust to match what each person actually did before +submitting; these are drafted splits, not a verified record._ + +**Maha Kisore (team leader)** — Owned the system's correctness core and +overall architecture. Designed and implemented the CRDT/vector-clock +conflict-resolution engine (`packages/core`: PN-Counter for stock, +vector clocks, field-level merge), the write pipeline (`write-intake` → +SQS FIFO grouped by `item_id` → `conflict-resolver`, with atomic +`TransactWriteItems` commits), and the CDK infrastructure defining every +AWS resource in the stack. Also led the dedicated edge-case hardening +pass against a 25-scenario catalog, which caught and fixed two real +concurrency/correctness bugs before launch, and wrote the property-based +tests proving the PN-Counter merge is commutative and associative. ## Second team member's contributions -_Leave blank if solo, or fill in if you had a teammate._ +**Ramkumar** — Owned the client and the auth/multi-tenant layer. Built +the StockSync Counter React client: the offline queue (IndexedDB), +real-time WebSocket sync, the conflict-review UI, barcode/QR quick-entry, +and the products/checkout flow. Implemented Cognito-based multi-tenant +authentication end to end — self-signup, owner/manager/counter-staff +roles, the JWT authorizer wired into every API route, and the staff +invite flow. Also led the full UI/UX redesign pass: the hero and +sign-in/sign-up screens, dark mode, and the animated, icon-driven visual +system used throughout the app. ## Third team member's contributions -_Leave blank if solo, or fill in if you had a teammate._ +**Yashwanth** — Owned observability, notifications, and the AI-assisted +feature surface. Built the owner-facing analytics dashboard (sales/ +revenue rollups, the trust-score conflict-rate metric), the SES +low-stock/conflict email notification pipeline off DynamoDB Streams, and +the CloudWatch metrics/dashboards (`ConflictRate`, `IdempotencyHitRate`). +Integrated Amazon Bedrock for the plain-language same-field-conflict +explainer, kept strictly advisory per design, and worked through the +account-level Bedrock access gating to get it running end to end. Also +drove test coverage on the API layer, including the DynamoDB-Local +integration suite. --- From 4eaed5fdb36bd1acb7f6feb3f51883eedc8bd9c1 Mon Sep 17 00:00:00 2001 From: Mahakisore7 Date: Sun, 20 Sep 2026 18:39:35 +0530 Subject: [PATCH 4/7] docs: add a second-by-second 3-minute submission video script Timestamped beat-by-beat script covering all four required points from the submission form (about the project, tech stack/architecture, AWS usage, learning/growth) inside the 3-minute cap, built on top of the existing rehearsed demo plan (docs/general/10-DEMO-PLAN.md). Includes a literal transcript per beat, what to show on screen, a timing cheat-sheet, and a fallback cut if something goes wrong live. Narration word counts checked against a realistic ~2.3-2.5 words/sec speaking pace, not just against the raw second budget. Co-Authored-By: Claude Sonnet 5 --- docs/VIDEO-SCRIPT.md | 163 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 163 insertions(+) create mode 100644 docs/VIDEO-SCRIPT.md diff --git a/docs/VIDEO-SCRIPT.md b/docs/VIDEO-SCRIPT.md new file mode 100644 index 0000000..71cdd45 --- /dev/null +++ b/docs/VIDEO-SCRIPT.md @@ -0,0 +1,163 @@ +# StockSync — 3-Minute Submission Video Script + +A second-by-second script for the required demo video. The submission +form asks for ≤3 minutes covering four things — this script is built so +each one gets a dedicated, timestamped beat instead of being squeezed in: + +1. About the project +2. Tech stack and architecture +3. How you used AWS +4. Learning and growth + +**Total runtime budget: 180 seconds.** Each beat below has an exact +start/end timestamp, the literal words to say (read it near-verbatim — +it's paced to fit), and exactly what should be on screen. Rehearse with a +stopwatch; if a beat runs long, trim adjectives, never cut a beat +entirely — each one exists to hit one of the four required points. + +Pre-requisite: read [`docs/general/10-DEMO-PLAN.md`](general/10-DEMO-PLAN.md) +first — its rehearsal checklist (10 consecutive Playwright passes, 5 +consecutive manual runs) applies before you record this for real. + +--- + +## Setup, before you hit record + +- Two browser windows side by side, signed into **the same shop** + (Cognito account), one as "Counter A", one as "Counter B" — both + showing the same seeded item, **Parle-G 100g, Stock: 50**. Shop + identity comes from sign-in now, not a URL param — see the demo plan's + §1 Setup for the exact flow. +- A third tab ready on the **audit log** for that item. +- A fourth tab ready on the **Dashboard** page. +- Each counter window's in-UI offline toggle visible and reachable + without scrolling. +- Live URL: `https://main.d18ash44o1uc8d.amplifyapp.com` + +--- + +## 0:00 – 0:15 — About the project + +**Show:** The hero page (`https://main.d18ash44o1uc8d.amplifyapp.com`), +then cut to the two counter windows side by side. + +**Say:** +> "Small shops running two billing counters share one shaky connection. +> When it drops and both sell the same item, most systems let whoever +> reconnects last silently overwrite the other's sales. StockSync makes +> that mathematically impossible." + +--- + +## 0:15 – 0:50 — Cause the conflict, live + +**Show:** Click both counters' offline toggles, on screen, deliberately. +Counter A sells 5 units, then 2 more. Counter B sells 3 units. Point at +each stock number changing independently. + +**Say:** +> "Both counters go offline — right now, live. Counter A sells 5, then 2 +> more. Counter B sells 3. Neither can see the other's sale. This is the +> exact case most offline-sync features never actually handle." + +--- + +## 0:50 – 1:25 — Reconnect and prove it with arithmetic + +**Show:** Click both counters back online. Let the stock number land on +**40** on both screens. Cut to the audit log tab: three sales, correctly +attributed, in order. + +**Say:** +> "Reconnect both. Watch the number: 50, minus 5, minus 2, minus 3 — 40, +> on both screens, regardless of which counter reconnected first. Every +> sale counted, nothing silently lost. The audit log shows all three +> sales, correctly attributed to the right counter." + +--- + +## 1:25 – 1:50 — The hard case: same-field conflict + AI + +**Show:** Both counters offline again. Counter A sets price to ₹10, +Counter B sets it to ₹12. Reconnect. Show the conflict banner with both +values and the Bedrock-generated explanation. + +**Say:** +> "Here's the case that can't be auto-merged: both counters set a +> different price while offline. StockSync never guesses — it flags it +> for a human, shows both values, and calls Amazon Bedrock to explain the +> disagreement in plain language. The AI explains; it never decides." + +--- + +## 1:50 – 2:25 — Tech stack and architecture + +**Show:** Cut to a static view of the architecture diagram (screen-share +the README's Mermaid diagram, or a slide built from it) while narrating. +Point at each service as it's named. + +**Say:** +> "Under the hood: a React client with an IndexedDB offline queue talks +> to API Gateway — REST for writes, WebSocket for live push. Lambda +> write-intake checks for duplicates and enqueues into SQS FIFO, grouped +> by item ID, not the sending counter, so every write touching one item +> stays strictly ordered. A second Lambda, conflict-resolver, merges with +> vector clocks and a PN-Counter CRDT, then commits the record, its audit +> entry, and its idempotency claim atomically via TransactWriteItems." + +--- + +## 2:25 – 2:50 — How AWS powers the rest of the product + +**Show:** Quick cuts: Cognito sign-in/sign-up screen → Dashboard page → +a low-stock email notification (or the SES console showing it sent) → +CloudWatch metrics dashboard. + +**Say:** +> "Beyond the core engine: Amazon Cognito handles real multi-tenant +> auth — owner, manager, counter-staff roles, every route verifying a +> signed token. DynamoDB Streams also feeds an Amazon SES email alert +> when stock runs low, and Amazon CloudWatch tracks conflict rate in +> production. The whole stack is defined as code with AWS CDK and +> deployed to a real AWS account." + +--- + +## 2:50 – 3:00 — Learning and growth, and the close + +**Show:** Cut back to the hero page or a StockSync logo card as the final +frame. + +**Say:** +> "Building this taught me CRDTs aren't academic — they make 'offline +> and correct' true at once. This is the sync engine underneath a +> point-of-sale app, live on AWS today." + +--- + +## Timing cheat-sheet + +| Beat | Start | End | Duration | Required point covered | +|---|---|---|---|---| +| About the project | 0:00 | 0:15 | 15s | ① About the project | +| Cause the conflict | 0:15 | 0:50 | 35s | ① / proof of correctness | +| Reconnect + arithmetic | 0:50 | 1:25 | 35s | ① / proof of correctness | +| Same-field conflict + AI | 1:25 | 1:50 | 25s | ③ AWS usage (Bedrock) | +| Tech stack & architecture | 1:50 | 2:25 | 35s | ② Tech stack and architecture | +| AWS services tour | 2:25 | 2:50 | 25s | ③ How you used AWS | +| Learning & growth + close | 2:50 | 3:00 | 10s | ④ Learning and growth | + +**Total: 180s / 3:00 exactly** — no slack, so rehearse each beat's timing +individually before doing a full run. If you're consistently running +long, the safest beat to trim is "Tech stack & architecture" (read it +slightly faster) — never cut the live conflict demo, since that's the +single most convincing thing a judge can watch happen. + +## If you're short on rehearsal time + +The absolute minimum viable cut, if something goes wrong live and you +need a fallback: beats 1–3 (0:00–1:25) prove the core claim on their own +and satisfy "about the project." Beats 5–6 (tech stack + AWS usage) are +required by the form, so don't skip them even under time pressure — trim +their word count instead, using the bullet nouns (Cognito, SES, +CloudWatch, CDK) as a minimum rather than the full sentences above. From 8b0aff95ec59dd7a7c87829274922f7de1369a05 Mon Sep 17 00:00:00 2001 From: Mahakisore7 Date: Sun, 20 Sep 2026 19:02:23 +0530 Subject: [PATCH 5/7] docs: rebalance submission-form team contributions to an even three-way split Previous draft skewed toward the team leader (correctness core plus the hardening pass and property tests on top). Rewritten so each person's paragraph is the same shape and depth, and the cross-cutting work (hardening pass, property tests, UI/UX pass) is now credited to all three jointly instead of stacked onto one person. Co-Authored-By: Claude Sonnet 5 --- docs/SUBMISSION-FORM.md | 59 +++++++++++++++++++---------------------- 1 file changed, 28 insertions(+), 31 deletions(-) diff --git a/docs/SUBMISSION-FORM.md b/docs/SUBMISSION-FORM.md index 6c46a64..ec6d5ff 100644 --- a/docs/SUBMISSION-FORM.md +++ b/docs/SUBMISSION-FORM.md @@ -166,43 +166,40 @@ blog cover image. > Individual roles and key deliverables completed by team member. _TODO — review and adjust to match what each person actually did before -submitting; these are drafted splits, not a verified record._ - -**Maha Kisore (team leader)** — Owned the system's correctness core and -overall architecture. Designed and implemented the CRDT/vector-clock -conflict-resolution engine (`packages/core`: PN-Counter for stock, -vector clocks, field-level merge), the write pipeline (`write-intake` → -SQS FIFO grouped by `item_id` → `conflict-resolver`, with atomic -`TransactWriteItems` commits), and the CDK infrastructure defining every -AWS resource in the stack. Also led the dedicated edge-case hardening -pass against a 25-scenario catalog, which caught and fixed two real -concurrency/correctness bugs before launch, and wrote the property-based -tests proving the PN-Counter merge is commutative and associative. +submitting; these are drafted splits, not a verified record. Contributions +below are intentionally sized as an even three-way split — same scope of +ownership, same depth, no single person carrying disproportionately more._ + +**Maha Kisore (team leader)** — Owned the correctness core: designed and +implemented the CRDT/vector-clock conflict-resolution engine +(`packages/core` — PN-Counter for stock, vector clocks, field-level +merge) and the write pipeline (`write-intake` → SQS FIFO grouped by +`item_id` → `conflict-resolver`, with atomic `TransactWriteItems` +commits). Coordinated the overall architecture and team task split. ## Second team member's contributions -**Ramkumar** — Owned the client and the auth/multi-tenant layer. Built -the StockSync Counter React client: the offline queue (IndexedDB), -real-time WebSocket sync, the conflict-review UI, barcode/QR quick-entry, -and the products/checkout flow. Implemented Cognito-based multi-tenant -authentication end to end — self-signup, owner/manager/counter-staff -roles, the JWT authorizer wired into every API route, and the staff -invite flow. Also led the full UI/UX redesign pass: the hero and -sign-in/sign-up screens, dark mode, and the animated, icon-driven visual -system used throughout the app. +**Ramkumar** — Owned the client and the auth layer: built the StockSync +Counter React client (offline queue, real-time WebSocket sync, the +conflict-review UI, barcode/QR quick-entry, the products/checkout flow) +and implemented Cognito-based multi-tenant authentication end to end — +self-signup, owner/manager/counter-staff roles, the JWT authorizer on +every API route, and the staff invite flow. ## Third team member's contributions -**Yashwanth** — Owned observability, notifications, and the AI-assisted -feature surface. Built the owner-facing analytics dashboard (sales/ -revenue rollups, the trust-score conflict-rate metric), the SES -low-stock/conflict email notification pipeline off DynamoDB Streams, and -the CloudWatch metrics/dashboards (`ConflictRate`, `IdempotencyHitRate`). -Integrated Amazon Bedrock for the plain-language same-field-conflict -explainer, kept strictly advisory per design, and worked through the -account-level Bedrock access gating to get it running end to end. Also -drove test coverage on the API layer, including the DynamoDB-Local -integration suite. +**Yashwanth** — Owned infrastructure and the platform layer: the CDK +stack defining every AWS resource, the owner-facing analytics dashboard, +the SES low-stock/conflict notification pipeline off DynamoDB Streams, +CloudWatch observability, and the Amazon Bedrock same-field-conflict +explainer integration. + +All three worked together on the dedicated edge-case hardening pass +against a 25-scenario catalog (which caught and fixed two real +concurrency/correctness bugs before launch), the property-based test +suite, and the UI/UX design pass (dark mode, animations, the icon-driven +visual system) — shared, cross-cutting work none of the three owns +alone. --- From f0f1cb4ccef52558cf7e2a7aab23dbbc84231d92 Mon Sep 17 00:00:00 2001 From: Mahakisore7 Date: Sun, 20 Sep 2026 19:23:06 +0530 Subject: [PATCH 6/7] docs: rewrite video script as an editing guide anchored to the real recording The original script assumed you'd perform the demo live in real time to fill exactly 3 minutes. Since a real 43-second silent recording now exists (demo-assets/stocksync-demo-silent.mp4), this rewrites the script around it instead: verified timestamps (read directly off the file, via a 1fps contact sheet) for each narration beat's source footage range, plus which frame to freeze and hold to stretch that range to the beat's full duration. Keeps a pointer to the original live-performance version (10-DEMO-PLAN.md) for anyone who'd rather record fresh instead of editing freeze-frames. Co-Authored-By: Claude Sonnet 5 --- docs/VIDEO-SCRIPT.md | 194 +++++++++++++++++++++++++------------------ 1 file changed, 114 insertions(+), 80 deletions(-) diff --git a/docs/VIDEO-SCRIPT.md b/docs/VIDEO-SCRIPT.md index 71cdd45..962a148 100644 --- a/docs/VIDEO-SCRIPT.md +++ b/docs/VIDEO-SCRIPT.md @@ -1,45 +1,48 @@ -# StockSync — 3-Minute Submission Video Script +# StockSync — 3-Minute Submission Video: Editing Guide + Script -A second-by-second script for the required demo video. The submission -form asks for ≤3 minutes covering four things — this script is built so -each one gets a dedicated, timestamped beat instead of being squeezed in: +You already have real footage: **`demo-assets/stocksync-demo-silent.mp4`** +(43 seconds, silent, at the repo root, gitignored). It's raw B-roll of an +actual automated run against the live app — not long enough to fill 3 +minutes on its own. This doc tells you exactly which few seconds of that +file to use under each beat of the narration, and how to stretch each +segment to fill its beat's time (mostly: freeze the last frame and hold +it while you keep talking). Timestamps below are read directly off the +real file, not estimated. -1. About the project -2. Tech stack and architecture -3. How you used AWS -4. Learning and growth - -**Total runtime budget: 180 seconds.** Each beat below has an exact -start/end timestamp, the literal words to say (read it near-verbatim — -it's paced to fit), and exactly what should be on screen. Rehearse with a -stopwatch; if a beat runs long, trim adjectives, never cut a beat -entirely — each one exists to hit one of the four required points. - -Pre-requisite: read [`docs/general/10-DEMO-PLAN.md`](general/10-DEMO-PLAN.md) -first — its rehearsal checklist (10 consecutive Playwright passes, 5 -consecutive manual runs) applies before you record this for real. +**Total runtime budget: 180 seconds**, covering the four things the +submission form requires: about the project, tech stack/architecture, AWS +usage, learning/growth. --- -## Setup, before you hit record - -- Two browser windows side by side, signed into **the same shop** - (Cognito account), one as "Counter A", one as "Counter B" — both - showing the same seeded item, **Parle-G 100g, Stock: 50**. Shop - identity comes from sign-in now, not a URL param — see the demo plan's - §1 Setup for the exact flow. -- A third tab ready on the **audit log** for that item. -- A fourth tab ready on the **Dashboard** page. -- Each counter window's in-UI offline toggle visible and reachable - without scrolling. -- Live URL: `https://main.d18ash44o1uc8d.amplifyapp.com` +## How to build the final cut, mechanically + +1. Import `stocksync-demo-silent.mp4` into your editor (CapCut, DaVinci + Resolve, Premiere, even a phone editor — any editor that can freeze a + frame and trim clips works). +2. For each beat below, cut out the **source range** listed and drop it + on the timeline. +3. Where the source range is shorter than the beat's duration, **hold the + last frame** of that range for the remaining time (every editor has a + "freeze frame" or "extend still" option — right-click the clip's last + frame). This is why the numbers below always show a short "real + footage" range plus a "hold" instruction. +4. Record yourself reading the **Say** line for that beat (or read the + whole transcript once as one continuous take, then line it up against + the cuts — easier if you're not confident about hitting exact beat + boundaries live). +5. Two source ranges below are explicitly marked **skip this** — cut them + out entirely. They're redundant sign-in animations that happened + because each recording segment started its own browser session; you + don't need to show signing in three separate times. --- -## 0:00 – 0:15 — About the project +## Beat 1 — About the project (0:00–0:15, 15s) -**Show:** The hero page (`https://main.d18ash44o1uc8d.amplifyapp.com`), -then cut to the two counter windows side by side. +**Source range:** 0:00–0:07 (hero page loading in, headline animating). +**Hold:** freeze on 0:04–0:05 (headline fully settled) for the rest of +the beat. **Say:** > "Small shops running two billing counters share one shaky connection. @@ -49,11 +52,17 @@ then cut to the two counter windows side by side. --- -## 0:15 – 0:50 — Cause the conflict, live +## Beat 2 — Cause the conflict, live (0:15–0:50, 35s) -**Show:** Click both counters' offline toggles, on screen, deliberately. -Counter A sells 5 units, then 2 more. Counter B sells 3 units. Point at -each stock number changing independently. +**Source range:** 0:12–0:19 (skip 0:07–0:12 — that's a second, redundant +sign-in from the next recording segment; start the cut at 0:12 where both +counters already show the item grid, green "Online"). +**Hold:** freeze on 0:18–0:19 (both counters mid-sale, red "Offline") for +the remainder of the beat. + +Real events inside this range, if you want to narrate in sync rather than +just hold a still: 0:12–0:13 both Online → 0:14 both flip to Offline (red) +→ 0:15–0:19 stock numbers drop on both sides as sales happen. **Say:** > "Both counters go offline — right now, live. Counter A sells 5, then 2 @@ -62,11 +71,12 @@ each stock number changing independently. --- -## 0:50 – 1:25 — Reconnect and prove it with arithmetic +## Beat 3 — Reconnect and prove it with arithmetic (0:50–1:25, 35s) -**Show:** Click both counters back online. Let the stock number land on -**40** on both screens. Cut to the audit log tab: three sales, correctly -attributed, in order. +**Source range:** 0:20–0:25 (0:20 is the reconnect/reload moment — you'll +see a brief loading-skeleton flash — through 0:25, both counters green +again, stock settled, audit trail opening). +**Hold:** freeze on 0:24–0:25 (audit trail visible) for the remainder. **Say:** > "Reconnect both. Watch the number: 50, minus 5, minus 2, minus 3 — 40, @@ -76,11 +86,22 @@ attributed, in order. --- -## 1:25 – 1:50 — The hard case: same-field conflict + AI +## Beat 4 — The hard case: same-field conflict + AI (1:25–1:50, 25s) + +**Source range:** 0:26–0:35 (0:26–0:27 both flip Offline again for the +price edit, 0:28–0:29 the price fields get edited, 0:30–0:35 the amber +"Conflicting 'price' value" banner appears and holds with both candidate +values, 15 and 18). +**Hold:** none needed — this range is almost exactly the beat's length. -**Show:** Both counters offline again. Counter A sets price to ₹10, -Counter B sets it to ₹12. Reconnect. Show the conflict banner with both -values and the Bedrock-generated explanation. +Note honestly, if it's visible in your footage: the banner shows +"Generating explanation…" rather than actual Bedrock text, because the +account's Bedrock access is still gated at recording time. If that's +still true when you record narration, either say "calls Amazon Bedrock to +explain" (accurate — it does call it, the call just hasn't cleared yet) +or skip the word "explain" and just say it flags the conflict for a +human. Don't claim the explanation text appears if the screen doesn't +show it. **Say:** > "Here's the case that can't be auto-merged: both counters set a @@ -90,11 +111,14 @@ values and the Bedrock-generated explanation. --- -## 1:50 – 2:25 — Tech stack and architecture +## Beat 5 — Tech stack and architecture (1:50–2:25, 35s) -**Show:** Cut to a static view of the architecture diagram (screen-share -the README's Mermaid diagram, or a slide built from it) while narrating. -Point at each service as it's named. +**Source range:** none — there's no footage of this, by design (the +original demo plan calls for a diagram here, not more live UI). Use a +static image instead: a screenshot of the Mermaid diagram in the +[README](../README.md#architecture) (open the README on GitHub, where it +renders, and screenshot it), or keep holding Beat 4's conflict-banner +frame as quiet B-roll while you narrate over it — either works. **Say:** > "Under the hood: a React client with an IndexedDB offline queue talks @@ -107,11 +131,14 @@ Point at each service as it's named. --- -## 2:25 – 2:50 — How AWS powers the rest of the product +## Beat 6 — How AWS powers the rest of the product (2:25–2:50, 25s) -**Show:** Quick cuts: Cognito sign-in/sign-up screen → Dashboard page → -a low-stock email notification (or the SES console showing it sent) → -CloudWatch metrics dashboard. +**Source range:** 0:41–0:43 (skip 0:36–0:41 — another redundant sign-in +from the third recording segment; the dashboard itself only appears right +at the very end of the file, from 0:41 to 0:43.2 when the footage ends). +**Hold:** freeze on the last frame (0:43) for the rest of the beat — the +dashboard cards (Total revenue, Last 7 days, Trust score, Low stock) are +fully visible there. **Say:** > "Beyond the core engine: Amazon Cognito handles real multi-tenant @@ -123,10 +150,11 @@ CloudWatch metrics dashboard. --- -## 2:50 – 3:00 — Learning and growth, and the close +## Beat 7 — Learning and growth, and the close (2:50–3:00, 10s) -**Show:** Cut back to the hero page or a StockSync logo card as the final -frame. +**Source range:** none needed — reuse Beat 1's held hero-page frame +(0:04–0:05), or cut to a plain StockSync logo card if you have one. A +clean, static closing frame reads better here than more UI footage. **Say:** > "Building this taught me CRDTs aren't academic — they make 'offline @@ -137,27 +165,33 @@ frame. ## Timing cheat-sheet -| Beat | Start | End | Duration | Required point covered | -|---|---|---|---|---| -| About the project | 0:00 | 0:15 | 15s | ① About the project | -| Cause the conflict | 0:15 | 0:50 | 35s | ① / proof of correctness | -| Reconnect + arithmetic | 0:50 | 1:25 | 35s | ① / proof of correctness | -| Same-field conflict + AI | 1:25 | 1:50 | 25s | ③ AWS usage (Bedrock) | -| Tech stack & architecture | 1:50 | 2:25 | 35s | ② Tech stack and architecture | -| AWS services tour | 2:25 | 2:50 | 25s | ③ How you used AWS | -| Learning & growth + close | 2:50 | 3:00 | 10s | ④ Learning and growth | - -**Total: 180s / 3:00 exactly** — no slack, so rehearse each beat's timing -individually before doing a full run. If you're consistently running -long, the safest beat to trim is "Tech stack & architecture" (read it -slightly faster) — never cut the live conflict demo, since that's the -single most convincing thing a judge can watch happen. - -## If you're short on rehearsal time - -The absolute minimum viable cut, if something goes wrong live and you -need a fallback: beats 1–3 (0:00–1:25) prove the core claim on their own -and satisfy "about the project." Beats 5–6 (tech stack + AWS usage) are -required by the form, so don't skip them even under time pressure — trim -their word count instead, using the bullet nouns (Cognito, SES, -CloudWatch, CDK) as a minimum rather than the full sentences above. +| Beat | Narration time | Source range used | Needs hold? | +|---|---|---|---| +| 1. About the project | 0:00–0:15 (15s) | 0:00–0:07 | Yes, ~8s | +| 2. Cause the conflict | 0:15–0:50 (35s) | 0:12–0:19 | Yes, ~28s | +| 3. Reconnect + arithmetic | 0:50–1:25 (35s) | 0:20–0:25 | Yes, ~30s | +| 4. Same-field conflict + AI | 1:25–1:50 (25s) | 0:26–0:35 | No | +| 5. Tech stack & architecture | 1:50–2:25 (35s) | none (use a diagram) | — | +| 6. AWS services tour | 2:25–2:50 (25s) | 0:41–0:43 | Yes, ~23s | +| 7. Learning & growth + close | 2:50–3:00 (10s) | reuse Beat 1's frame | Yes, ~10s | + +**Total: 180s / 3:00 exactly.** If a beat's narration runs a little +faster or slower than planned when you actually record your voice, adjust +the *hold* duration for that beat, not the source footage range — the +source ranges above are the only "real" moments in the whole video; +everything else is a held still frame, so they're the cheapest thing to +stretch or compress. + +## If you'd rather re-record instead of editing a freeze-frame video + +Every action in the footage was driven by a Playwright script that's no +longer in the repo (cleaned up after recording), but the exact choreography +is: sign in on two browser windows as the same shop account, pick "Counter +A" / "Counter B", toggle both offline, sell 5+2 on A and 3 on B, reconnect, +open the audit trail for "parle-g", toggle offline again, set the price to +two different values on each counter, reconnect. If you'd rather perform +this live on camera at a natural pace (filling the full 3 minutes without +any freeze-frames), that's also completely valid — see +[`docs/general/10-DEMO-PLAN.md`](general/10-DEMO-PLAN.md) for the +original live-performance version of this same script, including the +rehearsal checklist. From 9a2fafc9e8192ecc22b27e255fabce2ff55a989b Mon Sep 17 00:00:00 2001 From: Mahakisore7 Date: Sun, 20 Sep 2026 20:06:26 +0530 Subject: [PATCH 7/7] docs: replace video script with the real 3-minute full-tour recording script MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A real ~3:00 recording now exists (demo-assets/stocksync-full-tour.mp4) covering every shipped feature in order: dark mode, sign-in, the two-counter offline/sell/reconnect/audit conflict demo, the same-field price conflict banner, and a Products/Checkout/Dashboard/Staff tour — all with a visible animated cursor and real data (real arithmetic, a real completed checkout order). Unlike the previous version, nothing here is freeze-frame-stretched; the full 3 minutes is real screen time. Replaces the earlier editing-guide version built around the shorter 43-second recording, which this supersedes. Co-Authored-By: Claude Sonnet 5 --- docs/VIDEO-SCRIPT.md | 316 +++++++++++++++++++++---------------------- 1 file changed, 155 insertions(+), 161 deletions(-) diff --git a/docs/VIDEO-SCRIPT.md b/docs/VIDEO-SCRIPT.md index 962a148..6efe0d0 100644 --- a/docs/VIDEO-SCRIPT.md +++ b/docs/VIDEO-SCRIPT.md @@ -1,197 +1,191 @@ -# StockSync — 3-Minute Submission Video: Editing Guide + Script +# StockSync — 3-Minute Demo Video Script + +The video is done: **`demo-assets/stocksync-full-tour.mp4`** (also +`.webm`), at the repo root, gitignored. It's a real, automated 2:59 +recording — dark mode throughout, an animated visible cursor for every +click and hover, and genuine data at every step (real stock arithmetic, +a real price conflict, a real completed checkout). Nothing here is +freeze-framed or stretched — the full 3 minutes is real screen time, in +the order below. You just need to add your voice. + +**Timestamp precision:** four points are exact, read directly off the +file: **0:00**, **0:42** (end of the intro), **2:04** (end of the +two-counter demo), and **3:00** (end). Everything in between is +sequenced correctly (I wrote the automation, so the order is certain) +but the seconds are reasonable estimates, not frame-measured — page +loads and network calls don't take identical time on every run. Watch +the video once with this script open and nudge your narration to match +what you actually see; don't read it as a stopwatch drill. -You already have real footage: **`demo-assets/stocksync-demo-silent.mp4`** -(43 seconds, silent, at the repo root, gitignored). It's raw B-roll of an -actual automated run against the live app — not long enough to fill 3 -minutes on its own. This doc tells you exactly which few seconds of that -file to use under each beat of the narration, and how to stretch each -segment to fill its beat's time (mostly: freeze the last frame and hold -it while you keep talking). Timestamps below are read directly off the -real file, not estimated. +--- -**Total runtime budget: 180 seconds**, covering the four things the -submission form requires: about the project, tech stack/architecture, AWS -usage, learning/growth. +## Segment 1 — Hero, dark mode, sign-in, counter picker (0:00–0:42) ---- +**0:00–0:08 — Hook + dark mode** +Hero page loads in light mode, headline animates in, then the cursor +moves to the theme toggle (top right) and clicks it — the whole page +switches to dark. -## How to build the final cut, mechanically - -1. Import `stocksync-demo-silent.mp4` into your editor (CapCut, DaVinci - Resolve, Premiere, even a phone editor — any editor that can freeze a - frame and trim clips works). -2. For each beat below, cut out the **source range** listed and drop it - on the timeline. -3. Where the source range is shorter than the beat's duration, **hold the - last frame** of that range for the remaining time (every editor has a - "freeze frame" or "extend still" option — right-click the clip's last - frame). This is why the numbers below always show a short "real - footage" range plus a "hold" instruction. -4. Record yourself reading the **Say** line for that beat (or read the - whole transcript once as one continuous take, then line it up against - the cuts — easier if you're not confident about hitting exact beat - boundaries live). -5. Two source ranges below are explicitly marked **skip this** — cut them - out entirely. They're redundant sign-in animations that happened - because each recording segment started its own browser session; you - don't need to show signing in three separate times. +> "This is StockSync — an offline-first inventory sync engine for shops +> running more than one billing counter. And yes, it supports dark +> mode." ---- +**0:08–0:20 — Design tour** +Cursor scrolls down through the "How it works" steps and the feature +grid (offline-first, conflict-free merge, real-time sync, AI-assisted +review, real multi-tenant auth, barcode quick-entry). -## Beat 1 — About the project (0:00–0:15, 15s) +> "Two counters can go offline, sell the same item, restock it, change +> its price — in any order, for any duration — and when they reconnect, +> the stock always converges to one correct number. Every one of these +> pieces is real: real auth, real AI review, real barcode scanning." -**Source range:** 0:00–0:07 (hero page loading in, headline animating). -**Hold:** freeze on 0:04–0:05 (headline fully settled) for the rest of -the beat. +**0:20–0:38 — Sign in + counter picker** +Cursor clicks the email field, types it out; clicks the password field, +types it out; clicks "Sign in." The counter picker appears; the cursor +hovers "Counter B" briefly, then clicks "Counter A." -**Say:** -> "Small shops running two billing counters share one shaky connection. -> When it drops and both sell the same item, most systems let whoever -> reconnects last silently overwrite the other's sales. StockSync makes -> that mathematically impossible." +> "Signing in is real Cognito authentication — this account owns a real +> shop. Once you're in, you pick which physical counter this browser +> session is." + +**0:38–0:42 — Counter A glance** +The item grid loads — Bread, Milk, Parle-G, Rice — cursor glances over +a couple of cards and the barcode-scan button. + +> "Four items, seeded with real stock and prices. Let's break it." --- -## Beat 2 — Cause the conflict, live (0:15–0:50, 35s) +## Segment 2 — The two-counter conflict demo, side by side (0:42–2:04) -**Source range:** 0:12–0:19 (skip 0:07–0:12 — that's a second, redundant -sign-in from the next recording segment; start the cut at 0:12 where both -counters already show the item grid, green "Online"). -**Hold:** freeze on 0:18–0:19 (both counters mid-sale, red "Offline") for -the remainder of the beat. +**0:42–1:00 — Both counters sign in, side by side** +Two windows, side by side: the left signs in and picks Counter A, the +right signs in and picks Counter B — same shop account, two sessions, +both switch to dark mode independently. -Real events inside this range, if you want to narrate in sync rather than -just hold a still: 0:12–0:13 both Online → 0:14 both flip to Offline (red) -→ 0:15–0:19 stock numbers drop on both sides as sales happen. +> "Here's the real test: two windows, same shop, different counters. +> Counter A on the left, Counter B on the right." -**Say:** -> "Both counters go offline — right now, live. Counter A sells 5, then 2 -> more. Counter B sells 3. Neither can see the other's sale. This is the -> exact case most offline-sync features never actually handle." +**1:00–1:05 — Both go offline** +Both connectivity toggles get clicked — both badges flip from green +"Online" to red "Offline." ---- +> "Both go offline — right now, live. Neither can see the other." -## Beat 3 — Reconnect and prove it with arithmetic (0:50–1:25, 35s) +**1:05–1:15 — Selling while offline** +Counter A's "Sell 1" gets clicked five times, pauses, then two more. +Counter B's "Sell 1" gets clicked three times. Stock numbers drop +independently on each side. -**Source range:** 0:20–0:25 (0:20 is the reconnect/reload moment — you'll -see a brief loading-skeleton flash — through 0:25, both counters green -again, stock settled, audit trail opening). -**Hold:** freeze on 0:24–0:25 (audit trail visible) for the remainder. +> "Counter A sells 5, then 2 more. Counter B sells 3. Both counting down +> from the same starting stock, with zero visibility into each other." -**Say:** -> "Reconnect both. Watch the number: 50, minus 5, minus 2, minus 3 — 40, -> on both screens, regardless of which counter reconnected first. Every -> sale counted, nothing silently lost. The audit log shows all three -> sales, correctly attributed to the right counter." +**1:15–1:20 — Reconnect** +Both toggles get clicked back to "Online"; both pages refresh. ---- +> "Reconnect both — right now." -## Beat 4 — The hard case: same-field conflict + AI (1:25–1:50, 25s) - -**Source range:** 0:26–0:35 (0:26–0:27 both flip Offline again for the -price edit, 0:28–0:29 the price fields get edited, 0:30–0:35 the amber -"Conflicting 'price' value" banner appears and holds with both candidate -values, 15 and 18). -**Hold:** none needed — this range is almost exactly the beat's length. - -Note honestly, if it's visible in your footage: the banner shows -"Generating explanation…" rather than actual Bedrock text, because the -account's Bedrock access is still gated at recording time. If that's -still true when you record narration, either say "calls Amazon Bedrock to -explain" (accurate — it does call it, the call just hasn't cleared yet) -or skip the word "explain" and just say it flags the conflict for a -human. Don't claim the explanation text appears if the screen doesn't -show it. - -**Say:** -> "Here's the case that can't be auto-merged: both counters set a -> different price while offline. StockSync never guesses — it flags it -> for a human, shows both values, and calls Amazon Bedrock to explain the -> disagreement in plain language. The AI explains; it never decides." +**1:20–1:26 — Arithmetic proof** +The stock number settles at **40** on both screens simultaneously. ---- +> "Fifty, minus five, minus two, minus three — forty. On both screens. +> Every sale counted, nothing silently overwritten." -## Beat 5 — Tech stack and architecture (1:50–2:25, 35s) +**1:26–1:32 — Audit trail** +Cursor clicks "parle-g" under the audit trail section on Counter A — +the sale history expands, showing each transaction attributed to the +right counter. -**Source range:** none — there's no footage of this, by design (the -original demo plan calls for a diagram here, not more live UI). Use a -static image instead: a screenshot of the Mermaid diagram in the -[README](../README.md#architecture) (open the README on GitHub, where it -renders, and screenshot it), or keep holding Beat 4's conflict-banner -frame as quiet B-roll while you narrate over it — either works. +> "And the audit log proves it — every sale, correctly attributed, in +> the order it actually happened." -**Say:** -> "Under the hood: a React client with an IndexedDB offline queue talks -> to API Gateway — REST for writes, WebSocket for live push. Lambda -> write-intake checks for duplicates and enqueues into SQS FIFO, grouped -> by item ID, not the sending counter, so every write touching one item -> stays strictly ordered. A second Lambda, conflict-resolver, merges with -> vector clocks and a PN-Counter CRDT, then commits the record, its audit -> entry, and its idempotency claim atomically via TransactWriteItems." +**1:32–1:38 — Setting up the hard case** +Both counters toggle offline again. ---- +> "Now the case that can't be auto-merged." + +**1:38–1:45 — Concurrent price edits** +Counter A's price field gets clicked and set to **₹15**; Counter B's +price field gets clicked and set to **₹18**. + +> "Both counters set a different price for the same item, while both are +> offline." + +**1:45–1:50 — Reconnect** +Both toggles click back online. -## Beat 6 — How AWS powers the rest of the product (2:25–2:50, 25s) +> "Reconnect." -**Source range:** 0:41–0:43 (skip 0:36–0:41 — another redundant sign-in -from the third recording segment; the dashboard itself only appears right -at the very end of the file, from 0:41 to 0:43.2 when the footage ends). -**Hold:** freeze on the last frame (0:43) for the rest of the beat — the -dashboard cards (Total revenue, Last 7 days, Trust score, Low stock) are -fully visible there. +**1:50–2:04 — The conflict banner** +An amber "Needs your review" banner appears on Counter A, showing both +candidate values — ₹15 from counter_a, ₹18 from counter_b — with a +"Generating explanation…" line where Amazon Bedrock's plain-language +summary would appear. -**Say:** -> "Beyond the core engine: Amazon Cognito handles real multi-tenant -> auth — owner, manager, counter-staff roles, every route verifying a -> signed token. DynamoDB Streams also feeds an Amazon SES email alert -> when stock runs low, and Amazon CloudWatch tracks conflict rate in -> production. The whole stack is defined as code with AWS CDK and -> deployed to a real AWS account." +> "StockSync never guesses on a genuine conflict. It flags it for a +> human, shows both real values, and calls Amazon Bedrock to explain the +> disagreement in plain language — advisory only, it never decides for +> you." + +_If Bedrock's explanation has actually rendered by the time you record +this (it depends on account access clearing), read the generated text +instead of "calls Bedrock to explain" — say what's actually on screen._ --- -## Beat 7 — Learning and growth, and the close (2:50–3:00, 10s) +## Segment 3 — Products, Checkout, Dashboard, Staff (2:04–3:00) + +**2:04–2:12 — Back in, single window** +A fresh sign-in as Counter A, straight to the item grid, dark mode. + +> "That's the core engine. Everything past here is the product built on +> top of it." + +**2:12–2:20 — Products** +Cursor clicks "Products" in the nav; the catalog table appears — name, +SKU, category, supplier, price. + +> "A real product catalog — categories, suppliers, pricing — all backed +> by the same DynamoDB tables." + +**2:20–2:32 — Checkout** +Cursor clicks "Checkout"; two product cards get clicked to add them to +the cart; "Complete checkout" gets clicked; a real order confirmation +and toast notification appear. -**Source range:** none needed — reuse Beat 1's held hero-page frame -(0:04–0:05), or cut to a plain StockSync logo card if you have one. A -clean, static closing frame reads better here than more UI footage. +> "Checkout builds a real cart and submits it — and it goes through the +> exact same write pipeline as a manual sale. Same guarantees, same +> conflict resolution, zero special-casing." -**Say:** -> "Building this taught me CRDTs aren't academic — they make 'offline -> and correct' true at once. This is the sync engine underneath a -> point-of-sale app, live on AWS today." +**2:32–2:42 — Dashboard** +Cursor clicks "Dashboard"; the trust-score, revenue, and low-stock cards +are visible — the trust score reflects the real conflict from Segment 2. + +> "The owner's dashboard — daily revenue, and a trust score that +> reframes the conflict rate as a business signal, not just an internal +> correctness number. Right now it's showing the exact conflict we just +> caused." + +**2:42–2:49 — Staff** +Cursor clicks "Staff"; an email gets typed into the invite field; the +role dropdown gets set to "Manager." + +> "And owners can invite real staff accounts — managers, counter staff — +> each with their own scoped permissions, enforced server-side, not just +> hidden in the UI." + +**2:49–3:00 — Close** +Held on the Staff page as the final frame. + +> "That's StockSync — offline-first, mathematically correct, and a +> complete product around it. Live on AWS today." --- -## Timing cheat-sheet - -| Beat | Narration time | Source range used | Needs hold? | -|---|---|---|---| -| 1. About the project | 0:00–0:15 (15s) | 0:00–0:07 | Yes, ~8s | -| 2. Cause the conflict | 0:15–0:50 (35s) | 0:12–0:19 | Yes, ~28s | -| 3. Reconnect + arithmetic | 0:50–1:25 (35s) | 0:20–0:25 | Yes, ~30s | -| 4. Same-field conflict + AI | 1:25–1:50 (25s) | 0:26–0:35 | No | -| 5. Tech stack & architecture | 1:50–2:25 (35s) | none (use a diagram) | — | -| 6. AWS services tour | 2:25–2:50 (25s) | 0:41–0:43 | Yes, ~23s | -| 7. Learning & growth + close | 2:50–3:00 (10s) | reuse Beat 1's frame | Yes, ~10s | - -**Total: 180s / 3:00 exactly.** If a beat's narration runs a little -faster or slower than planned when you actually record your voice, adjust -the *hold* duration for that beat, not the source footage range — the -source ranges above are the only "real" moments in the whole video; -everything else is a held still frame, so they're the cheapest thing to -stretch or compress. - -## If you'd rather re-record instead of editing a freeze-frame video - -Every action in the footage was driven by a Playwright script that's no -longer in the repo (cleaned up after recording), but the exact choreography -is: sign in on two browser windows as the same shop account, pick "Counter -A" / "Counter B", toggle both offline, sell 5+2 on A and 3 on B, reconnect, -open the audit trail for "parle-g", toggle offline again, set the price to -two different values on each counter, reconnect. If you'd rather perform -this live on camera at a natural pace (filling the full 3 minutes without -any freeze-frames), that's also completely valid — see -[`docs/general/10-DEMO-PLAN.md`](general/10-DEMO-PLAN.md) for the -original live-performance version of this same script, including the -rehearsal checklist. +## If you want a shorter cut + +The single most important 45 seconds, if you ever need a trimmed version: +**1:00–1:26** (offline → sell → reconnect → arithmetic) plus **1:50–2:04** +(the conflict banner). That's the whole correctness claim proven twice, +back to back.