First Commit

docs/00_overview.md

@@ -0,0 +1,54 @@
+# Cloudsy 🎧
+
+## Slogan
+Your music, in the cloud of your mind
+
+---
+
+## 📌 Descrição
+
+Cloudsy é uma aplicação de música moderna desenvolvida em Flutter que combina:
+
+- Streaming local (upload de músicas)
+- Inteligência artificial (Clou)
+- Funcionalidades sociais (DMs)
+- Personalização avançada (temas + cores)
+- Interface moderna e responsiva
+
+---
+
+## 🎯 Objetivo
+
+Criar uma aplicação musical inteligente que:
+- se adapta ao utilizador
+- aprende com os seus gostos
+- oferece uma experiência fluida e visualmente sofisticada
+
+---
+
+## 🤖 Clou (IA)
+
+Clou é o assistente inteligente da app:
+
+- Gera tags automaticamente (género + mood)
+- Recomenda músicas
+- Interage com o utilizador via chat
+
+---
+
+## 🌍 Internacionalização
+
+Idiomas suportados:
+- Português 🇵🇹 (default)
+- English 🇬🇧
+
+---
+
+## 🎨 Design
+
+- Interface moderna (Material 3)
+- Botões arredondados (border radius alto)
+- Cor principal: Azul
+- Tema automático:
+  - segue o sistema (dark/light)
+

docs/01_architecture.md

@@ -0,0 +1,289 @@
+# 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
+

docs/02_database.md

@@ -0,0 +1,70 @@
+# Base de Dados — Firestore
+
+## 🔐 Users
+
+users/
+  userId/
+    email: string
+    username: string
+    themeMode: "system" | "light" | "dark"
+    primaryColor: string (hex)
+    language: "pt" | "en"
+    favoriteGenres: [string]
+    createdAt: timestamp
+
+---
+
+## 🎵 Songs
+
+songs/
+  songId/
+    title: string
+    artist: string
+    url: string
+    coverUrl: string
+    userId: string
+    genre: string
+    mood: string
+    duration: number
+    createdAt: timestamp
+
+---
+
+## 📂 Playlists
+
+playlists/
+  playlistId/
+    name: string
+    userId: string
+    songs: [songId]
+    createdAt: timestamp
+
+---
+
+## 💬 Chats
+
+chats/
+  chatId/
+    participants: [userId]
+    lastMessage: string
+    updatedAt: timestamp
+
+---
+
+## 📨 Messages
+
+messages/
+  messageId/
+    chatId: string
+    senderId: string
+    text: string (optional)
+    songId: string (optional)
+    timestamp: timestamp
+
+---
+
+## ⚡ Regras importantes
+
+- Nunca duplicar dados desnecessários
+- Usar IDs para relações
+- Otimizar leituras (Firestore billing)

docs/03_features.md

@@ -0,0 +1,59 @@
+# Funcionalidades
+
+---
+
+## 🎵 Música
+
+- Upload de ficheiros áudio
+- Player completo:
+  - play/pause
+  - seek
+  - progresso
+- Capa dinâmica
+
+---
+
+## 📂 Playlists
+
+- Criar playlists
+- Adicionar/remover músicas
+- Ordenação
+
+---
+
+## 🤖 IA (Clou)
+
+- Tagging automático:
+  - género
+  - mood
+- Recomendações inteligentes
+- Chat conversacional
+
+---
+
+## 💬 DMs
+
+- Mensagens de texto
+- Envio de músicas
+- Visualização de músicas no chat
+
+---
+
+## 🎨 Personalização
+
+- Tema automático (system)
+- Override manual
+- Cor principal customizável
+
+---
+
+## 🌍 Idiomas
+
+- PT / EN
+- Mudança dinâmica
+
+---
+
+## 🎼 Lyrics
+
+- Integração com Genius API

docs/04_ai.md

@@ -0,0 +1,60 @@
+# Inteligência Artificial — Clou 🤖
+
+## 🎯 Objetivo
+
+Fornecer uma experiência musical personalizada baseada em IA.
+
+---
+
+## 🧠 Funcionalidades
+
+### 1. Tagging automático
+
+Input:
+- título
+- artista
+
+Output:
+- genre
+- mood
+
+---
+
+### 2. Recomendações
+
+Baseado em:
+- histórico
+- playlists
+- moods
+
+---
+
+### 3. Chat IA
+
+Capaz de:
+- responder perguntas
+- sugerir música
+- analisar gostos
+
+---
+
+## 💬 Personalidade
+
+Clou deve ser:
+- amigável
+- conciso
+- focado em música
+
+---
+
+## ⚙️ Implementação
+
+- API externa (ex: :contentReference[oaicite:2]{index=2})
+- fallback com regras simples
+
+---
+
+## ⚠️ Limitações
+
+- Não inventar dados falsos
+- Evitar respostas longas

docs/05_tasks.md

@@ -0,0 +1,61 @@
+# Plano de Desenvolvimento — Cloudsy
+
+## ⏳ Duração: 8 semanas
+
+---
+
+## 🟦 Semana 1 — Fundação
+- Setup Flutter
+- Integração com Firebase
+- Estrutura do projeto
+- AuthService + Login/Register
+
+---
+
+## 🟦 Semana 2 — Música Core
+- Upload de músicas (Storage)
+- Guardar metadata (Firestore)
+- Player básico
+
+---
+
+## 🟦 Semana 3 — Playlists
+- CRUD playlists
+- UI de playlists
+- Navegação
+
+---
+
+## 🟦 Semana 4 — IA Tagging
+- Integração IA
+- Geração automática:
+  - género
+  - mood
+
+---
+
+## 🟦 Semana 5 — Chat Clou
+- UI de chat
+- Integração com API IA
+- Recomendações
+
+---
+
+## 🟦 Semana 6 — UI + Temas
+- Tema automático (system)
+- Custom colors
+- Material 3 polish
+
+---
+
+## 🟦 Semana 7 — DMs + Lyrics
+- Sistema de mensagens
+- Envio de músicas
+- Integração com Genius
+
+---
+
+## 🟦 Semana 8 — Finalização
+- Bug fixes
+- UX improvements
+- Preparação para apresentação

docs/06_prompts_gemini.md

@@ -0,0 +1,57 @@
+# Prompts para Gemini (Estruturados)
+
+## Regra base
+Sempre:
+- Ler /docs
+- Seguir arquitetura
+- Não inventar features
+
+---
+
+## Prompt 1 — Setup
+Setup Flutter + Firebase + Auth + Localization
+
+---
+
+## Prompt 2 — Music Upload
+Create MusicService:
+- upload audio to Firebase Storage
+- store metadata in Firestore
+
+---
+
+## Prompt 3 — Player
+Create audio player using just_audio:
+- play
+- pause
+- seek
+
+---
+
+## Prompt 4 — Playlists
+Implement CRUD playlists with Firestore
+
+---
+
+## Prompt 5 — AI Tagging
+Send song metadata to AI and store genre/mood
+
+---
+
+## Prompt 6 — Chat IA
+Create chat UI + AI integration
+
+---
+
+## Prompt 7 — Messaging
+Create DMs system:
+- text messages
+- send songId
+
+---
+
+## Prompt 8 — Themes
+Implement:
+- system theme
+- custom colors
+

docs/07_ui_ux.md

@@ -0,0 +1,273 @@
+# UI/UX Design System — Cloudsy ☁️🎧
+
+---
+
+# 🧠 Filosofia de Design
+
+Cloudsy inspira-se em:
+- leveza (cloud)
+- fluidez (música)
+- simplicidade moderna
+
+A interface deve transmitir:
+- suavidade
+- conforto visual
+- elegância tecnológica
+
+---
+
+# ☁️ Identidade Visual (Cloud Design)
+
+## Conceito
+A UI deve refletir uma “nuvem digital”:
+
+- Formas arredondadas
+- Elementos suaves
+- Espaçamento confortável
+- Sem arestas agressivas
+
+---
+
+## 🔵 Cor Principal
+
+Primary Color:
+- Azul (Cloud Blue)
+- Exemplo: #3B82F6
+
+Uso:
+- Botões principais
+- Elementos interativos
+- Destaques
+
+---
+
+## 🌗 Sistema de Tema
+
+### Default
+- ThemeMode.system
+
+### Comportamento
+- Segue automaticamente o tema do dispositivo
+- Atualização em tempo real
+
+---
+
+## 🎨 Paleta
+
+### Light Mode
+- Background: branco suave (#F9FAFB)
+- Cards: branco
+- Texto: preto suave
+
+### Dark Mode
+- Background: preto profundo (#0F172A)
+- Cards: cinza escuro (#1E293B)
+- Texto: branco suave
+
+---
+
+# 🔘 Componentes Base
+
+---
+
+## ☁️ Botões (Cloud Buttons)
+
+### Estilo
+- BorderRadius: MUITO alto (ex: 20–30)
+- Forma: pill / oval
+- Aparência: “nuvem”
+
+### Tipos
+
+#### Primary Button
+- Fundo azul
+- Texto branco
+- Elevation leve
+
+#### Secondary Button
+- Outline azul
+- Fundo transparente
+
+#### Icon Button
+- Circular
+- Fundo suave
+
+---
+
+## 🎵 Music Card
+
+### Layout
+- Rounded corners
+- Capa à esquerda
+- Info à direita
+
+### Conteúdo
+- Título
+- Artista
+- Mood tag (IA)
+
+---
+
+## 💬 Chat Bubble
+
+### Estilo
+- Bordas arredondadas
+- Cores diferentes:
+  - User: azul
+  - Clou: cinza
+
+---
+
+## 🎵 Song Message Card
+
+- Pequeno player embutido
+- Capa + título
+- Botão play
+
+---
+
+# 📱 Layout Geral
+
+## Estrutura
+
+- Safe area
+- Padding consistente (16px–24px)
+- Espaçamento vertical suave
+
+---
+
+## 📊 Hierarquia Visual
+
+1. Música (principal)
+2. Ações (botões)
+3. Informação secundária
+
+---
+
+# 🔄 Navegação
+
+## Bottom Navigation
+
+Tabs:
+- Home
+- Playlists
+- Chat
+- Settings
+
+### Estilo:
+- Rounded container
+- Floating effect
+- Azul ativo
+
+---
+
+# ✨ Animações
+
+## Princípios
+- Suaves
+- Rápidas
+- Naturais
+
+## Exemplos
+- Fade transitions
+- Scale em botões
+- Progress animations
+
+---
+
+# ⚡ Estados da UI
+
+## Loading
+- Skeleton UI
+- Shimmer effect (opcional)
+
+---
+
+## Empty
+Mensagens amigáveis:
+- “Ainda não tens músicas ☁️”
+- “Cria a tua primeira playlist”
+
+---
+
+## Error
+- Mensagens claras
+- Botão retry
+
+---
+
+# 🧠 UX Guidelines
+
+## Simplicidade
+- Evitar clutter
+- Interface limpa
+
+## Consistência
+- Mesmos padrões em toda a app
+
+## Feedback
+- Sempre mostrar resposta a ações
+
+---
+
+# 🌍 Localização
+
+- Todo texto via keys
+- Layout adaptável a idiomas
+
+---
+
+# ⚙️ Settings UX
+
+## Secções
+
+### Perfil
+- Nome
+- Email
+
+---
+
+### Tema
+- System (default)
+- Light
+- Dark
+
+---
+
+### Cor
+- Azul default
+- Custom
+
+---
+
+### Idioma
+- Português
+- English
+
+---
+
+### Conta
+- Logout
+
+---
+
+# ☁️ Assinatura Visual Cloudsy
+
+## Elementos únicos
+
+- Bordas muito arredondadas
+- Layout “leve”
+- Espaçamento respirável
+- Azul suave como base
+
+---
+
+# 🚀 Conclusão
+
+A UI de Cloudsy deve parecer:
+- moderna
+- suave
+- fluida
+- inteligente
+
+Como se a música estivesse “na nuvem”.

docs/08_delivery.md

@@ -0,0 +1,28 @@
+# Entrega
+
+## 🎯 Demonstração
+
+1. Login
+2. Upload música
+3. IA tagging
+4. Player
+5. Playlist
+6. Chat Clou
+7. Enviar música por DM
+
+---
+
+## 💡 O que impressiona
+
+- UI moderna
+- IA funcional
+- Fluidez
+- Organização do código
+
+---
+
+## 🧠 Dica
+
+Mostrar fluxo completo:
+upload → IA → playlist → chat → DM
+

docs/09_progress_report.md

@@ -0,0 +1,17 @@
+# Progress Report
+
+## Estrutura
+
+Data:
+Tarefa:
+Descrição:
+Ficheiros:
+Estado:
+Notas:
+
+---
+
+## Regras
+- Atualizar após cada tarefa
+- Ser claro e objetivo
+

docs/10_error_log.md

@@ -0,0 +1,15 @@
+# Error Log
+
+## Estrutura
+
+Data:
+Erro:
+Causa:
+Solução:
+Prevenção:
+
+---
+
+## Objetivo
+Evitar repetir erros e melhorar debugging
+

docs/11_models..md

@@ -0,0 +1,47 @@
+# Models
+
+## User
+- id
+- email
+- username
+- themeMode
+- primaryColor
+- language
+
+---
+
+## Song
+- id
+- title
+- artist
+- url
+- coverUrl
+- genre
+- mood
+- duration
+
+---
+
+## Playlist
+- id
+- name
+- userId
+- songs[]
+
+---
+
+## Message
+- id
+- chatId
+- senderId
+- text
+- songId
+- timestamp
+
+---
+
+## Chat
+- id
+- participants[]
+- lastMessage
+

docs/11_models.md

@@ -0,0 +1,47 @@
+# Models
+
+## User
+- id
+- email
+- username
+- themeMode
+- primaryColor
+- language
+
+---
+
+## Song
+- id
+- title
+- artist
+- url
+- coverUrl
+- genre
+- mood
+- duration
+
+---
+
+## Playlist
+- id
+- name
+- userId
+- songs[]
+
+---
+
+## Message
+- id
+- chatId
+- senderId
+- text
+- songId
+- timestamp
+
+---
+
+## Chat
+- id
+- participants[]
+- lastMessage
+

docs/12_services.md

@@ -0,0 +1,46 @@
+# Services
+
+## AuthService
+- login
+- register
+- logout
+
+---
+
+## MusicService
+- uploadSong
+- getSongs
+- deleteSong
+
+---
+
+## PlaylistService
+- createPlaylist
+- addSong
+- removeSong
+
+---
+
+## AIService
+- generateTags
+- getRecommendations
+- chatWithClou
+
+---
+
+## MessageService
+- sendMessage
+- getMessages
+
+---
+
+## ThemeService
+- setThemeMode
+- setPrimaryColor
+
+---
+
+## LocalizationService
+- setLanguage
+- getLanguage
+- translate

docs/13_testing.md

@@ -0,0 +1,177 @@
+# Testing — Cloudsy 🧪
+
+## 🎯 Objetivo
+
+Garantir que todas as funcionalidades da aplicação:
+- funcionam corretamente
+- são estáveis
+- oferecem boa experiência ao utilizador
+
+---
+
+# 🧠 Tipos de Testes
+
+## 1. Testes Funcionais
+Verificar se cada funcionalidade funciona como esperado.
+
+## 2. Testes de UI/UX
+Garantir que:
+- interface é intuitiva
+- estados visuais funcionam (loading, error, empty)
+
+## 3. Testes de Integração
+Verificar comunicação entre:
+- Flutter ↔ Firebase
+- App ↔ APIs (IA, lyrics)
+
+---
+
+# 🔐 AUTHENTICATION
+
+## Testes
+
+- [ ] Registo com email válido
+- [ ] Registo com password fraca → erro
+- [ ] Login com credenciais corretas
+- [ ] Login com credenciais erradas → erro
+- [ ] Logout funciona
+
+---
+
+# 🎵 MÚSICA
+
+## Upload
+
+- [ ] Upload de ficheiro válido
+- [ ] Upload falha → erro visível
+- [ ] Música aparece na lista após upload
+
+## Player
+
+- [ ] Play funciona
+- [ ] Pause funciona
+- [ ] Barra de progresso atualiza
+- [ ] Música troca corretamente
+
+---
+
+# 📂 PLAYLISTS
+
+- [ ] Criar playlist
+- [ ] Adicionar música
+- [ ] Remover música
+- [ ] Lista atualiza corretamente
+
+---
+
+# 🤖 IA (Clou)
+
+## Tagging
+
+- [ ] Música recebe género
+- [ ] Música recebe mood
+
+## Chat
+
+- [ ] Responde a perguntas
+- [ ] Sugere músicas
+- [ ] Não crasha com inputs inválidos
+
+---
+
+# 💬 DMs
+
+- [ ] Enviar mensagem de texto
+- [ ] Receber mensagem
+- [ ] Enviar música
+- [ ] Música aparece corretamente no chat
+
+---
+
+# 🌍 LOCALIZAÇÃO
+
+- [ ] App inicia em português
+- [ ] Mudança para inglês funciona
+- [ ] UI atualiza sem restart
+- [ ] Nenhum texto hardcoded
+
+---
+
+# 🎨 UI / UX
+
+## Tema
+
+- [ ] Segue tema do telemóvel (system)
+- [ ] Dark mode funciona
+- [ ] Light mode funciona
+
+## Botões
+
+- [ ] Todos são clicáveis
+- [ ] Feedback visual funciona
+- [ ] Bordas arredondadas consistentes
+
+---
+
+# ⚡ ESTADOS DA APP
+
+## Loading
+
+- [ ] Indicadores visuais presentes
+
+## Empty
+
+- [ ] Mensagens amigáveis
+
+## Error
+
+- [ ] Mensagens claras
+
+---
+
+# 🔥 TESTES CRÍTICOS (DEMO)
+
+Antes da apresentação:
+
+- [ ] Login
+- [ ] Upload música
+- [ ] Player
+- [ ] IA tagging
+- [ ] Chat IA
+- [ ] Enviar música por DM
+
+---
+
+# 🧠 DEBUGGING GUIDELINES
+
+## Problemas comuns
+
+### Firebase não responde
+- Verificar config
+- Verificar regras
+
+### Upload falha
+- Verificar Storage rules
+
+### IA não responde
+- Verificar API key
+
+---
+
+# 🚀 NOTA FINAL
+
+Testes não precisam ser automatizados para este projeto.
+
+Mas:
+- Devem ser executados manualmente
+- Devem ser demonstráveis
+
+---
+
+# 📌 CONCLUSÃO
+
+Um sistema testado:
+- reduz bugs
+- melhora UX
+- aumenta a qualidade percebida
+

docs/14_mvp.md

@@ -0,0 +1,13 @@
+# MVP
+
+## Obrigatório
+
+- Auth
+- Upload música
+- Player
+- Playlists
+- IA tagging
+- Chat IA
+- DMs
+- Lyrics
+- Temas

docs/15_wireframes.md

@@ -0,0 +1,362 @@
+# Wireframes — Cloudsy ☁️🎧
+
+---
+
+# 🧠 Objetivo
+
+Definir a estrutura visual, comportamento e fluxo de cada ecrã da aplicação.
+
+Este documento complementa:
+- 07_ui_ux.md (design system)
+- 01_architecture.md (estrutura)
+
+---
+
+# ☁️ Princípios Globais
+
+- UI arredondada (cloud style)
+- Botões com bordas suaves
+- Azul como cor principal
+- Tema automático (system)
+- Layout limpo e espaçado
+
+---
+
+# 🏠 1. HOME SCREEN
+
+## 🎯 Objetivo
+Mostrar músicas do utilizador + acesso rápido
+
+---
+
+## 🧱 Layout
+
+### Top Bar
+- Logo "Cloudsy"
+- Avatar do utilizador
+- Botão Settings (⚙️)
+
+---
+
+### Secção principal
+
+#### Lista de músicas
+Cada item:
+- Capa (rounded)
+- Título
+- Artista
+- Tag (mood IA)
+
+---
+
+### Floating Action Button (FAB)
+- Forma: circular arredondada
+- Cor: azul
+- Ícone: +
+- Ação: Upload música
+
+---
+
+## ⚡ Estados
+
+- Loading → skeleton list
+- Empty → "Ainda não tens músicas ☁️"
+- Error → mensagem + retry
+
+---
+
+# 🎧 2. PLAYER SCREEN
+
+## 🎯 Objetivo
+Reprodução completa de música
+
+---
+
+## 🧱 Layout
+
+### Top
+- Botão back
+- Nome da playlist
+
+---
+
+### Centro
+- Capa da música (grande, rounded)
+- Título
+- Artista
+
+---
+
+### Barra de progresso
+- Linha suave
+- Thumb arredondado
+
+---
+
+### Controlos
+- Play / Pause (botão principal azul)
+- Next / Previous
+
+---
+
+### Ações extra
+- Adicionar à playlist
+- Ver lyrics
+- Partilhar (DM)
+
+---
+
+## ✨ UX
+- Animação ao trocar música
+- Feedback visual nos controlos
+
+---
+
+# 📂 3. PLAYLISTS SCREEN
+
+## 🎯 Objetivo
+Gestão de playlists
+
+---
+
+## 🧱 Layout
+
+### Lista de playlists
+Cada item:
+- Nome
+- Nº de músicas
+- Estilo rounded card
+
+---
+
+### Botão criar
+- Botão azul arredondado
+
+---
+
+## 📂 Dentro da playlist
+
+- Lista de músicas
+- Botões:
+  - remover
+  - reorder
+
+---
+
+## ⚡ Estados
+
+- Empty → “Cria a tua primeira playlist ☁️”
+
+---
+
+# 💬 4. CHAT IA (Clou)
+
+## 🎯 Objetivo
+Interação com IA
+
+---
+
+## 🧱 Layout
+
+### Chat area
+- Bolhas arredondadas
+- User → azul
+- Clou → cinza
+
+---
+
+### Input
+- Campo rounded
+- Botão enviar
+
+---
+
+## 🤖 Funcionalidades
+
+- Perguntas livres
+- Recomendações
+- Análise de gosto
+
+---
+
+## ✨ UX
+
+- Scroll automático
+- Loading message (typing...)
+
+---
+
+# 👥 5. DMs (Mensagens)
+
+## 🎯 Objetivo
+Comunicação entre utilizadores
+
+---
+
+## 🧱 Lista de conversas
+
+- Nome
+- Última mensagem
+- Timestamp
+
+---
+
+## 🧱 Chat individual
+
+### Mensagens
+- Texto
+- Música (card)
+
+---
+
+### Input
+- Campo texto
+- Botão enviar
+- Botão enviar música 🎵
+
+---
+
+## 🎵 Mensagem de música
+
+- Capa
+- Nome
+- Botão play
+
+---
+
+# 📤 6. UPLOAD SCREEN
+
+## 🎯 Objetivo
+Adicionar música
+
+---
+
+## 🧱 Layout
+
+- Selecionar ficheiro
+- Input:
+  - título
+  - artista
+
+---
+
+### Botão upload
+- Azul
+- Rounded
+
+---
+
+## 🤖 Após upload
+
+- IA gera:
+  - género
+  - mood
+
+---
+
+# ⚙️ 7. SETTINGS SCREEN
+
+## 🎯 Objetivo
+Personalização da app
+
+---
+
+## 🧱 Layout
+
+### ☁️ Perfil
+- Nome
+- Email
+
+---
+
+### 🎨 Aparência
+
+#### Tema
+- System (default)
+- Light
+- Dark
+
+#### Cor
+- Azul (default)
+- Custom picker
+
+---
+
+### 🌍 Idioma
+- Português
+- English
+
+---
+
+### 🎵 Preferências
+- Géneros favoritos
+- Moods favoritos
+
+---
+
+### 🔐 Conta
+- Logout
+
+---
+
+# 📊 8. ESTADOS GLOBAIS
+
+## Loading
+- Skeleton
+- Shimmer
+
+---
+
+## Empty
+- Mensagens amigáveis
+- UI leve
+
+---
+
+## Error
+- Mensagem clara
+- Botão retry
+
+---
+
+## Offline
+- Aviso “Sem internet”
+
+---
+
+# 🔄 9. FLUXO PRINCIPAL
+
+## 🎯 Jornada do utilizador
+
+1. Login
+2. Upload música
+3. IA gera tags
+4. Música aparece na Home
+5. Criar playlist
+6. Ouvir música
+7. Chat com Clou
+8. Enviar música via DM
+
+---
+
+# ☁️ Assinatura Cloudsy
+
+- UI suave
+- Bordas arredondadas
+- Azul elegante
+- Layout respirável
+- Experiência fluida
+
+---
+
+# 🚀 Conclusão
+
+Wireframes definem:
+- Estrutura
+- UX
+- Comportamento
+
+E garantem que a app Cloudsy:
+- parece moderna
+- é intuitiva
+- tem identidade única