melhores marcadores adicionados

docs/01_ARQUITETURA.md

@@ -0,0 +1,32 @@
+# 01 - Arquitetura de Software
+
+A arquitetura do VdcScore foi desenhada para resolver o problema de que as origens dos dados de campeonatos locais raramente oferecem uma API oficial, em tempo real e de uso público que possa ser consumida diretamente por dezenas de aplicações clientes sem problemas de estabilidade e segurança.
+
+## Diagrama de Fluxo (Data Flow)
+
+```mermaid
+graph TD
+    A[AFAVCD Web API / JSON] -->|1. Request/Scrape| B(Scraper Java)
+    B -->|2. Limpeza e Parsing (GSON/Jsoup)| C{Processamento}
+    C -->|3. Firebase Admin SDK| D[(Firebase Realtime Database)]
+    D -->|4. Sync Em Tempo Real| E(App Android VdcScore)
+    E -->|5. Exibe Dados| F[Utilizador Final]
+```
+
+## Como a Informação flui
+
+### 1. Fonte de Dados
+O sistema baseia-se nos dados provenientes do website oficial da associação (AFAVCD). Eles são obtidos essencialmente através de endpoints de "API" ocultos ou HTML bruto.
+
+### 2. O Scraper
+O **Scraper** é uma aplicação Java isolada. Esta aplicação tem de ser agendada (ex: cronjob num servidor) para correr periodicamente.
+- Recolhe dados como listas de jogos (`/jorneys`), resultados, estatísticas dos clubes e plantéis (jogadores).
+- Compara a nova informação, converte-a para a nossa estrutura de classes, e utiliza a biblioteca `firebase-admin` (via JSON account de serviço) para fazer update à **Firebase Realtime Database**.
+- Ao usar este "middle-man" garantimos que a App Android não tem de saber lidar com a complexidade e lentidão de extrair os dados na hora (nem sobrecarregar a fonte oficial com requests de todos os utilizadores).
+
+### 3. A Centralização (Firebase Realtime Database)
+A base de dados funciona como a única fonte da verdade (*Single Source of Truth*). Os nós de dados são altamente descritivos e simples. Sempre que o Scraper faz push de dados novos, os utilizadores conectados recebem as alterações graças ao modelo de websockets da Realtime DB.
+
+### 4. A App Cliente
+A App Android está ligada diretamente à Firebase com permissões de **Leitura Apenas** (Read-Only) para a maioria das coleções (exceto para gestão de utilizadores e favoritos, caso existam).
+O emparelhamento é feito via Data Models (ex: `Game.java`, `Club.java`) que correspondem *exatamente* ao formato JSON injetado pelo Scraper.