VdcScoreLive/docs/03-architecture.md

# 03 — Arquitetura do Sistema

## Diagrama de Arquitetura

```
┌─────────────────────────────────────────────────────────────┐
│                        FIREBASE                              │
│                                                              │
│   ┌─────────────┐    ┌──────────────┐    ┌───────────────┐ │
│   │  Firestore  │    │     Auth     │    │   Hosting     │ │
│   │  (Database) │    │  (Admin only)│    │  (Deploy)     │ │
│   └──────┬──────┘    └──────────────┘    └───────────────┘ │
│          │                                                    │
└──────────┼────────────────────────────────────────────────── ┘
           │ Real-time listeners
    ┌──────┴──────────────────────────┐
    │                                 │
    ▼                                 ▼
┌──────────────────┐       ┌──────────────────────┐
│  ADMIN DASHBOARD │       │   APLICAÇÃO CLIENTE  │
│  (Este projeto)  │       │   (Já desenvolvida)  │
│                  │       │                      │
│  - Escreve dados │       │  - Lê dados          │
│  - Autenticado   │       │  - Sem autenticação  │
│  - React SPA     │       │  - Apenas leitura    │
└──────────────────┘       └──────────────────────┘
       ▲ WRITE                      ▲ READ
       │                            │
       └────────── Firebase ────────┘
                  (fonte única de verdade)
```

---

## Fluxo de Dados

### Atualização de Resultado em Tempo Real

```
Admin clica "+1 Golo" no Live Score Editor
        │
        ▼
React Hook Form / estado local atualiza
        │
        ▼
Firebase transaction (atómica):
  - Atualiza game.score
  - Cria evento no subcollection game.events
  - Atualiza stats do jogador (se golo com autor)
  - Recalcula standings
        │
        ▼
Firebase Firestore (source of truth)
        │
        ├──▶ Admin Dashboard: listener onSnapshot atualiza UI
        │
        └──▶ App Cliente: listener onSnapshot recebe atualização
                         (< 2 segundos latência)
```

### Fluxo de Autenticação

```
Utilizador acede ao site
        │
        ▼
Firebase Auth verifica sessão
        │
        ├── Não autenticado ──▶ Redireciona para /login
        │
        └── Autenticado ──▶ Verifica role em Firestore
                                │
                                ├── role: "admin" ──▶ Acesso total
                                │
                                └── outros ──▶ Redireciona para /login
```

---

## Arquitetura de Componentes

```
App
├── AuthProvider (contexto de autenticação)
│   └── Router
│       ├── /login → LoginPage
│       └── ProtectedRoute (requer auth)
│           └── Layout
│               ├── Sidebar
│               ├── Header
│               └── Outlet (conteúdo da página)
│                   ├── /dashboard → DashboardPage
│                   ├── /games → GamesPage
│                   │   └── /games/:id/live → LiveGamePage ⭐
│                   ├── /clubs → ClubsPage
│                   │   └── /clubs/:id → ClubDetailPage
│                   ├── /players → PlayersPage
│                   ├── /standings → StandingsPage
│                   └── /scorers → ScorersPage
```

---

## Gestão de Estado

### Zustand Stores

```typescript
// authStore — autenticação
{
  user: FirebaseUser | null,
  isAdmin: boolean,
  loading: boolean
}

// leagueStore — dados da liga (cache local)
{
  clubs: Club[],
  players: Player[],
  currentSeason: string,
  activeGameId: string | null  // jogo a decorrer
}
```

### Firebase Hooks (React Query pattern)

Cada módulo tem um hook custom que:
1. Subscreve ao Firestore com `onSnapshot`
2. Guarda dados no estado local do hook
3. Expõe funções de mutação (create, update, delete)
4. Faz cleanup do listener no unmount

```typescript
// Exemplo
function useGames(jornadaId?: string) {
  const [games, setGames] = useState<Game[]>([])
  const [loading, setLoading] = useState(true)

  useEffect(() => {
    const q = jornadaId 
      ? query(gamesRef, where("jornadaId", "==", jornadaId))
      : gamesRef
    
    const unsubscribe = onSnapshot(q, (snapshot) => {
      setGames(snapshot.docs.map(d => ({ id: d.id, ...d.data() })))
      setLoading(false)
    })

    return () => unsubscribe()  // cleanup
  }, [jornadaId])

  return { games, loading }
}
```

---

## Firebase Security Rules

```javascript
rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    
    // Função helper: verifica se é admin
    function isAdmin() {
      return request.auth != null && 
             get(/databases/$(database)/documents/users/$(request.auth.uid)).data.role == "admin";
    }
    
    // Jogos: leitura pública, escrita apenas admin
    match /games/{gameId} {
      allow read: if true;
      allow write: if isAdmin();
      
      match /events/{eventId} {
        allow read: if true;
        allow write: if isAdmin();
      }
    }
    
    // Clubes: leitura pública, escrita apenas admin
    match /clubs/{clubId} {
      allow read: if true;
      allow write: if isAdmin();
    }
    
    // Jogadores: leitura pública, escrita apenas admin
    match /players/{playerId} {
      allow read: if true;
      allow write: if isAdmin();
    }
    
    // Standings: leitura pública, escrita apenas admin
    match /standings/{doc} {
      allow read: if true;
      allow write: if isAdmin();
    }
    
    // Utilizadores: apenas o próprio ou admin
    match /users/{userId} {
      allow read: if request.auth.uid == userId || isAdmin();
      allow write: if isAdmin();
    }
  }
}
```