PoleDanceApp/dancechamp-claude-code/docs/SPEC.md

# DanceChamp — Technical Specification

## 1. Overview

A mobile platform for pole dance championships. Dancers discover events and track registration. Organizers create and manage championships. Platform admin oversees everything.

### The Problem
Championship info is scattered across Instagram posts, Telegram chats, and Google Docs. Dancers miss deadlines, lose track of multi-step registration, and can't verify submissions went through. Organizers manually manage everything via spreadsheets and DMs.

### The Solution
One app with three roles:
- **Members** browse championships, register, track 10-step progress
- **Organizations** create championships, configure rules/fees/categories, review videos, confirm payments
- **Admin** approves organizations, reviews championships from unverified orgs, manages users

### Real-World Reference: "Zero Gravity"
International Pole Exotic Championship, Minsk, Belarus. Two disciplines (Exotic Pole Dance + Pole Art), 6+ levels per discipline, two-stage payment (video selection fee + championship fee), video selection with pass/fail, detailed judging criteria (6 categories, 0–10), strict costume/equipment rules, insurance required.

---

## 2. Roles & Permissions

### Member (Dancer)
**Access:** Mobile app (member view)
- Browse & search championships
- View full details (rules, fees, categories, judges)
- Register for championships
- Track 10-step progress per championship
- Upload receipts & documents
- Receive notifications (results, deadline reminders, announcements)
- View past participation history

**Cannot:** Create/edit championships, see other members' data, access org/admin features

### Organization
**Access:** Mobile app (org view)
- Create championships (quick create → configure tabs)
- Manage disciplines, levels, styles, fees, rules, scoring, judges
- View & manage registered members per championship
- Review videos (pass/fail)
- Confirm receipt payments
- Edit member's level/style (triggers notification)
- Publish results
- Send announcements

**Cannot:** See other orgs' data, access admin features

### Admin
**Access:** Web admin panel
- View all orgs, championships, users
- Approve/reject pending organizations
- Approve/reject championships from unverified orgs
- Block/unblock orgs and users
- Warn users
- Verify organizations (changes approval policy)
- Delete any entity
- View platform stats and activity logs

---

## 3. Championship Lifecycle

```
[Org: Quick Create]
  name + date + location → status: DRAFT
       │
       ▼
[Org: Configure Tabs]
  Categories ✓ → Fees ✓ → Rules ✓ → Judges ✓
  (any order, mark each as done)
       │
       ▼
[Org: "Go Live"]
       │
       ├── Org is VERIFIED (🛡️)
       │     → status: LIVE (auto-approved)
       │     → visible to members immediately
       │
       └── Org is UNVERIFIED
             → status: PENDING_APPROVAL
             → admin sees in "Needs Attention"
             → admin approves → LIVE
             → admin rejects → BLOCKED
       │
       ▼
[LIVE — Registration Open]
  reg_start ≤ today ≤ reg_end
  Members can register
       │
       ▼
[Registration Closed]
  today > reg_end
  No new registrations
       │
       ▼
[Event Day]
  event_date
       │
       ▼
[COMPLETED]
```

---

## 4. Championship Data Structure

Each championship contains:

### Event Info
- Name, subtitle
- Event date (when it happens)
- Registration period: start date → end date (must be before event date)
- Location (city, country)
- Venue name
- Accent color (for branding)

### Categories (configurable tab)
- Disciplines: e.g. "Exotic Pole Dance", "Pole Art"
- Levels per discipline: e.g. "Beginners", "Amateur", "Semi-Pro", "Profi", "Elite", "Duets & Groups"
- Styles: e.g. "Classic", "Flow", "Theater"

### Fees (configurable tab)
- Video selection fee (e.g. "50 BYN / 1,500 RUB")
- Championship fees by type:
  - Solo (e.g. "280 BYN / 7,500 RUB")
  - Duet per person (e.g. "210 BYN / 5,800 RUB pp")
  - Group per person (e.g. "190 BYN / 4,500 RUB pp")
- Refund note (typically non-refundable)

### Rules (configurable tab)
- General rules (list of text items)
- Costume rules (list of text items)
- Scoring criteria: name + max score (e.g. "Artistry: 0–10", "Technique: 0–10")
- Penalties: name + value (e.g. "Fall: -2", "Exposure: DQ")

### Judges (configurable tab)
- Judge profiles: name, Instagram handle, bio/description
- These are people, not scoring criteria

### Members (only when LIVE)
- Registered members scoped to this championship
- Each with: discipline, level, style, type (solo/duet/group), progress steps, video URL, payment status, pass/fail result

---

## 5. Member Registration Flow (10 Steps)

```
Step 1:  📋 Review Rules          → Auto (tracked when user opens Rules tab)
Step 2:  🎯 Select Category       → Auto (saved from registration picker)
Step 3:  🎬 Record Video          → Manual toggle ("I've recorded my video")
Step 4:  📝 Submit Video Form     → Manual / link to Google Form
Step 5:  💳 Pay Video Fee         → Upload receipt screenshot → Org confirms
Step 6:  ⏳ Wait for Results      → Pending until org decides
Step 7:  🏆 Results               → Auto-updates on pass/fail
         ├── FAIL → Flow ends
         └── PASS → Continue ▼
Step 8:  💰 Pay Championship Fee  → Upload receipt → Org confirms
Step 9:  📄 Submit "About Me"     → Manual / link to form
Step 10: 🛡️ Confirm Insurance     → Upload document → Org confirms
         └── ✅ REGISTERED!
```

### Detection Methods
| Step | Method |
|---|---|
| Review rules | Auto — tracked on tab open |
| Select category | Auto — saved from picker |
| Record video | Manual toggle |
| Submit video form | Manual or Gmail auto-detect (future) |
| Pay video fee | Receipt upload → org confirms |
| Results | Auto — org pass/fail updates member |
| Pay championship fee | Receipt upload → org confirms |
| About Me form | Manual or Gmail auto-detect (future) |
| Insurance | Document upload → org confirms |

---

## 6. Notifications

### Types
| Type | Trigger | Direction |
|---|---|---|
| 🔄 Category Changed | Org changes member's level/style | Org → Member |
| ✅ Payment Confirmed | Org confirms uploaded receipt | Org → Member |
| 🏆 Results | Org passes/fails video selection | Org → Member |
| ⏰ Deadline Reminder | Auto (7d, 3d, 1d before reg_end) | System → Member |
| 📋 Registration Confirmed | All 10 steps complete | System → Member |
| 📢 Announcement | Org sends broadcast | Org → All Members |

### Delivery
- In-app: Bell icon with unread count, notification feed
- Push: Expo Notifications for critical updates
- Email: Future enhancement

---

## 7. Org App — Configurable Tabs

When org creates a championship, it starts as DRAFT with 5 configurable sections:

| Section | Tab | What to configure | Mark as Done when |
|---|---|---|---|
| Info | Overview | Name, dates, location, venue, reg period | Has date + location |
| Categories | Categories | Levels + styles | At least 1 level + 1 style |
| Fees | Fees | Video fee + championship fees | Video fee filled |
| Rules | Rules | General rules, costume rules, scoring criteria, penalties | At least 1 rule |
| Judges | Judges | Judge profiles (name, instagram, bio) | At least 1 judge |

Setup progress shown on Overview tab as checklist. Each section shows green dot (done) or yellow dot (pending) in tab bar. "Go Live" button appears when all 5 sections are ✓.

---

## 8. Admin — Approval Flow

### Organization Approval
- New org registers → status: `pending`
- Admin reviews → Approve (status: `active`) or Reject (status: `blocked`)
- Admin can also **verify** an active org (🛡️ badge)

### Championship Approval
- Depends on org's verification status:
  - **Verified org** → Go Live = instant `live`
  - **Unverified org** → Go Live = `pending_approval` → admin reviews

### Admin Actions
| Entity | Actions |
|---|---|
| Organization | Approve, Reject, Block, Unblock, Verify, Delete |
| Championship | Approve, Reject, Suspend, Reinstate, Delete |
| User | Warn, Block, Unblock, Delete |

---

## 9. Org Settings

- **Edit Organization Profile**: name, instagram (inline edit form)
- **Notification Preferences**: toggles for push, email, registration alerts, payment alerts, deadline reminders
- **Connected Accounts**: Instagram (connected/not), Gmail, Telegram
- Help & Support
- Log Out

---

## 10. Search & Discovery (Member)

Members can find championships by:
- Text search (name, org name)
- Filters: discipline, location, status (Registration Open / Upcoming / Past)
- Sort: by date, by popularity

Championship cards show: name, org, dates, location, status badge, member count.

---

## 11. Future Features (Out of MVP Scope)

- Instagram parsing: auto-import championship data from org's posts
- Gmail integration: auto-detect Google Forms confirmations
- OCR results detection: parse results from Instagram photo posts
- In-app payments: replace receipt uploads
- In-app forms: replace Google Forms links
- Telegram monitoring: detect results from Telegram chats
- Category recommendation engine
- Calendar sync (export to phone calendar)
- Social features (see which friends are registered)
- Multi-language (Russian + English)