4.0 KiB
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