# Solution Overview

## 1. Proposed System Architecture

The platform is designed as a modular PHP 8 + MySQL web application with server-side rendered pages and a thin service/repository layer.

### Architecture style

- Presentation layer: PHP templates and page controllers
- Application layer: auth, RBAC, validation, workflow services
- Data layer: PDO repositories over a normalized MySQL schema
- Integration layer: payment gateway, email, and future ranking imports

### Recommended deployment shape

- `public/` as the web root
- Apache or Nginx with HTTPS enabled
- PHP-FPM or mod_php
- MySQL 8 with daily backups
- Separate storage path for uploaded files and exports

### Why this fits 5,000 users

- 5,000 users is well within the range of a properly indexed PHP/MySQL application
- The workload is mostly transactional CRUD with moderate reporting
- Clean indexing on user, role, club, licence, and event tables will keep the system responsive
- Server-side rendering keeps hosting simple and cost-effective

## 2. Core Domain Design

### Identity model

- Every person has exactly one `users` record
- A user may hold many roles through `user_roles`
- Parent-child links are explicit through `parent_child_links`
- Club membership is separate from roles through `club_memberships`
- Club admin powers are scoped through `club_staff_assignments`

### Profile model

- Shared personal data lives in `users` and `user_profiles`
- Role-specific data lives in dedicated tables such as `fencer_profiles`, `coach_certifications`, and `referee_certifications`
- Rankings are stored in `ranking_snapshots` so future rankings integration is possible without redesign

### Membership and licence model

- Licence types are configurable through `licence_types`
- Each application or renewal becomes a `licence_records` row
- Status changes are tracked in `licence_status_history`
- Payment linkage is handled through `payments` and `payment_items`

### Competition and event model

- Events and competitions use the same `events` table
- Entries are stored in `event_entries`
- A parent can enter a child because `entered_by_user_id` is captured on the registration
- Capacity, registration windows, and payment-required entries are handled at event level

## 3. Main Modules / Pages

- Public landing page
- Login / logout / password reset
- My profile
- Parent dashboard
- Child management
- Licence applications and renewal history
- Events and competitions listing
- Event detail and entry page
- My competition history
- Club portal
- Admin users index
- Admin user detail
- Admin clubs management
- Admin licences management
- Admin events management
- Admin payments and refunds
- Admin reports dashboard
- Audit log viewer

## 4. Recommended Roles And Permissions

### Global roles

- `admin`
- `fencer`
- `referee`
- `coach`
- `supporter`
- `parent`
- `club_admin`

### Permission groups

- Authentication and own-profile access
- Parent-child management
- Licence application and renewal
- Event browsing and entry
- Club reporting access
- Admin record management
- Payment and refund management
- Reporting and exports
- Audit log access

See `database/seed_reference_data.sql` for the starter permission model.

## 5. Suggested Payment Workflow

### Licence payment flow

1. User or parent selects a licence type.
2. System creates a pending `licence_records` row.
3. System creates a pending payment session with `payments` and `payment_items`.
4. Payment gateway callback marks payment as paid or failed.
5. Paid licence is moved to `active` or `awaiting_review`, depending on the business rule.
6. Status change is written to `licence_status_history`.
7. Audit log records the transition.

### Event payment flow

1. User or parent enters an event.
2. If the event is free, entry goes straight to `confirmed`.
3. If the event is paid, entry starts as `pending_payment`.
4. Successful payment updates the related payment item and moves the entry to `confirmed`.
5. Cancellation and refund actions update `event_entries`, `refunds`, and `audit_logs`.

### Gateway recommendation

- Stripe is the strongest default choice for hosted checkout, webhook support, refunds, and audit-friendly payment references
- If an Irish-specific provider is preferred later, keep the payment layer abstracted behind a payment service interface

## 6. Suggested Admin Reporting Structure

### Dashboard sections

- Membership overview
- Licence health
- Club breakdown
- Competition activity
- Revenue and refunds

### Core reports

- Active fencers by age group
- Active fencers by weapon
- Active fencers by sex
- Membership totals by club
- Active vs expired licences
- Competition participation statistics

The starter SQL views live in `database/report_views.sql`.

## 7. Important Features To Add Soon

- Password reset and email verification
- Document uploads for certificates and proof of eligibility
- Consent management for minors and GDPR-related records
- Safeguarding / vetting checks for coaches, referees, and club officials
- Notification templates for renewals, expiring certifications, and competition reminders
- CSV export and import tools
- Soft-deletion or archival strategy for compliance-sensitive records
- Fine-grained admin impersonation safeguards if support access is later needed

## 8. Phased MVP Plan

### Phase 1: Core identity and access

- Database schema
- Authentication
- User profile
- Roles and permissions
- Parent-child linking
- Club membership model

### Phase 2: Licences and memberships

- Licence type configuration
- New and renewal workflows
- Online payments
- Licence history and status screens
- Admin approval tools

### Phase 3: Competitions and events

- Event creation and publishing
- Entry workflow
- Paid and free entries
- Capacity limits and closing dates
- Parent entry on behalf of child
- Event participation history

### Phase 4: Admin reporting and operations

- User and licence search screens
- Payment/refund management
- Reporting dashboards
- CSV exports
- Audit log explorer

### Phase 5: Federation-specific enhancements

- Rankings integration
- Certification workflows
- Club renewal processes
- Official assignments
- API integrations and single sign-on if needed later

## 9. Security Notes

- Use PHP `password_hash()` and `password_verify()`
- Enforce HTTPS in production
- Add CSRF protection to all state-changing forms
- Scope all access through permission checks, not just hidden UI
- Log admin writes, refunds, approvals, and relationship changes
- Validate uploaded files and keep them outside the web root
- Add rate limiting for login and password reset endpoints