# Arquitetura — Cloudsy 🎧

---

# 🧠 Visão Geral

Cloudsy segue uma arquitetura modular baseada em separação de responsabilidades, garantindo:

- Escalabilidade
- Manutenibilidade
- Reutilização de código
- Clareza para desenvolvimento assistido por IA

---

# 🧱 Camadas da Aplicação

A aplicação é dividida em 4 camadas principais:

## 1. Presentation Layer (UI)
Responsável pela interface com o utilizador.

## 2. Controller Layer (State Management)
Responsável por gerir estado e lógica de interação.

## 3. Service Layer (Business Logic)
Responsável por lógica de negócio e comunicação externa.

## 4. Data Layer (Firebase / APIs)
Responsável por persistência e dados externos.

---

## 🔄 Fluxo de Dados

User Interaction
↓
UI (Screens / Widgets)
↓
Controllers
↓
Services
↓
Firebase / APIs

---

# 📁 Estrutura de Pastas

/lib
  /models
  /services
  /controllers
  /screens
  /widgets
  /theme
  /localization
  /utils

---

# 🧩 Descrição das Pastas

## /models
- Representação de dados
- Classes imutáveis
- Conversão JSON ↔ Dart

Exemplo:
- UserModel
- SongModel
- PlaylistModel
- MessageModel

---

## /services
- Comunicação com Firebase e APIs
- Lógica de negócio isolada

Regras:
- Nunca conter UI
- Nunca depender de widgets

Serviços principais:
- AuthService
- MusicService
- PlaylistService
- MessageService
- AIService
- ThemeService
- LocalizationService

---

## /controllers
- Gestão de estado
- Ligação entre UI e Services

Responsabilidades:
- Processar eventos da UI
- Atualizar estado
- Chamar services

---

## /screens
- Ecrãs principais da app
- Composição de widgets

Exemplos:
- LoginScreen
- HomeScreen
- PlayerScreen
- PlaylistScreen
- ChatScreen
- SettingsScreen

---

## /widgets
- Componentes reutilizáveis

Exemplos:
- MusicCard
- PlaylistCard
- ChatBubble
- RoundedButton

---

## /theme
- Configuração de temas
- Material 3
- Cores dinâmicas

---

## /localization
- Sistema de traduções
- PT / EN
- ARB ou JSON

---

## /utils
- Funções auxiliares
- Helpers

---

# 🧠 State Management

## Abordagem recomendada:
- Provider ou Riverpod

## Regras:
- Controllers gerem estado
- UI apenas observa estado
- Services não conhecem estado

---

# 🔌 Integração com Backend

## Backend principal:
- :contentReference[oaicite:0]{index=0}

### Serviços usados:
- Authentication
- Firestore
- Storage

---

## APIs externas:
- IA (Clou)
- :contentReference[oaicite:1]{index=1}

---

# 🔐 Gestão de Autenticação

- Baseada em Firebase Auth
- Estado global (logged in / out)
- Persistência automática de sessão

---

# 🎨 Sistema de Tema

## Default:
- ThemeMode.system

## Comportamento:
- Segue tema do dispositivo
- Pode ser override manual

## UI:
- Material 3
- Botões arredondados
- Azul como cor principal

---

# 🌍 Internacionalização (i18n)

## Idiomas:
- Português (default)
- English

## Implementação:
- LocalizationService
- Keys em vez de strings

Exemplo:
tr("home.title")

---

# 🤖 Integração de IA (Clou)

## Fluxo:

User → Controller → AIService → API → Response → UI

## Funções:
- Tagging automático
- Recomendações
- Chat

---

# 💬 Sistema de Mensagens

## Estrutura:
- Chats
- Messages

## Fluxo:

UI → MessageController → MessageService → Firestore

---

# ⚡ Performance e Otimização

- Lazy loading de dados
- Evitar rebuilds desnecessários
- Uso eficiente do Firestore
- Cache local (se necessário)

---

# 🚨 Regras Críticas

## ❌ NÃO FAZER
- Colocar lógica nos widgets
- Aceder diretamente ao Firebase na UI
- Hardcode de strings
- Misturar responsabilidades

## ✅ FAZER
- Usar services para lógica
- Usar controllers para estado
- Manter UI limpa
- Usar models consistentes

---

# 🔄 Escalabilidade

Arquitetura permite adicionar facilmente:

- Novas features
- Novos serviços
- Mais APIs
- Mais idiomas

---

# 🧠 Conclusão

Esta arquitetura garante que Cloudsy:
- é modular
- é escalável
- é fácil de manter
- funciona bem com desenvolvimento assistido por IA