Gamified Study Accountability & Challenge Management Platform
Replacing manual Discord spreadsheets, YPT screenshot tracking, and host burnout with an automated challenge engine.
Study challenges in Discord communities (running weekly team accountability duels, productivity sprints, and study seasons) suffer from severe Admin Burnout. Community moderators spend 5–10 hours every week manually building complex spreadsheets, copy-pasting YPT daily timestamps across 20+ columns, calculating team hour differences, verifying individual to-do goals, and enforcing server Punishment PFPs.
HoldMeToIt automates the entire lifecycle of Discord study battles:
- Instant Challenge Setup: Hosts configure battle cycles (e.g. Tuesday–Monday), team rosters, and punishment rules in minutes.
- Declared Individual Targets & Weekly Goals: Each participant declares their own weekly study-hour target (e.g. 20h, 35h, 50h, 70h) and mandatory weekly goals in the pre-kickoff phase.
- Clock-Time Self-Logging (
HH:MM:SS): Instant daily logging matching Yeolpumta (YPT) clock displays down to the second with a 24-hour daily safety limit. - The Catch-Up Deficit Engine: Zero grace days. Missed hours dynamically roll over into remaining challenge days with real-time pace guidance.
- Team vs Team Match Scoreboard: Live head-to-head banner (e.g., Bees vs Butterflies), lead delta (
+Xh Ym Zs ahead), and unified standings table. - Dual-Failure Accountability & Punishment PFP: Automatic flagging if hours or goals fail, paired with a direct 1-click Download Punishment PFP button.
- Discord Integration: Frictionless Discord OAuth login with public read-only spectator mode.
The technology stack is locked to guarantee high velocity, zero CORS overhead, and strict end-to-end type safety:
| Layer / Role | Ratified Technology | Architectural Purpose |
|---|---|---|
| Framework | Next.js 14 (App Router) | Unified fullstack SSR/Client architecture, zero CORS, edge-ready |
| Language | TypeScript 5.x (strict: true) |
End-to-end type safety across DB, API, and UI |
| Styling & Theme | Tailwind CSS + shadcn/ui | Obsidian dark theme (DESIGN.md), responsive down to 360px |
| Database Engine | PostgreSQL (Supabase / Neon) | Relational integrity for challenges, teams, and daily logs |
| Object Storage | Supabase Storage | Server-only uploads of event banners & punishment PFPs |
| ORM & Migrations | Prisma ORM 6.x | Declarative schemas, type-safe queries, migration control |
| Authentication | Auth.js (NextAuth.js v5 beta) | Discord OAuth 2.0 (identify scope), guild-role RBAC, spectator fallback |
| Offline Storage | Browser IndexedDB | Offline-first to-do tasks with background sync (/api/tasks/sync) |
| Observability | LogRocket | Session replay, error boundaries, feedback correlation |
| Testing & Math | Vitest 3.x | Fast ESM runner for pure domain time math and deficit logic |
| Validation | Zod 4.x | Strict runtime payload validation at API boundaries |
- Phase 0 (MVP Core): ~65% feature parity. The core loop (login → enroll → log hours → live scoreboard → catch-up pace) works. Several host and accountability UIs still need rebuilding after the Obsidian redesign.
- Quality gates: typecheck ✅ · 559/559 tests ✅ · production build ✅
- See ROADMAP.md §0 for status vs timeline and HANDOFF.md for the verified feature matrix, defect list, and exact next step.
The project maintains a lean, highly focused documentation and specification suite:
| Document | Primary Authority & Purpose |
|---|---|
| FEATURES.md | Absolute source of truth for product behavior, screen layouts, UX flows, and phase tags ([P0] to [V2]). |
| DESIGN.md | Absolute source of truth for visual identity, Obsidian theme, color tokens, typography, and mobile responsive rules. |
| AGENTS.md | Absolute source of truth for agent protocol, locked stack, stack laws L1–L9, git safety, and quality matrix. |
| ROADMAP.md | Product and technical evolution trajectory across phases ([P0] MVP [P1] [V1] [V2]), plus current status vs timeline. |
| HANDOFF.md | Living operational relay, verified feature completion matrix, known defects, and next step between engineering sessions. |
| README.md | Developer onboarding, mission overview, locked stack matrix, and local dev setup. |
| prisma/migrations/README.md | Migration baseline procedure and known schema drift. |
apps/
├── web/ # Next.js app (app/, core/, features/, components/, lib/, types/)
├── tasker/ # Discord task/category bot (Node + tsx; src/, test/)
└── ypt-bot/ # YPT study-log ingestion bot (Node ESM; src/, test/)
packages/
├── database/ # Shared Prisma schema, migrations, seed, and client singleton
│ ├── prisma/ # schema.prisma + migrations/
│ └── src/index.ts # @holdmetoit/database (built to dist/)
└── discord/ # Shared discord.js REST client + bot runtime
└── src/ # @holdmetoit/discord (built to dist/; ./bot subpath)
docs/ # Shared feature documentation (pokemon, economy, feature-flags, ypt-bot, tasker)
AGENTS.md · DESIGN.md · FEATURES.md · ROADMAP.md · HANDOFF.md · CHANGELOG.md
apps/web keeps the Feature-First slices (features/<slice>/ → domain/ · data/ · api/ · presentation/). Both apps consume the single @holdmetoit/database client against the same PostgreSQL database.
@holdmetoit/discord— discord.js v14 REST helpers used by the web app (feedback embeds, avatar sync, guild-role lookup). Rate limiting, retries and 429 handling come from discord.js.@holdmetoit/discord/bot— gateway runtime for long-lived bots: client factory, command/event loaders, interaction + prefix dispatch, slash-command deployment,/health, and graceful shutdown.apps/tasker— the migrated Tasker bot; seedocs/tasker/README.md.
| Role | Primary Layer Responsibilities |
|---|---|
| Data & Identity | Database schema, Prisma migrations, Auth.js Discord OAuth, session hydration, and repositories. |
| Scoring & Engine | Pure domain math, HH:MM:SS duration converters, team score aggregations, catch-up deficit calculator, Vitest suite. |
| Participant UI | Home cockpit, HH:MM:SS Log Hours modal, Daily/Weekly task board, progress meters, mobile responsiveness (360px+). |
| Admin Operations | Host wizard, Manage tab (teams, assignments, kickoff/lock), admin inline hours override, pardons, Punishment PFP hub. |
- Node.js 22+ (required by
@supabase/supabase-js2.117+) - A Supabase (or Neon) PostgreSQL database, plus a public Supabase Storage bucket
- A Discord Developer Portal application (OAuth 2.0) and a bot token that's a member of your guild (used for role lookup and feedback embeds)
git clone https://github.com/Afnanpathan2004/holdmetoit.git
cd holdmetoit
npm install # workspaces + prisma generate + builds @holdmetoit/database
cp apps/web/.env.example apps/web/.env
# The bots read the repo-root .env (apps/tasker/.env.example documents its variables)| Variable | Purpose |
|---|---|
DATABASE_URL, DIRECT_URL |
Pooled and direct Postgres connections |
AUTH_SECRET, AUTH_URL |
Auth.js session secret and base URL |
AUTH_DISCORD_ID, AUTH_DISCORD_SECRET |
Discord OAuth app (identify scope) |
DISCORD_GUILD_ID, DISCORD_BOT_TOKEN |
Guild + bot used to read member roles |
DISCORD_ADMIN_ROLE_IDS |
Comma-separated guild role IDs that map to ADMIN |
DEV_DISCORD_IDS |
JSON array of Discord snowflakes that map to DEV (full access) |
DISCORD_FEEDBACK_CHANNEL_ID / _BUG_CHANNEL_ID / _SUGGESTIONS_CHANNEL_ID |
Feedback embed destinations (optional; falls back to a default channel) |
GITHUB_TOKEN, GITHUB_REPO |
Optional GitHub issue sync (fine-grained PAT with Issues read/write) |
GITHUB_ISSUE_LABELS_BUG, GITHUB_ISSUE_LABELS_ENHANCEMENT |
Comma-separated labels for auto-created issues |
GITHUB_ISSUE_ASSIGNEES, GITHUB_API_URL |
Optional assignees and API base URL (defaults to https://api.github.com) |
JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN, JIRA_PROJECT_KEY |
Optional Jira Cloud issue sync (API token Basic auth) |
JIRA_LABELS, JIRA_ASSIGNEE_ACCOUNT_ID |
Optional base labels and assignee for auto-created Jira issues |
SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY |
Server-only storage client (never prefix with NEXT_PUBLIC_) |
SUPABASE_STORAGE_BUCKET |
Public bucket name |
SUPABASE_EVENT_BANNERS_FOLDER, SUPABASE_PUNISHMENT_PFPS_FOLDER |
Separate directories for event headers and punishment PFPs |
SUPABASE_FEEDBACK_ATTACHMENTS_FOLDER |
Feedback media directory (optional; defaults to feedback-attachments) |
Review packages/database/prisma/migrations/README.md before applying migrations.
Warning
Known schema drift: the feedbacks table and the sort_order columns on categories/tasks were applied with prisma db push and have no migration files yet. On a fresh database, prisma migrate deploy alone produces an incomplete schema. Until catch-up migrations land (HANDOFF.md D5), run npx prisma db push on fresh local dev databases only.
npm run db:migrate # apply migration history (packages/database)
npm run dev:web # http://localhost:3000Existing databases previously created with db push must be backed up and verified against the baseline before marking it applied (see the migration README). Don't run the baseline SQL against a populated database.
# Seed sample challenge (Honey Bees vs Lavender Butterflies) and system feature flags
npm run db:seednpm run typecheck:web # tsc --noEmit (apps/web)
npm run test:web # vitest run (apps/web)
npm run build:web # next build (apps/web)
npm run typecheck:tasker # tsc --noEmit (apps/tasker)
npm run test:tasker # vitest run (apps/tasker)
npm run test:ypt-bot # node --test (apps/ypt-bot)