Inspiration
What it does
How we built it
Challenges we ran into
Accomplishments that we're proud of
What we learned
What's next for Raid Relic
Inspiration
A raid is brief, but its welcome can leave a lasting story. Raid Relic gives two Twitch communities one shared object to contribute to and pass onward: an evolving, erasable history rather than disconnected collectibles.
What it does
Viewers submit words or emoji privately; approved contributions become original procedural runes. A verified raid and both eligible chats must claim a hand-off before the relic moves and gains a ring. API acceptance is not arrival. The app-local claim window is 180 seconds, independent of Twitch’s countdown. Each side needs T=min(10,ceil(sqrt(max(1,signed raid viewers)))) distinct eligible nonbot participants, without cross-side reuse. Chat location is not proof of raid membership.
The Atlas, Keeper pages and read-only overlay show surviving approved history. Approved marks remain on their creation ring/hold after a stream closes; offline is not erasure. Forget, block, veto and opt-out privacy removals remain effective. Forgetting does not refund quota, and downloaded files cannot be recalled. Pending text and private viewer identifiers are not public content. The three configured creator test channels are not evidence of adoption or open signup.
Try it
Open https://raid-relic-760724762396.us-central1.run.app — no login is required for public content. Visit /atlas/ and inspect Ring 12 and surviving approved light; /keeper/olsols3 and /overlay/1593561134 show retained public marks even offline. If privacy removal legitimately changes a record, do not recreate it. The /demo/judge, /demo/film and /demo/ routes are explicitly fictional demonstrations, not real transfers or live footage.
This is a browsing walkthrough, not an instruction to operate Twitch. Production is not globally read-only. Keeper controls require Twitch sign-in as an owner-admitted creator channel; arbitrary judges gain no controls, consent or raid authority. No Twitch actions are part of the judge walk.
How we built it
Node.js 22+ runs on Cloud Run with Firestore persistence. Transactions keep ownership, claims, quotas and retained history consistent. Signed EventSub webhooks verify raw-body HMAC, timestamps and replay boundaries. External HTTP stays outside database transactions; distributed leases and dispatch markers prevent repeating ambiguous raid requests. The reconnecting read-only WebSocket is the browser/OBS feed, not an upstream EventSub connection.
Original WebGL geometry and SVG rendering present the relic and deterministic runes, with reduced-motion support and client-side PNG cards. Three.js is credited MIT software; the self-hosted Cinzel font retains its OFL notice. Paid AI remains off and clipping is design-only/unwired. Scale-to-zero and free-tier allowances do not guarantee a zero bill.
How Codex was used
Primary build thread: 01a1705c-a87d-7143-80f6-021e47b78ced. This original application author and integration lead built the application, tests and procedural art. Three registered application workers separately contributed presentation, controls and shared replies; report-only QA and judge-freeze documentation workers are separately credited in docs/CODEX_SESSIONS.md. Parent operators performed native/browser QA, Git, CI and releases; current repository authorship is not attributed to one session.
Four concrete historical implementation checkpoints (problem descriptions are paraphrases, not transcript quotations):
- One engraving, one rune: c63ec31 unified canonical recap/shared rune geometry; deterministic local rendering is not live-transfer proof.
- Shared Chat is not local authority: d8eecf4 removed copied-message command authority while retaining bounded non-authoritative decorative echoes.
- Reply once without reviving old grants: b079fe8 introduced an exact-row at-most-once reply path; the documented run061 correction separated request receipts from revocable alias grants. Mocked failure and replay tests are not promises of Twitch delivery.
- Accepted is not arrived: 8ded729 added precision-aware restart recovery and explicit Send Off reservation failures, without blindly repeating ambiguous Raid POSTs.
The video combines existing genuine Twitch hand-off footage with newly recorded Codex documentation/regression refinement. The Codex segment is actual later refinement, not replay of the historical original application build. Raw/private transcripts are not published; sanitized source documentation records concrete contributions and evidence limits.
Challenges
Unknown dispatch outcomes must never cause a blind retry or fabricate arrival. Exact stream identity, signed timing and transactional claims must survive restarts. Copied Shared Chat messages cannot acquire local authority. Privacy also reaches exports: removed engravings must not escape through stale cards. Retained approved marks must stay visible offline without reopening streams or restoring removed content.
Accomplishments
Final source 5f7d933de13adabba12c23613db1203c957a0095 on feature/raid-relic-p9-stretch passed 1,277 native tests with zero skips and hosted CI 41323751216. These are source-checkpoint results, not a new deployed image or fresh physical Twitch/OBS acceptance. Production remains the separately frozen runtime 2b218b3. Historical overlapping QA cohorts are not added together. The demonstration distinguishes real recorded Twitch events, public retained state and fictional demos.
What we learned
An honest UI needs the same authority boundaries as its backend: accepted is not arrived, copied is not local, offline is not forgotten, and simulation is not live proof. Small Codex increments became reviewable through concrete code and targeted regressions followed by independent operator QA. Explicit attribution prevents a tidy narrative from overstating authorship or coverage.
What's next
Consented pilot expansion and further manual accessibility, native OS sharing and physical Twitch/OBS validation. No measured adoption, performance SLA or universal accessibility claim is made. Optional paid AI/clipping work and operational changes remain separate owner decisions.
Source and running instructions
Use the explicit final branch https://github.com/OlsOls2/raid-relic/tree/feature/raid-relic-p9-stretch (default main is not asserted to be the final branch). README.md and docs/PROJECT_GUIDE.md provide source/run instructions; docs/JUDGES_QUICKSTART.md explains the public walkthrough. Third-party licenses and notices are included.
Built With
- css3
- firestore
- google-cloud-run
- html5
- javascript
- node.js
- openai-codex
- svg
- three.js
- twitch
- webgl
- websockets
