organizations

├── users (role: super_admin, admin, staff, student)

│ └── staff_permissions

├── student_profiles

│ ├── student_subscriptions → subscription_plans

│ ├── student_disciplines → martial_art_disciplines → discipline_ranks

│ ├── rank_records (progression history)

│ ├── class_enrollments → classes → class_sessions → class_session_attendance

│ ├── program_assignments → programs → program_plans → exercise_plans

│ ├── body_measurements, measurement_goals

│ ├── grading_candidates → gradings

│ ├── contract_signatures, form_submissions

│ ├── event_bookings → special_events

│ └── orders → order_items → inventory → inventory_variants

├── martial_art_disciplines → discipline_ranks

├── classes → class_sessions → class_session_attendance

├── subscription_plans → plan_discount_rules, plan_classes

├── programs → program_plans → exercise_plans → sections → groups → items → exercises

├── inventory → inventory_variants, inventory_transactions

├── marketing_campaigns → notification_log

├── site_settings, blog_posts, trial_signups, contact_submissions

├── accounting_config, account_mappings, journal_entries, depreciation_schedules

└── licenses (per-module with caps, pricing, expiry)

5. API Architecture

5.1 Route Files

5.2 Middleware Stack

6. Frontend Architecture

6.1 Admin Portal Pages

6.2 Student Portal Pages

6.3 Public/Kiosk Pages (no auth guard)

6.4 Shared Components

• UI.js: Badge, Btn, Input, Table, Modal, Card, Stat, PageHeader, Tabs, FilterChips, SearchBar, Spinner, EmptyState, Avatar, Ic (SVG icons), RankChip, RankSwatch, ThemeToggle
• PlanBuilder.js: Exercise plan editor with sections, groups (supersets/circuits), items
• SubscriptionPlansManager.js: Plan templates with discount rules and class linking
• WeeklySchedule.js: CSS Grid weekly timetable

7. Key Features Detail

7.1 Multi-Discipline Martial Arts

• Unlimited disciplines per org (Karate, Krav Maga, Wing Chun, etc.)
• Each discipline: name, style/lineage, grading system type (belts/sashes/patches/levels)
• Custom rank progression per discipline with name, colour (auto-detected from name), centre stripe (white/black), dan/bar count with gold bar rendering
• Students enrolled in one or more disciplines
• Per-discipline: requirements (min classes, min months), syllabus (items with categories), grading readiness dashboard
• Gradings: events with testing fees, bulk invite from readiness, payment tracking, result marking, auto-rank award on completion

7.2 Exercise Plan System

Exercise Library (shared catalog)

└── Exercise Plans

└── Sections (Warmup, Main, Cooldown)

├── Exercise Groups (superset, circuit, straight)

│ ├── Group config: rounds, rest between rounds, timed/reps

│ └── Exercises: sets, reps, duration, rest, weight notes

└── Standalone Exercises

Programs (containers)

├── Type: personal, group, therapeutic

├── Linked Plans via program_plans (day labels)

└── Assigned to students via program_assignments

7.3 Subscription Plans & Billing

• Plan templates: module, discipline link, base price, frequency, session type, sessions/week
• Conditional discount rules: discount when student has another module/discipline/plan
• Auto-enrollment in linked classes when plan assigned
• Auto-unenrollment when plan removed (only plan-sourced enrollments)
• Price snapshot at assignment time (base, discount, final)
• Stripe integration (scaffolded): checkout for shop/grading/subscriptions, webhooks, customer portal

7.4 Shop / Point of Sale

• Product browser with size variant picker
• Cart with quantity controls, running subtotal/GST/total
• Customer: walk-in or select student
• Payment: cash, card (Stripe if configured), account balance
• Order numbering (ORD-0001)
• HTML receipt with org branding (auto-print)
• Refunds: refund/exchange/warranty types, per-item return-to-stock flag, auto stock adjustment
• Student store: browse, cart, checkout, order history

7.5 Attendance System

• 4 check-in methods: manual (roll call), kiosk (photo tap), token scan (RFID/QR/PIN), self (student phone)
• Kiosk: standalone page at /kiosk, token-authenticated, shows enrolled students for today
• Session auto-creation for recurring classes
• Attendance dashboard: overall stats, by-student, by-class, by check-in method

7.6 Accounting Integration

• Providers: Xero, MYOB, QuickBooks Online (OAuth2 scaffolded), CSV (fully working)
• 12 configurable account mappings (Australian defaults)
• Journal entry generator: 6 transaction types + depreciation
• Double-entry balanced entries with JSONB lines
• Depreciation: straight-line and ATO diminishing value
• Sync tracking: pending → synced/failed with external ID

7.7 Public Website

• Template-based per-org site with CSS custom property theming
• 8 sections (all toggleable): Hero, About, Programs, Schedule, Store, Blog, Trial Signup, Contact
• SEO: title, meta description, keywords, Open Graph
• Custom CSS override, Google Fonts selection
• Blog CMS with slugs, excerpts, featured images, publishing workflow
• Trial lead capture → admin lead pipeline
• Contact form → admin inbox

8. Security

8.1 Implemented

• JWT authentication with token refresh and revocation
• bcrypt password hashing (12 rounds)
• Parameterised SQL queries (SQL injection prevention)
• Helmet.js security headers
• CORS configuration
• Per-org rate limiting (configurable)
• Multi-tenant data isolation via org_id scoping
• Role-based access control with granular permission tags
• IP address logging on contract signatures
• Practitioner access with time-limited codes
• Kiosk device-level authentication

8.2 Recommended for Production

• SSL/TLS termination (Nginx/Caddy with Let's Encrypt)
• Environment variable encryption for secrets
• Database connection pooling with SSL
• Automated database backups
• Content Security Policy headers
• Input sanitisation for XSS prevention
• Webhook signature verification (Stripe, Xero)
• Session management for OAuth2 tokens

9. Deployment

9.1 Docker Compose Services

5 containers: db (PostgreSQL 16), api (Node.js), frontend (Nginx), license-portal (Nginx), public-site (Nginx)

9.2 Environment Variables

DATABASE_URL, JWT_SECRET, JWT_EXPIRY, CORS_ORIGIN, PORT,

LICENSE_MASTER_KEY, XERO_CLIENT_ID, XERO_CLIENT_SECRET,

MYOB_CLIENT_ID, MYOB_CLIENT_SECRET, QBO_CLIENT_ID, QBO_CLIENT_SECRET

9.3 Minimum Requirements

2GB RAM, 2 vCPU, 20GB SSD. Estimated cost: $12-24/month on DigitalOcean/Vultr.

10. File Structure

phoenix-suite/

├── docker-compose.yml

├── .env.example

├── docs/

│ ├── TECHNICAL_SPECIFICATION.md

│ └── USER_GUIDE.md

├── backend/

│ ├── Dockerfile

│ ├── package.json

│ ├── migrations/ (001-025)

│ └── src/

│ ├── index.js

│ ├── config/db.js

│ ├── middleware/

│ │ ├── auth.js

│ │ ├── errors.js

│ │ └── rateLimiter.js

│ ├── routes/

│ │ ├── auth.js, students.js, resources.js

│ │ ├── exercises.js, disciplines.js, belt-progression.js

│ │ ├── programs.js, subscription-plans.js

│ │ ├── shop.js, stripe.js

│ │ ├── checkin.js, marketing.js

│ │ ├── public.js, site-admin.js

│ │ ├── contracts-forms.js, reports.js, accounting.js

│ │ ├── practitioner-auth.js, licenses.js

│ │ └── ...

│ └── utils/

│ ├── discount-calculator.js

│ ├── plan-enrollment.js

│ ├── stripe-client.js

│ ├── email-service.js

│ ├── sms-service.js

│ ├── journal-generator.js

│ └── accounting-client.js

├── frontend/

│ ├── Dockerfile, nginx.conf, package.json

│ ├── public/ (PhoenixLogo.png, favicons, index.html)

│ └── src/

│ ├── index.js, App.js, api.js, responsive.css

│ ├── context/ (AuthContext.js, ThemeContext.js)

│ ├── components/ (UI.js, PlanBuilder.js, SubscriptionPlansManager.js, WeeklySchedule.js)

│ └── pages/

│ ├── AdminLayout.js, StudentLayout.js, LoginPage.js

│ ├── AdminPages.js (Payments, Messages, Contracts, Forms, Inventory, Equipment, Classes, MartialArts, Fitness, Settings)

│ ├── DashboardPage.js, StudentsPage.js, StudentDetailPage.js

│ ├── ExerciseLibraryPage.js, ShopPage.js, ReportsPage.js

│ ├── AccountingPage.js, MarketingPage.js, WebsitePage.js

│ ├── KioskPage.js, WorkoutDisplayPage.js

│ └── student/ (Dashboard, Classes, Gradings, Programs, Store, Documents, Profile, Messages, Billing)

├── license-portal/ (separate React app)

│ └── src/ (App.js, api.js)

└── public-site/ (separate React app)

└── src/ (App.js with template engine + SEO)