PoleDanceApp/LINEAR-ROADMAP.md

DanceChamp — Linear Roadmap

Development plan for the Pole Dance Championships app. Tech: FastAPI + SQLAlchemy (async) + Expo (React Native) + PostgreSQL. Copy each section as a Project in Linear, each checkbox as an Issue.

---

Status Legend

• ✅ = Already implemented (current MVP)
• 🔴 = Blocker (must have)
• 🟡 = Important
• 🟢 = Nice to have

---

Project 1: Database & Models Expansion

Expand the database schema from 4 tables to the full 12+ table schema required by the spec.

• ✅ users table (id, email, password, full_name, phone, role, status)
• ✅ refresh_tokens table (JWT refresh rotation)
• ✅ championships table (basic: title, description, location, event_date, status)
• ✅ registrations table (basic: user_id, championship_id, category, level, status)
• 🔴 Add organizations table — id, user_id (FK), name, instagram, email, city, logo_url, verified, status, block_reason
• 🔴 Expand championships — add subtitle, reg_start, reg_end, venue, accent_color, source (manual/instagram), instagram_media_id, image_url, raw_caption_text
• 🔴 Add disciplines table — id, championship_id (FK), name, levels (JSON array)
• 🔴 Add styles table — id, championship_id (FK), name
• 🔴 Add fees table — id, championship_id (FK), video_selection, solo, duet, group, refund_note
• 🔴 Add rules table — id, championship_id (FK), section (general/costume/scoring/penalty), name, value
• 🔴 Add judges table — id, championship_id (FK), name, instagram, bio, photo_url
• 🔴 Expand registrations — add discipline_id, style, participation_type (solo/duet/group), current_step (1-10), video_url, receipt_url, insurance_url, passed (null/true/false)
• 🔴 Add participant_lists table — id, championship_id (FK), published_by, is_published, published_at, notes
• 🔴 Add notifications table — id, user_id (FK), championship_id, type, title, message, read, created_at
• 🟡 Add activity_logs table — id, actor_id, action, target_type, target_id, details (JSON), created_at
• 🟡 Add sync_state table — key, value, updated_at (for Instagram sync tracking)
• 🔴 Create Alembic migration for all new tables
• 🔴 Update Pydantic schemas for all new/expanded models
• 🟡 Add seed data for new tables (disciplines, fees, rules, judges)

---

Project 2: Organization System

Organizations are separate entities from users. An organizer user creates/manages an organization.

• 🔴 Organization CRUD API — POST /api/v1/organizations, GET, PATCH
• 🔴 Organization approval flow — pending → admin approves → active
• 🔴 Organization verification system — verified orgs auto-approve championships
• 🔴 Link championships to organizations (not directly to users)
• 🔴 get_org_owner dependency — checks user owns the organization
• 🟡 Organization profile with logo upload
• 🟡 Mobile: Organization setup screen (name, instagram, city)
• 🟡 Mobile: Organization dashboard (list own championships)

---

Project 3: Championship Configuration (Org Side)

Organizers configure championships through tabbed interface with 5 sections.

• ✅ Basic championship CRUD (title, description, location, date)
• 🔴 Quick Create — minimal 3-field form (name, date, location) → creates draft
• 🔴 Championship setup progress tracking — 5 sections (info, categories, fees, rules, judges)
• 🔴 Categories API — CRUD for disciplines + levels per championship
• 🔴 Styles API — CRUD for styles per championship
• 🔴 Fees API — set video_selection, solo, duet, group fees
• 🔴 Rules API — add/remove general rules, costume rules, scoring criteria, penalties
• 🔴 Judges API — CRUD for judge profiles per championship
• 🔴 "Go Live" endpoint — validates all sections done, sets status
• 🔴 Registration period — reg_start, reg_end dates; auto-close when expired
• 🔴 Mobile: Championship config tabs (Overview, Categories, Fees, Rules, Judges)
• 🔴 Mobile: Tag editor component (for rules, levels, styles)
• 🔴 Mobile: "Mark as Done" per section + progress checklist
• 🟡 Mobile: Inline editing for championship info fields
• 🟡 Championship status guard — prevent edits on live championships

---

Project 4: Enhanced Member Experience

Rich championship browsing with 5-tab detail view, search, and filtering.

• ✅ Championship list screen
• ✅ Basic championship detail screen
• 🔴 Championship Detail — 5 tabs: Overview, Categories, Rules, Fees, Judges
• 🔴 Overview tab — event info, registration period, member count, "Register" button
• 🔴 Categories tab — show disciplines with levels and styles
• 🔴 Rules tab — general rules, costume rules, scoring criteria, penalties
• 🔴 Fees tab — video selection + championship fees breakdown
• 🔴 Judges tab — judge profiles with photo, instagram, bio
• 🔴 Search championships — full-text search by name/org
• 🔴 Filter championships — by discipline, location, status (open/upcoming/past)
• 🟡 Sort championships — by date, by popularity
• 🟡 Home screen dashboard — active registrations with progress, upcoming championships
• 🟡 Pull-to-refresh on all list screens
• 🟢 Championship image/poster display

---

Project 5: 10-Step Registration Progress Tracker

Members track their championship registration through 10 steps with uploads and auto-updates.

• ✅ Basic registration (submit application)
• ✅ Registration status display (submitted/accepted/rejected)
• 🔴 10-step progress model — current_step field on registration
• 🔴 Step 1: Review rules — auto-mark when user opens Rules tab
• 🔴 Step 2: Select category — saved from registration form (discipline + level + style)
• 🔴 Step 3: Record video — manual toggle
• 🔴 Step 4: Submit video form — manual toggle or external link
• 🔴 Step 5: Pay video fee — upload receipt screenshot
• 🔴 Step 6: Wait for results — pending state until org decides
• 🔴 Step 7: Results — auto-updates when org passes/fails video
• 🔴 Step 8: Pay championship fee — upload receipt (only if passed)
• 🔴 Step 9: Submit "About Me" — manual toggle or external link
• 🔴 Step 10: Confirm insurance — upload insurance document
• 🔴 Mobile: Vertical step list with icons, status (locked/available/done/failed)
• 🔴 Mobile: Progress bar (X/10 completed)
• 🔴 Mobile: Step detail expansion with action area
• 🟡 Mobile: "My Championships" with Active/Past tabs and progress bars

---

Project 6: File Upload System

Receipt photos, insurance documents, judge photos, org logos.

• 🔴 File upload API endpoint — POST /api/v1/uploads
• 🔴 Local file storage (dev) with configurable S3/Supabase Storage (prod)
• 🔴 Receipt photo upload — camera/gallery picker → upload → pending confirmation
• 🔴 Insurance document upload — same flow
• 🔴 Serve uploaded files — GET /api/v1/uploads/{filename}
• 🟡 Judge profile photo upload
• 🟡 Organization logo upload
• 🟡 Image compression before upload (mobile side)
• 🟡 File type validation (images only for receipts, PDF/images for insurance)

---

Project 7: Organizer — Member Management

Organizers review members, pass/fail videos, confirm payments, publish results.

• 🔴 Members list per championship — GET /api/v1/championships/{id}/members
• 🔴 Member detail — registration info, video link, receipt, progress
• 🔴 Edit member's level/style (with notification trigger)
• 🔴 Video review — Pass/Fail buttons per member
• 🔴 Payment confirmation — Confirm receipt button
• 🔴 Results tab — pending/passed/failed counts, "Publish Results" button
• 🔴 Mobile: Member list with search + filter chips (All, Receipts, Videos, Passed)
• 🔴 Mobile: Member detail screen with action buttons
• 🔴 Mobile: Results screen with Pass/Fail workflow
• 🟡 Filter members by status (pending receipt, pending video, passed, failed)
• 🟡 Bulk actions — pass/fail multiple members at once

---

Project 8: Notification System

In-app notifications + push notifications via Expo Push Service.

• 🔴 Notification model + CRUD API
• 🔴 In-app notification feed — GET /api/v1/notifications
• 🔴 Mark notification as read — PATCH /api/v1/notifications/{id}/read
• 🔴 Mark all as read — POST /api/v1/notifications/read-all
• 🔴 Notification triggers:
  • Video passed/failed → member notification
  • Payment confirmed → member notification
  • Level/style changed → member notification
  • Results published → all registrants notified
  • User approved → welcome notification
  • Championship goes live → all platform notification
• 🔴 Expo Push Token registration — PATCH /api/v1/users/me/push-token
• 🔴 Expo Push Service integration — send push on notification create
• 🔴 Mobile: Bell icon with unread count badge
• 🔴 Mobile: Notification feed screen (cards with icon, type, message, timestamp)
• 🟡 Push notification preferences (toggles for each type)
• 🟡 Deadline reminders — auto-send 7d, 3d, 1d before registration closes
• 🟢 Email notifications (secondary channel)

---

Project 9: Instagram Integration

Automatically sync championship announcements from organizer's Instagram Business account.

• 🔴 Instagram Graph API client — fetch recent posts from Business/Creator account
• 🔴 Caption parser — extract title (first line), location, date from caption text
• 🔴 Date parser — support Russian ("15 марта 2025") and English ("March 15 2025") + numeric (15.03.2025)
• 🔴 Location parser — detect "Место:", "Адрес:", "Location:", "Venue:", "Зал:"
• 🔴 Championship upsert — use instagram_media_id as dedup key, create as draft
• 🔴 APScheduler polling — run every 30 min via FastAPI lifespan event
• 🔴 Sync state tracking — store last sync timestamp, only process new posts
• 🔴 Long-lived token management — store in .env, auto-refresh before 60-day expiry
• 🔴 Token refresh scheduler — weekly job to call Graph API token exchange
• 🟡 Image sync — save media_url as championship image
• 🟡 Manual import button — "Import from Instagram" in org dashboard
• 🟡 Error handling — failed parsing saves raw caption for manual review
• 🟢 Multiple Instagram accounts support (one per org)

---

Project 10: Enhanced Admin Panel

Full admin capabilities: org management, championship moderation, user management.

• ✅ Basic admin panel (approve/reject pending users)
• 🔴 Admin dashboard — stats (active orgs, live champs, total users)
• 🔴 "Needs Attention" section — pending orgs + pending championships
• 🔴 Organization management — list, detail, approve/reject/block/unblock/verify
• 🔴 Championship moderation — list, detail, approve/reject (from unverified orgs), suspend/reinstate
• 🔴 Enhanced user management — warn, block/unblock, view activity
• 🔴 Activity log — recent actions across the platform
• 🟡 Mobile: Admin dashboard with stat cards
• 🟡 Mobile: Organization list + detail screens
• 🟡 Mobile: Championship moderation screens
• 🟢 Web admin panel (React + Vite, same API)

---

Project 11: Auth & Security Hardening

Production-ready auth, rate limiting, CORS, input validation.

• ✅ JWT access + refresh token rotation
• ✅ bcrypt password hashing
• ✅ Role-based route protection (dependency chain)
• 🔴 Rate limiting on auth endpoints (slowapi)
• 🔴 CORS configuration (whitelist mobile app + admin panel origins)
• 🔴 Input validation — Pydantic strict mode, length limits, email format
• 🔴 Password strength requirements (min 8 chars, mixed case, number)
• 🟡 Account lockout after N failed login attempts
• 🟡 HTTPS enforcement in production
• 🟡 Audit logging — log all admin actions
• 🟢 Google OAuth login (alternative to email/password)
• 🟢 Two-factor authentication

---

Project 12: PostgreSQL & Production Infrastructure

Migrate from SQLite to PostgreSQL, containerize with Docker.

• 🔴 PostgreSQL support in database.py (async via asyncpg)
• 🔴 docker-compose.yml — PostgreSQL 16 + FastAPI containers
• 🔴 Dockerfile for backend
• 🔴 Environment config — .env.example with all required variables
• 🔴 Alembic migration compatibility — ensure all migrations work on PostgreSQL
• 🔴 Production ASGI server — gunicorn + uvicorn workers
• 🟡 Health check endpoint improvements
• 🟡 Structured logging (JSON format for production)
• 🟡 Database connection pooling
• 🟢 CI/CD pipeline (GitHub Actions — lint, test, build)
• 🟢 Deployment to cloud (VPS / Railway / Fly.io)

---

Project 13: Testing

Comprehensive test coverage for backend and mobile.

• 🔴 pytest setup with async fixtures (httpx + AsyncClient)
• 🔴 Auth tests — register, login, refresh, logout, me, role checks
• 🔴 Championship tests — CRUD, status transitions, permission checks
• 🔴 Registration tests — submit, duplicate guard, closed registration guard
• 🔴 Admin tests — approve/reject users, org management
• 🔴 Instagram parser tests — various caption formats, edge cases
• 🔴 Notification tests — trigger conditions, push delivery
• 🟡 Integration tests — full flows (register → apply → review → publish)
• 🟡 Mobile: TypeScript strict mode + path aliases (@api/, @store/, @screens/*)
• 🟢 E2E tests (Detox or Maestro for mobile)
• 🟢 Load testing (locust or k6)

---

Project 14: Design System & UI Polish

Consistent dark luxury theme across all screens, smooth animations.

• 🟡 Design tokens — colors, typography, spacing constants file
• 🟡 Typography — Playfair Display (headings) + DM Sans (body) + JetBrains Mono (badges)
• 🟡 Component library — Button, Card, Badge, TabBar, TagEditor, LoadingOverlay
• 🟡 Dark luxury theme — dark backgrounds (#08070D), pink/purple accents
• 🟡 Loading skeletons on all list screens
• 🟡 Empty states — custom illustrations per screen
• 🟡 Error states — friendly messages + retry buttons
• 🟡 Animations — tab transitions, card press, progress bar fill
• 🟢 Haptic feedback on key actions
• 🟢 Swipe gestures on member cards (pass/fail)
• 🟢 Onboarding walkthrough for first-time users

---

Project 15: Internationalization (Post-MVP)

Russian + English language support.

• 🟢 i18n setup (react-i18next or similar)
• 🟢 Extract all strings to translation files
• 🟢 Russian translations
• 🟢 Language switcher in profile settings
• 🟢 Date/time formatting per locale

---

Recommended Priority Order

If you need to ship fast, work in this order:

Priority	Project	Why
1	Project 1: Database Expansion	Foundation for everything else
2	Project 2: Organization System	Core business entity
3	Project 3: Championship Config	Orgs need to create proper championships
4	Project 4: Enhanced Member UX	Members need to see championship details
5	Project 5: 10-Step Progress	Core differentiator — step-by-step registration
6	Project 6: File Uploads	Required for receipts + insurance steps
7	Project 7: Member Management	Orgs need to review and manage members
8	Project 8: Notifications	Users need to know what's happening
9	Project 9: Instagram Sync	Automate championship creation
10	Project 10: Enhanced Admin	Full platform control
11	Project 11: Security	Production hardening
12	Project 12: PostgreSQL + Docker	Production deployment
13	Project 13: Testing	Quality assurance
14	Project 14: Design System	Visual polish
15	Project 15: i18n	Post-launch

---

Current State Summary

What's Built (MVP)

• FastAPI backend with SQLite (async)
• JWT auth with refresh token rotation
• 4 tables: users, refresh_tokens, championships, registrations
• Member auto-approve, organizer requires admin approval
• Championship list + basic detail
• Registration form + "My Registrations" with championship info
• Admin panel (approve/reject pending users)
• Profile screen with role badges
• Tab navigation with Ionicons

What's Next (Sprint 1 recommended)

1. Database expansion (Project 1)
2. Organization system (Project 2)
3. Championship configuration tabs (Project 3)