290 lines
4.0 KiB
Markdown
290 lines
4.0 KiB
Markdown
# 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
|
|
|