dayMaker_lp/documentação/02_ARCHITECTURE.md

Arquitetura Técnica

Stack atual

Camada	Tecnologia
App móvel	Flutter / Dart
Backend/Auth/DB	Supabase
Base de dados	PostgreSQL via Supabase
Imagens	URLs guardados em item_images
IA de texto	Ollama API remota
Tema visual	Design tokens em lib/theme/app_theme.dart

---

Estrutura principal

lib/
├── constants/
│   └── item_categories.dart
├── login/
│   └── login_screen.dart
├── Screens/
│   ├── home_screen.dart
│   ├── item_screen.dart
│   ├── add_item_screen.dart
│   ├── week_screen.dart
│   ├── ai_chat_screen.dart
│   └── perfil_screen.dart
├── services/
│   └── ai_recommendation_service.dart
├── theme/
│   └── app_theme.dart
└── main.dart

---

Navegação

A HomeScreen contém uma navegação inferior com 5 áreas:

1. Início
2. Itens
3. Semana
4. IA
5. Perfil

O conteúdo é mantido num IndexedStack, permitindo alternar tabs sem recriar todos os ecrãs imediatamente.

---

Modelo de dados Supabase

users

Usada para dados adicionais do perfil.

Campo	Tipo esperado
id	UUID do utilizador
nome	texto

items

Representa itens do inventário.

Campo	Tipo esperado
id	inteiro/identificador
user_id	UUID
nome	texto
categoria	texto
tags	array/lista
nota / notes	texto opcional

item_images

Relaciona imagens a itens.

Campo	Tipo esperado
item_id	id do item
image_url	URL da imagem

plans

Representa um dia planeado.

Campo	Tipo esperado
id	inteiro/identificador
user_id	UUID
data	data em YYYY-MM-DD

plan_items

Relaciona itens com planos.

Campo	Tipo esperado
plan_id	id do plano
item_id	id do item

---

Serviço de IA

Ficheiro: lib/services/ai_recommendation_service.dart

Responsabilidades:

• Obter contexto do inventário do utilizador.
• Enviar mensagens para https://apichat.epvc.pt/api/chat.
• Usar modelo llama3.2:3b.
• Manter histórico simples em memória.
• Suportar modo silencioso para devolver apenas nomes de itens.
• Carregar itens com imagens para o fluxo de sugestão da home.

Formato da chamada Ollama:

{
  "model": "llama3.2:3b",
  "messages": [
    {"role": "system", "content": "..."},
    {"role": "user", "content": "..."}
  ],
  "stream": false
}

---

Tema visual

O tema é centralizado em app_theme.dart:

• AppColors
• AppRadius
• AppSpacing
• AppShadows
• AppText
• AppDecorations
• AppButton
• AppChip
• AppSnack

Novos ecrãs devem reutilizar estes tokens para manter consistência.

---

Segurança

• Todas as queries de dados usam user_id do utilizador autenticado quando aplicável.
• A app não deve hardcodar chaves privadas.
• A API de IA atual é endpoint remoto público do projeto, sem chave no cliente.
• Dados de inventário enviados à IA incluem nomes, categorias, tags e notas dos itens.