Documentação Inclusa

2026-05-13 15:59:02 +01:00
parent b2b0323804
commit 85a289806e
10 changed files with 1333 additions and 0 deletions
--- a/documentação/02_ARCHITECTURE.md
+++ b/documentação/02_ARCHITECTURE.md
@@ -0,0 +1,143 @@
+# 🏗️ Arquitetura Técnica
+
+## Stack Tecnológica
+
+### Decisões principais
+
+| Camada | Tecnologia escolhida | Alternativa considerada | Motivo da escolha |
+|--------|----------------------|-------------------------|-------------------|
+| App móvel | React Native | Flutter | Ecosistema JS, mais fácil de integrar com APIs web |
+| Backend / Auth | Firebase | Supabase | Setup rápido, escalável, gratuito no início |
+| Base de dados | Firestore | PostgreSQL (Supabase) | NoSQL flexível, sincronia em tempo real |
+| Armazenamento de imagens | Firebase Storage | AWS S3 | Integrado com Firebase, simples |
+| IA de imagem | Google Vision AI | AWS Rekognition | Melhor deteção de objetos, preço competitivo |
+| IA de texto (futuro) | OpenAI API | Anthropic Claude API | Fase futura — não implementar no MVP |
+
+---
+
+## Estrutura da Aplicação
+
+```
+inventoryai/
+├── mobile/                    # App React Native
+│   ├── src/
+│   │   ├── screens/           # Ecrãs principais
+│   │   │   ├── HomeScreen.jsx
+│   │   │   ├── AddItemScreen.jsx
+│   │   │   ├── InventoryScreen.jsx
+│   │   │   ├── ItemDetailScreen.jsx
+│   │   │   └── SuggestionsScreen.jsx
+│   │   ├── components/        # Componentes reutilizáveis
+│   │   ├── services/          # Lógica de negócio e APIs
+│   │   │   ├── firebase.js
+│   │   │   ├── visionApi.js
+│   │   │   └── suggestions.js
+│   │   ├── hooks/             # Custom hooks React
+│   │   ├── utils/             # Utilitários
+│   │   └── constants/         # Categorias, regras, etc.
+│   └── package.json
+├── functions/                 # Firebase Cloud Functions (opcional)
+└── docs/                      # Ficheiros .md deste projeto
+```
+
+---
+
+## Modelo de Dados (Firestore)
+
+### Coleção: `users/{userId}`
+```json
+{
+  "uid": "string",
+  "email": "string",
+  "displayName": "string",
+  "createdAt": "timestamp",
+  "preferences": {
+    "defaultContext": "travel_short"
+  }
+}
+```
+
+### Coleção: `users/{userId}/items/{itemId}`
+```json
+{
+  "id": "string",
+  "name": "string",
+  "photoUrl": "string",
+  "thumbnailUrl": "string",
+  "category": "clothing | electronics | footwear | accessories | documents | other",
+  "subcategory": "string",
+  "tags": ["string"],
+  "visionLabels": ["string"],
+  "contextTags": ["travel", "work", "casual"],
+  "createdAt": "timestamp",
+  "updatedAt": "timestamp"
+}
+```
+
+---
+
+## Fluxo de Adição de Item
+
+```
+[Utilizador tira foto]
+        ↓
+[Upload para Firebase Storage]
+        ↓
+[Chamada à Google Vision API]
+        ↓
+[Receber labels automáticas]
+        ↓
+[Mapear labels → categoria + tags sugeridas]
+        ↓
+[Mostrar ao utilizador para confirmar/editar]
+        ↓
+[Guardar item no Firestore]
+```
+
+---
+
+## Autenticação
+
+- Firebase Authentication
+- Login com Google (obrigatório no MVP)
+- Login com email/password (opcional no MVP)
+- Todos os dados são isolados por `userId`
+
+---
+
+## Performance e Limites
+
+| Recurso | Limite gratuito Firebase | Estimativa uso MVP |
+|---------|--------------------------|---------------------|
+| Firestore reads | 50.000/dia | ~5.000/dia (100 users) |
+| Firestore writes | 20.000/dia | ~2.000/dia |
+| Storage | 5 GB | ~1 GB para 100 users |
+| Google Vision API | 1.000 unidades/mês grátis | ~500 unidades/mês |
+
+> Para o MVP com utilizadores de teste, o tier gratuito é suficiente.
+
+---
+
+## Segurança (Firestore Rules — MVP)
+
+```javascript
+rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+    match /users/{userId}/{document=**} {
+      allow read, write: if request.auth != null && request.auth.uid == userId;
+    }
+  }
+}
+```
+
+---
+
+## Notas para o agente IA
+
+- **Não** sugerir AWS, Azure ou outras clouds — a decisão está tomada: Firebase
+- **Não** sugerir Flutter — a decisão está tomada: React Native
+- Quando criar código de serviço, usar o padrão `services/` definido acima
+- O modelo de dados do Firestore é o definido neste ficheiro — não alterar sem avisar
+- Para novas funcionalidades, verificar se precisam de novas coleções no Firestore
+- Imagens são sempre guardadas no Firebase Storage antes de qualquer processamento