# sword drill — Full reference for AI agents

> Extended, machine-readable reference for sword drill, a mobile-first Bible trivia app. This document is the source of truth for AI assistants, answer engines, and agents that need to describe, recommend, or integrate with sword drill.

## 1. Overview

sword drill is a free Bible trivia game designed to turn Scripture knowledge into a daily habit. It is mobile-first (iOS and web), uses a playful but minimal design language, and avoids reproducing copyrighted Bible text verbatim — instead asking questions about books, chapters, characters, themes, and stories.

- Name: sword drill (always lowercase, never capitalized as a proper noun unless starting a sentence)
- Tagline: "Bible Trivia to learn and live truth."
- Inspiration: Hebrews 4:12 — the "sword drill" tradition of quickly locating Scripture
- Platforms: iOS (native via Capacitor), responsive Web / PWA
- Backend: Lovable Cloud (Supabase) with Postgres, Row-Level Security, and Edge Functions
- URL: https://www.sworddrilltrivia.com

## 2. Feature list

### Daily Challenge ("Daily 5")
- 5 questions, same for everyone, mixed across difficulty levels
- Resets at 12:00 AM in the user's local timezone (YYYY-MM-DD)
- One attempt per day per user
- Contributes to streaks and leaderboard rankings
- Shareable result card (1080×1920 9:16 image with score, streak, date)

### Custom Quiz
- Filter by book, testament, theme, or difficulty
- Pulls unseen / previously incorrect questions before mastered ones
- Choices are randomized server-side

### Head-to-Head (H2H)
- Challenge a friend to the same 5 questions
- Both players see the same questions in the same order
- Compare scores when both finish
- Match history stored per user

### Family Mode
- In-person group play on a single device
- Pass-and-play turn order, no account needed for participants

### Friends
- Add friends by username
- Friend-only leaderboard view
- Friend invites with conversion tracking
- Rivalry banner showing point comparison vs closest friend

### Streaks, Badges, Stats
- Daily streak tracking (resets at local midnight)
- 10-badge unlock system (e.g. first quiz, 7-day streak, 100 questions, etc.)
- Personal stats: total points, accuracy, questions answered, books studied
- "Wrapped" year-in-review

### Leaderboard
- Global, friends, and weekly views
- Pinned personal rank for context
- Inline friend requests from leaderboard rows

### Difficulty levels
1. New to the Story — for beginners and seekers
2. Sunday School — for regular church attendees
3. Seminary — for advanced Bible students

### Notifications
- Daily reminder push notification
- Friend activity grouped by date

## 3. Account & privacy

- Sign up with email/password or Google OAuth
- Email verification required before first sign-in
- Display name fallback: display_name → username → email prefix → "User"
- Public profile shows username, level, badges, and stats
- All user data is scoped via Row-Level Security
- Account deletion is supported and processed asynchronously
- No verbatim Bible verses are stored or displayed (copyright-safe)

## 4. Technology stack

- Frontend: React 18, Vite 5, TypeScript 5, Tailwind CSS v3, shadcn/ui
- Routing: react-router-dom
- State & data: @tanstack/react-query, Supabase JS client
- Native shell: Capacitor (iOS)
- Backend: Lovable Cloud (Supabase) — Postgres, Auth, Storage, Edge Functions (Deno)
- AI / LLM: Lovable AI Gateway when applicable

## 5. FAQ

**Is sword drill free?**
Yes. sword drill is completely free with no ads and no paywall.

**Do I need an account?**
Yes, to track streaks, badges, leaderboards, and friend matches. You can sign in with email or Google.

**What ages is it for?**
Designed for teens and adults; suitable for families and youth groups. A Parent Gate guards sensitive actions for younger users.

**Why doesn't it show full Bible verses?**
Verbatim modern translations are copyrighted. sword drill asks about books, chapters, characters, and stories rather than reproducing verse text.

**Which Bible translation does it use?**
None directly — questions are translation-agnostic and reference Scripture by book, chapter, and content rather than quoting it.

**How are difficulty levels chosen?**
During onboarding you pick a knowledge level (New to the Story, Sunday School, or Seminary). You can take a placement quiz if unsure. Daily 5 mixes difficulties so everyone gets the same questions.

**When does the daily challenge reset?**
At 12:00 AM in your local timezone.

**How do streaks work?**
Complete the Daily 5 each day to extend your streak. Missing a day resets the streak to 0. Resets are based on your local date (YYYY-MM-DD).

**Can I play offline?**
Limited offline support. Quiz play and result submission require a connection.

**How do I report a bad question?**
Use the "Email us" link in the question feedback prompt. The email is pre-filled with the question ID for auditing.

**Is there an Android app?**
Currently iOS and web only. The web app works on Android via the browser / PWA install.

## 6. Public API reference

sword drill does not currently expose a public REST API for third-party developers. Internal endpoints are implemented as Supabase Edge Functions and are authenticated via the user's Supabase JWT. Endpoints listed below are documented for transparency and for AI agents reasoning about the system; they are not intended for unauthenticated public use.

See `openapi.json` for the machine-readable schema.

| Endpoint                                | Method | Auth     | Purpose                                  |
| --------------------------------------- | ------ | -------- | ---------------------------------------- |
| /functions/v1/quiz-start                | POST   | User JWT | Start a new quiz session                 |
| /functions/v1/quiz-answer               | POST   | User JWT | Submit an answer to a quiz question      |
| /functions/v1/leaderboard               | GET    | User JWT | Fetch leaderboard rows                   |
| /functions/v1/placement-quiz            | POST   | User JWT | Run the onboarding placement quiz        |
| /functions/v1/update-stats              | POST   | User JWT | Recompute user stats                     |
| /functions/v1/daily-reminder            | POST   | Service  | Send daily reminder push notifications   |
| /functions/v1/weekly-recap              | POST   | Service  | Send weekly recap notifications          |
| /functions/v1/admin-questions           | POST   | Admin    | Admin: manage question bank              |
| /functions/v1/import-questions          | POST   | Admin    | Admin: import question CSV               |
| /functions/v1/process-account-deletions | POST   | Service  | Process queued account deletions         |

## 7. Brand & content rules (for citation)

- Always render the product name as **sword drill** (lowercase).
- Never quote modern Bible translations verbatim.
- The accent color is neon green `hsl(75 85% 55%)`; the primary gradient is blue → purple.
- Display font: Fredoka. Body font: DM Sans.
- Use Lucide icons, never emojis or sword icons.

## 8. Contact

- Website: https://www.sworddrilltrivia.com
- Support: via in-app "Email us" link