┌─────────────────────────────────────────────────────────────────┐
│                         FRONTEND                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │   Hotwire    │  │   Stimulus   │  │   Tailwind   │          │
│  │   (Turbo)    │  │      JS      │  │      CSS     │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                      RAILS CONTROLLERS                           │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐          │
│  │  Clubs   │ │  Courts  │ │Tournaments│ │ Matches  │          │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘          │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                     AUTHORIZATION (Pundit)                       │
│  ┌────────────────────────────────────────────────────┐         │
│  │          ACL (Access Control Lists)                │         │
│  │   - Per-Tournament permissions                     │         │
│  │   - Role-based access control                      │         │
│  └────────────────────────────────────────────────────┘         │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                      BUSINESS LOGIC                              │
│  ┌──────────────────────────────────────────────────┐           │
│  │  • Tournament bracket generation                 │           │
│  │  • Seed placement & BYE calculation              │           │
│  │  • Match scheduling                              │           │
│  │  • Score validation workflow                     │           │
│  │  • Point calculation (FFT rules)                 │           │
│  └──────────────────────────────────────────────────┘           │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                      MODELS (ActiveRecord)                       │
│  ┌─────┐  ┌──────┐  ┌──────┐  ┌──────────┐  ┌───────┐         │
│  │User │  │ Club │  │Court │  │Tournament│  │ Match │         │
│  └─────┘  └──────┘  └──────┘  └──────────┘  └───────┘         │
│     │         │         │           │             │             │
│  ┌──────────────┐  ┌──────┐  ┌────────────────────┐           │
│  │ Tournament   │  │ Team │  │  ScoreProposal     │           │
│  │  Permission  │  └──────┘  └────────────────────┘           │
│  └──────────────┘                                               │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                      DATABASE (PostgreSQL)                       │
│                                                                  │
│  Tables: users, clubs, courts, tournaments,                     │
│          tournament_permissions, teams, matches,                │
│          match_teams, score_proposals                           │
└─────────────────────────────────────────────────────────────────┘

┌─────────────┐
│    User     │
│─────────────│
│ • email     │
│ • role      │◄────────────┐
│ • niveau_jap│             │
│ • classement│             │
└─────────────┘             │
       │                    │
       │ manages            │ juge_arbitre_principal
       ▼                    │
┌─────────────┐             │
│    Club     │             │
│─────────────│             │
│ • nom       │             │
│ • adresse   │             │
└─────────────┘             │
       │                    │
       │ has_many           │
       ▼                    │
┌─────────────┐             │
│    Court    │             │
│─────────────│             │
│ • nom       │             │
│ • homologue │             │
│ • hauteur   │             │
└─────────────┘             │
       │                    │
       │ used_by            │
       ▼                    │
┌─────────────┐             │
│    Match    │             │
│─────────────│             │
│ • round     │             │
│ • heure     │             │
└─────────────┘             │
       │                    │
       │ belongs_to         │
       ▼                    │
┌──────────────┐            │
│  Tournament  │◄───────────┘
│──────────────│
│ • type       │
│ • format     │
│ • dates      │
└──────────────┘
       │
       │ has_many
       ▼
┌──────────────────┐
│Tournament        │
│Permission (ACL)  │
│──────────────────│
│ • user_id        │
│ • permission_type│
│ • granted_by     │
└──────────────────┘
       │
       │ grants_access_to
       ▼
┌─────────────┐
│    User     │ (autorized users)
└─────────────┘

┌──────────────┐          ┌─────────────┐
│  Tournament  │──────────│    Team     │
└──────────────┘ has_many └─────────────┘
                              │      │
                   joueur1_id │      │ joueur2_id
                              ▼      ▼
                          ┌─────────────┐
                          │    User     │
                          └─────────────┘

┌─────────────┐          ┌──────────────┐
│    Match    │──────────│  MatchTeam   │
└─────────────┘ has_many └──────────────┘
                              │
                              │ belongs_to
                              ▼
                          ┌─────────────┐
                          │    Team     │
                          └─────────────┘

┌─────────────┐          ┌──────────────────┐
│    Match    │──────────│ ScoreProposal    │
└─────────────┘ has_many └──────────────────┘
                          │ • scores         │
                          │ • validated?     │
                          └──────────────────┘

┌──────────────────────────────────────────────────────────┐
│                    USER ROLES                            │
├──────────────────────────────────────────────────────────┤
│  ┌──────┐   ┌──────────────┐   ┌─────┐   ┌────────┐   │
│  │Admin │   │Juge-Arbitre  │   │Gest.│   │ Joueur │   │
│  │      │   │  (JAP)       │   │Club │   │        │   │
│  └──────┘   └──────────────┘   └─────┘   └────────┘   │
│     │              │               │           │        │
│     │              │               │           │        │
│     ▼              ▼               ▼           ▼        │
│  [ALL]      [Create Tourn.]  [Manage Club] [Register] │
└──────────────────────────────────────────────────────────┘
                     │
                     ▼
┌──────────────────────────────────────────────────────────┐
│              TOURNAMENT CREATION                         │
│  JAP creates tournament → Gets ADMIN permission          │
└──────────────────────────────────────────────────────────┘
                     │
                     ▼
┌──────────────────────────────────────────────────────────┐
│            ACL PERMISSION GRANTS                         │
│                                                          │
│  JAP (admin) can grant:                                 │
│    • Other JAP      → READ or WRITE                     │
│    • Club Manager   → READ or WRITE                     │
│    • Players        → READ (auto on registration)       │
└──────────────────────────────────────────────────────────┘
                     │
                     ▼
┌──────────────────────────────────────────────────────────┐
│           PERMISSION CHECKS (Pundit)                     │
│                                                          │
│  Before action:                                          │
│    • Check user role                                     │
│    • Check tournament permission                         │
│    • Allow or deny action                               │
└──────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────┐
│         DÉCLARATION AVEC VALIDATION                       │
├──────────────────────────────────────────────────────────┤
│                                                           │
│  JAP propose    ────►  Gestionnaire valide  ────►  Créé  │
│                                                           │
│  Gestionnaire  ────►  JAP valide            ────►  Créé  │
│   déclare                                                 │
│                                                           │
│  Admin         ────►  (pas de validation)   ────►  Créé  │
└──────────────────────────────────────────────────────────┘

┌─────────┐
│   JAP   │
└────┬────┘
     │
     │ 1. Propose tournament (status: declaration)
     ▼
┌────────────────┐
│  Tournament    │
│  (brouillon)   │
└────┬───────────┘
     │
     │ 2. Configure
     ▼
┌────────────────────────────────┐
│ • Type (P25-P2000)             │
│ • Dates                        │
│ • Format match                 │
│ • Club & courts                │
│ • Min/max teams                │
└────┬───────────────────────────┘
     │
     │ 3. Grant permissions
     ▼
┌────────────────────────────────┐
│ TournamentPermission           │
│ • Other JAP (write)            │
│ • Club manager (read)          │
└────┬───────────────────────────┘
     │
     │ 4. Open registrations
     ▼
┌────────────────┐
│  Tournament    │
│  (ouvert)      │
└────┬───────────┘
     │
     │ 5. Teams register
     ▼
┌────────────────────────────────┐
│  Team validation:              │
│  • Check classement constraint │
│  • Check poids paire           │
│  • Check licence FFT           │
└────┬───────────────────────────┘
     │
     │ 6. Close registrations
     ▼
┌────────────────────────────────┐
│  Generate bracket:             │
│  • Sort by classement          │
│  • Place seeds                 │
│  • Calculate BYE               │
│  • Create matches              │
└────┬───────────────────────────┘
     │
     │ 7. Generate schedule
     ▼
┌────────────────────────────────┐
│  Match planning:               │
│  • Assign courts               │
│  • Assign times                │
│  • Respect rest periods        │
│  • Notify players              │
└────┬───────────────────────────┘
     │
     │ 8. Tournament starts
     ▼
┌────────────────┐
│  Tournament    │
│  (en_cours)    │
└────────────────┘

┌──────────────┐
│ Match starts │
└──────┬───────┘
       │
       ▼
┌──────────────────────────────────┐
│  Team 1 plays vs Team 2          │
└──────┬───────────────────────────┘
       │
       │ Match ends
       ▼
┌──────────────────────────────────┐
│ Team 1 player proposes score     │
│ (via mobile/web interface)       │
└──────┬───────────────────────────┘
       │
       │ Creates ScoreProposal
       ▼
┌──────────────────────────────────┐
│ System notifies Team 2           │
│ "Please validate score"          │
└──────┬───────────────────────────┘
       │
       ├─────────── YES ────────────┐
       │                            │
       │                            ▼
       │                    ┌────────────────┐
       │                    │ Team 2 accepts │
       │                    └────────┬───────┘
       │                             │
       │                             │
       │                             ▼
       │                    ┌──────────────────┐
       │                    │ Notify JAP       │
       │                    │ for validation   │
       │                    └────────┬─────────┘
       │                             │
       │                             ▼
       │                    ┌──────────────────┐
       │                    │ JAP validates    │
       │                    └────────┬─────────┘
       │                             │
       │                             ▼
       │                    ┌──────────────────┐
       │                    │ Score confirmed  │
       │                    │ • Update match   │
       │                    │ • Progress winner│
       │                    │ • Calculate pts  │
       │                    └──────────────────┘
       │
       └─────────── NO ─────────────┐
                                    │
                                    ▼
                            ┌────────────────┐
                            │ Team 2 contests│
                            └────────┬───────┘
                                     │
                                     ▼
                            ┌──────────────────┐
                            │ Alert JAP        │
                            │ (dispute)        │
                            └────────┬─────────┘
                                     │
                                     ▼
                            ┌──────────────────┐
                            │ JAP investigates │
                            │ & decides        │
                            └────────┬─────────┘
                                     │
                                     ▼
                            ┌──────────────────┐
                            │ JAP enters       │
                            │ correct score    │
                            └────────┬─────────┘
                                     │
                                     ▼
                            ┌──────────────────┐
                            │ Score confirmed  │
                            │ (with audit log) │
                            └──────────────────┘

┌─────────────┐
│ DÉCLARATION │ ← JAP/Gestionnaire propose (nouveau)
└──────┬──────┘
       │
       │ Validation
       ▼
┌─────────────┐
│  BROUILLON  │ ← Après validation ou création directe (admin)
└──────┬──────┘
       │
       │ Configure
       ▼
┌─────────────────────┐
│ OUVERT_INSCRIPTIONS │
└──────┬──────────────┘
       │
       │ Teams register
       ▼
┌─────────────────────┐
│ CLOTURE_INSCRIPTIONS│
└──────┬──────────────┘
       │
       │ Generate bracket & schedule
       ▼
┌─────────────┐
│  EN_COURS   │
└──────┬──────┘
       │
       │ Play matches
       ▼
┌─────────────┐
│   TERMINE   │
└──────┬──────┘
       │
       │ Calculate final points
       ▼
┌─────────────┐
│  ARCHIVED   │
└─────────────┘

     ╔═══════════╗
     ║  ANNULE   ║ ← Can happen anytime
     ╚═══════════╝

┌────────────────────────────────────┐
│  Dashboard JAP                     │
├────────────────────────────────────┤
│  • Mes tournois                    │
│  • Créer un nouveau tournoi        │
│  • Tournois en cours               │
│  • Matches à valider               │
│  • Statistiques                    │
└────────────────────────────────────┘

┌────────────────────────────────────┐
│  Dashboard Gestionnaire            │
├────────────────────────────────────┤
│  • Mon club                        │
│  • Mes terrains                    │
│  • Tournois hébergés               │
│  • Planning des terrains           │
│  • Statistiques d'utilisation      │
└────────────────────────────────────┘

┌────────────────────────────────────┐
│  Dashboard Joueur                  │
├────────────────────────────────────┤
│  • Mes inscriptions                │
│  • Mes prochains matchs            │
│  • Saisir un score                 │
│  • Mon classement                  │
│  • Historique de performances      │
└────────────────────────────────────┘

Ruby 3.3.6
├── Rails 8.0
├── PostgreSQL 16
├── Devise (auth)
├── Pundit (authorization)
├── Sidekiq (background jobs)
└── ActiveStorage (file uploads)

Hotwire
├── Turbo (SPA-like experience)
├── Stimulus (JS sprinkles)
└── Tailwind CSS (styling)

RSpec
├── FactoryBot (fixtures)
├── Faker (test data)
├── Capybara (system tests)
└── Shoulda Matchers (validation tests)

├── Rubocop (linting)
├── Bullet (N+1 query detection)
├── Brakeman (security scan)
└── SimpleCov (code coverage)