Stack'D

Presence is the new luxury.

Stack'D is a real-time, multiplayer phone-down focus protocol.

Join a shared room, stack your phones, and stay focused together. Every tilt, lift, shake, or screen wake breaks the stack for everyone—in real time.

🔗 Live: stackd.raghav.studio

---

How it works

1. Start or join a room with a target duration and enforcement mode (gentle or absolute).
2. Sensors arm on session start — orientation, motion, tab visibility, and Screen Wake Lock are all monitored through a single adapter (use-sensors.ts) so the same logic runs on web and the future Capacitor build.
3. Breach a rule (tilt past threshold, pick the phone up, shake it, switch tabs, lose the wake lock) and it's logged with a severity — minor or severe.
4. Session ends → the client computes a provisional score locally for instant feedback, then calls a Postgres RPC (finalize_focus_session) that independently recomputes duration, breach count, and XP server-side and takes the lower of client vs. server XP. A modified client can only shortchange itself, never inflate its score.
5. Result lands with a full cinematic completion sequence — animated XP count-up, tier reveal, streak, unlocked achievements — that fires the moment your session finalizes, whether that's instant or synced later from an offline queue.

Scoring model

S_focus = max(0, min(100, (T_focus / T_target) * 100 − Σ P_breach))
XP      = floor(S_focus * (T_focus / 60) * M_tier)

Tier	Score range	XP multiplier
Flow State	95–100	1.5×
Pristine Focus	85–94	1.0×
Steady Ambient	70–84	0.5×
Fragmented Attention	40–69	0×
Protocol Compromised	0–39	0×

Minor breaches cost 10 points, severe breaches cost 40. Abandoning past a 15-second grace window after a severe breach adds a continuous penalty. The pure scoring function lives in src/lib/focus-score.ts with no React or DB dependencies, so it's independently testable.

Features

• Core loop — rooms, real-time presence, live activity rail, session workspace, ambient soundscapes, QR-code room invites, floating persistent timer.

• Progression & identity — XP, streaks, tiers, achievements, challenges, seasons, prestige, narrative rank titles, profile cards, DNA (behavioral pattern breakdown), memory vault, session replay, time capsules.

• Social — friends, groups/circles, activity feed, leaderboards, mentor relationships, live session reactions, shared goal bars for group rooms.

• Companion — Atlas, an ambient AI coach that surfaces context-aware, data-grounded recommendations (next session length, best focus hour, burnout risk) as a small dismissible card on Dashboard and Insights — not a chatbot you have to seek out, though a full conversational companion page exists at /companion for direct Q&A. Grounded in real session history via a system-prompt guardrail against inventing statistics.

• Trust & safety — user reporting, moderation queue, blocking, room moderators, IP + device-fingerprint rate limiting on auth, CAPTCHA (Turnstile) on suspicious activity.

• Progressive navigation — the nav isn't flat. Routes are gated behind Starter / Intermediate / Advanced tiers computed from real usage (lifetime XP, streak, session count), not a settings toggle, with a power-user override for anyone who wants everything immediately (use-nav-tier.ts).

• Low Power Mode — trims particles, meteors, and parallax FX; auto-enables on prefers-reduced-motion or low battery.

• Ecosystem — an /integrations directory cataloging what's shipped (Webhooks, TypeScript SDK, MCP server) vs. what's planned (Calendar, Notion, Discord, Slack, Raycast), each honestly status-labeled.

Extensibility —

• Webhooks — subscribe to session/room events, with delivery logs and retry.
• Public TypeScript SDK (@stackd/sdk) — zero-dependency client for webhook signature verification.
• MCP server — Stack'D exposes its own Model Context Protocol endpoint (/mcp) so agents like Claude or Cursor can read a user's focus history, groups, and profile directly.

Tech stack

Layer	Technology
Frontend	React 19, TanStack Start, TanStack Router, TypeScript, Tailwind CSS v4, GSAP, Lenis, shadcn/ui, Radix UI
Backend	Supabase (Postgres, Auth, Realtime), Row-Level Security, SECURITY DEFINER PostgreSQL RPCs
Mobile	Capacitor (core + motion plugin), PWA-first architecture, native Android/iOS planned
Validation	Zod
Utilities	jsPDF, QR Code generation
Testing	Playwright Visual Regression

Getting started

git clone https://github.com/sasly2048/Stack-D.git
cd Stack-D
bun install        # or npm install

cp .env.example .env
# fill in your Supabase project URL + publishable key

bun run dev         # vite dev

Other scripts: build, build:dev, preview, lint, format.

Database schema and RLS policies live in supabase/migrations/ — apply them to a fresh Supabase project via the Supabase CLI or dashboard SQL editor.

Project structure

src/
├── routes/_authenticated/      # Application pages
├── components/                 # Shared UI components
├── hooks/                      # Custom hooks
├── lib/                        # Shared utilities and server functions
├── integrations/               # Supabase client and middleware
└── ...

supabase/
└── migrations/                 # Database schema and RLS history

tests/
└── visual/                     # Playwright visual regression suite

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening an issue or submitting a pull request. Discussions, bug reports, feature requests, and documentation improvements are all appreciated.

Status

Actively developed. Core loop, scoring integrity, RLS coverage, and progressive disclosure are solid. Known gaps: no native mobile shell yet (Android planned first, ARM64 dev machine has no iOS build path), and automated test coverage beyond visual regression is still thin relative to the reward-critical server logic.

License

MIT — see LICENSE.