diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index a3ed4fd..e048977 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,6 +1,8 @@ # Architecture Overview - AI Study Assistant -## πŸ—οΈ COMPLETE SYSTEM ARCHITECTURE +## πŸ—οΈ ACTUAL SYSTEM ARCHITECTURE + +> ⚠️ **Nota importante**: Esta documentaΓ§Γ£o reflete a arquitetura REAL implementada no cΓ³digo. O projeto Γ© uma aplicaΓ§Γ£o Flutter que comunica diretamente com Firebase e Ollama, sem backend Node.js ou Python intermediΓ‘rio. --- @@ -31,46 +33,45 @@ This document provides a comprehensive overview of the AI Study Assistant system ## πŸ›οΈ HIGH-LEVEL ARCHITECTURE -### System Overview +### System Overview (Real Implementation) ``` β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ PRESENTATION LAYER β”‚ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ -β”‚ Flutter App β”‚ Web App β”‚ Admin Dashboard β”‚ -β”‚ (Mobile/Web) β”‚ (PWA) β”‚ (Management) β”‚ +β”‚ Flutter App β”‚ Web App β”‚ (Same codebase) β”‚ +β”‚ (Mobile/Web) β”‚ (Flutter Web) β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β–Ό β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ API GATEWAY β”‚ -β”‚ β€’ Authentication β€’ Rate Limiting β€’ Load Balancing β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - β–Ό -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ SERVICE LAYER β”‚ +β”‚ FLUTTER SERVICES β”‚ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ -β”‚ Auth β”‚ Tutor β”‚ Quiz β”‚ Analytics β”‚ +β”‚ Auth β”‚ Tutor β”‚ Quiz β”‚ Gamification β”‚ β”‚ Service β”‚ Service β”‚ Service β”‚ Service β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ RAG β”‚ Chat β”‚ Content β”‚ Vector β”‚ +β”‚ Service β”‚ Memory β”‚ Service β”‚ Service (Mock) β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β–Ό β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ AI/ML LAYER β”‚ -β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ -β”‚ RAG β”‚ Embedding β”‚ LLM β”‚ Vector Store β”‚ -β”‚ Engine β”‚ Service β”‚ Service β”‚ (FAISS) β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - β–Ό -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ DATA LAYER β”‚ -β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ -β”‚ Firestore β”‚ Storage β”‚ Cache β”‚ Search β”‚ -β”‚ Database β”‚ (Files) β”‚ (Redis) β”‚ (Elasticsearch) β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +β”‚ EXTERNAL SERVICES β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ Firebase β”‚ Ollama LLM β”‚ +β”‚ β€’ Auth β”‚ β€’ Model: qwen3-coder:30b β”‚ +β”‚ β€’ Firestore β”‚ β€’ Endpoint: /api/chat β”‚ +β”‚ β€’ Storage β”‚ β”‚ +β”‚ β€’ Analytics β”‚ β”‚ +β”‚ β€’ Crashlytics β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` +### Architecture Notes +- **No Backend Server**: The Flutter app communicates directly with Firebase and Ollama +- **RAG Implementation**: Keyword-based search with windowing, implemented in Dart +- **Embeddings**: Mock/simulated embeddings (384 dimensions) using text hashing +- **Vector Store**: Not FAISS - simple in-memory Firestore storage with cosine similarity + --- ## πŸ“± FRONTEND ARCHITECTURE @@ -187,7 +188,14 @@ class TutorRepositoryImpl implements TutorRepository { ## ⚑ BACKEND ARCHITECTURE -### Cloud Functions Architecture +> ⚠️ **Nota**: NΓ£o existe backend Node.js/Cloud Functions. A arquitetura descrita abaixo Γ© para referΓͺncia futura apenas. + +### Actual Backend +The "backend" consists of: +1. **Firebase Services** (managed by Google) +2. **Ollama Instance** (self-hosted at 89.114.196.110:11434) + +### Cloud Functions Architecture (NOT IMPLEMENTED) ``` β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ API GATEWAY LAYER β”‚ @@ -198,6 +206,8 @@ class TutorRepositoryImpl implements TutorRepository { β”‚ β€’ CORS β”‚ β€’ Schema Valid β”‚ β€’ Per-Endpoint Limits β”‚ β”‚ β€’ Logging β”‚ β€’ Sanitization β”‚ β€’ Global Limits β”‚ β”‚ β€’ Error Handl β”‚ β€’ Type Check β”‚ β€’ Burst Protection β”‚ + +Note: This layer does not exist in the current implementation. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β–Ό @@ -274,32 +284,32 @@ export class TutorService { --- -## πŸ€– AI/ML ARCHITECTURE +## πŸ€– AI/ML ARCHITECTURE (DART IMPLEMENTATION) -### RAG Engine Architecture +### RAG Engine Architecture (Real Implementation) ``` β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ INPUT PROCESSING β”‚ +β”‚ INPUT PROCESSING (Dart) β”‚ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ β”‚ Text Input β”‚ Content β”‚ Query Processing β”‚ β”‚ Processing β”‚ Processing β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ -β”‚ β€’ Tokenization β”‚ β€’ PDF Parsing β”‚ β€’ Query Embedding β”‚ -β”‚ β€’ Cleaning β”‚ β€’ Text Extract β”‚ β€’ Vector Search β”‚ -β”‚ β€’ Normalization β”‚ β€’ Chunking β”‚ β€’ Similarity Calculation β”‚ -β”‚ β€’ Validation β”‚ β€’ Metadata β”‚ β€’ Ranking β”‚ +β”‚ β€’ Text Cleaning β”‚ β€’ PDF Parsing β”‚ β€’ Keyword Extraction β”‚ +β”‚ β€’ LaTeX Filter β”‚ β€’ Text Extract β”‚ β€’ Window Search β”‚ +β”‚ β€’ Normalization β”‚ β€’ Chunking β”‚ β€’ Similarity Matching β”‚ +β”‚ β€’ Validation β”‚ β€’ Cache (Hive) β”‚ β€’ Content Ranking β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β–Ό β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ VECTOR STORE β”‚ +β”‚ VECTOR STORE (Mock/Simple) β”‚ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ -β”‚ Indexing β”‚ Storage β”‚ Retrieval β”‚ +β”‚ Embeddings β”‚ Storage β”‚ Retrieval β”‚ β”‚ β”‚ β”‚ β”‚ -β”‚ β€’ FAISS Index β”‚ β€’ Vector Data β”‚ β€’ Approximate Search β”‚ -β”‚ β€’ HNSW Tree β”‚ β€’ Metadata β”‚ β€’ Exact Search β”‚ -β”‚ β€’ IVF Clusters β”‚ β€’ Chunks β”‚ β€’ Hybrid Search β”‚ -β”‚ β€’ Optimization β”‚ β€’ Updates β”‚ β€’ Filtering β”‚ +β”‚ β€’ Hash-based β”‚ β€’ Firestore β”‚ β€’ Cosine Similarity β”‚ +β”‚ β€’ 384 dims β”‚ β€’ contentChunks β”‚ β€’ Keyword Matching β”‚ +β”‚ β€’ Deterministic β”‚ β€’ materials β”‚ β€’ Window-based Search β”‚ +β”‚ β€’ Fast/Cheap β”‚ β€’ No FAISS β”‚ β€’ No Approximate Search β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β–Ό @@ -309,107 +319,124 @@ export class TutorService { β”‚ Prompt β”‚ Generation β”‚ Post-Processing β”‚ β”‚ Engineering β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ -β”‚ β€’ Context Build β”‚ β€’ OpenAI API β”‚ β€’ Response Validation β”‚ -β”‚ β€’ Template β”‚ β€’ Anthropic APIβ”‚ β€’ Safety Checks β”‚ -β”‚ β€’ Formatting β”‚ β€’ Model Selectionβ”‚ β€’ Quality Assessment β”‚ -β”‚ β€’ Safety β”‚ β€’ Rate Limit β”‚ β€’ Caching β”‚ +β”‚ β€’ Context Embed β”‚ β€’ Ollama API β”‚ β€’ UTF-8 Encoding β”‚ +β”‚ β€’ User Persona β”‚ β€’ qwen3-coder β”‚ β€’ Response Formatting β”‚ +β”‚ β€’ PDF Content β”‚ β€’ 30B model β”‚ β€’ Citation Handling β”‚ +β”‚ β€’ Constraints β”‚ β€’ Direct HTTP β”‚ β€’ Error Handling β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` -### RAG Pipeline Implementation -```python -# RAG Engine Pipeline -class RAGPipeline: - def __init__(self): - self.embedding_service = EmbeddingService() - self.vector_store = VectorStore() - self.llm_service = LLMService() - self.prompt_builder = PromptBuilder() - - async def process_query(self, query: str, mode: str = "EXPLANATION") -> str: - # Step 1: Process input - processed_query = self.preprocess_query(query) - - # Step 2: Generate embedding - query_embedding = await self.embedding_service.encode([processed_query]) - - # Step 3: Retrieve relevant context - context_chunks = await self.vector_store.search( - query_embedding[0], - k=10, - filters=self.get_filters(mode) - ) - - # Step 4: Build prompt - prompt = self.prompt_builder.build( - query=processed_query, - context=context_chunks, - mode=mode - ) - - # Step 5: Generate response - response = await self.llm_service.generate(prompt) - - # Step 6: Post-process - final_response = self.postprocess_response(response, context_chunks) - - return final_response +### RAG Pipeline Implementation (Dart) +```dart +// Real implementation in lib/core/services/rag_ai_service.dart +class RAGAIService { + static const String _baseUrl = 'http://89.114.196.110:11434/api/chat'; + static const String _model = 'qwen3-coder:30b'; + + static Future askTutor({ + required String question, + required List materialIds, + required String mode, + }) async { + // Step 1: Retrieve context from materials (keyword-based) + final context = await MaterialsRAGService.getContextForQuestion( + question: question, + materialIds: materialIds, + ); - def preprocess_query(self, query: str) -> str: - # Clean and normalize query - query = query.strip().lower() - # Remove special characters - query = re.sub(r'[^\w\s]', '', query) - # Tokenize and normalize - return query + // Step 2: Build prompt with embedded context + final prompt = _buildPrompt( + question: question, + context: context, + mode: mode, + ); - def get_filters(self, mode: str) -> Dict[str, Any]: - # Mode-specific filtering - filters = {} - if mode == "EXPLANATION": - filters["content_type"] = ["explanation", "definition"] - elif mode == "TUTOR": - filters["difficulty"] = {"$lte": 0.7} - return filters + // Step 3: Call Ollama API directly + final response = await http.post( + Uri.parse(_baseUrl), + headers: {'Content-Type': 'application/json; charset=utf-8'}, + body: utf8.encode(jsonEncode({ + 'model': _model, + 'messages': [ + {'role': 'system', 'content': _systemPrompt}, + {'role': 'user', 'content': prompt}, + ], + })), + ); + + // Step 4: Process response + return _processResponse(response); + } +} + +// MaterialsRAGService - keyword window search +class MaterialsRAGService { + static Future getContextForQuestion({ + required String question, + required List materialIds, + }) async { + // PDF extraction with syncfusion_flutter_pdf + // Keyword matching with windowing (1200 chars) + // No FAISS, no embeddings, no vector search + } +} ``` +### Key Differences from Original Design +- ❌ **No Python RAG Engine**: Implemented entirely in Dart +- ❌ **No FAISS**: Uses keyword matching and simple cosine similarity +- ❌ **No Sentence Transformers**: Hash-based mock embeddings (384 dims) +- ❌ **No OpenAI/Anthropic**: Only Ollama (qwen3-coder:30b) +- βœ… **PDF Processing**: syncfusion_flutter_pdf for text extraction +- βœ… **Caching**: Hive for PDF content caching +- βœ… **Firestore**: Stores contentChunks with simple vector data + --- ## πŸ—„οΈ DATA ARCHITECTURE -### Database Schema +### Database Schema (Actual Implementation) ``` β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ FIRESTORE DATABASE β”‚ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ -β”‚ USERS β”‚ CONTENT β”‚ LEARNING β”‚ +β”‚ USERS β”‚ MATERIALS β”‚ CONTENTCHUNKS β”‚ β”‚ β”‚ β”‚ β”‚ -β”‚ β€’ uid β”‚ β€’ id β”‚ β€’ studentId β”‚ -β”‚ β€’ email β”‚ β€’ title β”‚ β€’ concept β”‚ -β”‚ β€’ role β”‚ β€’ subject β”‚ β€’ mastery β”‚ -β”‚ β€’ schoolId β”‚ β€’ concept β”‚ β€’ confidence β”‚ -β”‚ β€’ profile β”‚ β€’ difficulty β”‚ β€’ lastInteraction β”‚ -β”‚ β€’ preferences β”‚ β€’ grade β”‚ β€’ interactions β”‚ -β”‚ β€’ createdAt β”‚ β€’ uploadedAt β”‚ β€’ recommendations β”‚ -β”‚ β€’ lastActive β”‚ β€’ uploadedBy β”‚ β€’ spacedRepetition β”‚ +β”‚ β€’ uid β”‚ β€’ id β”‚ β€’ id β”‚ +β”‚ β€’ email β”‚ β€’ teacherId β”‚ β€’ text β”‚ +β”‚ β€’ role β”‚ β€’ fileName β”‚ β€’ subject β”‚ +β”‚ β€’ schoolId β”‚ β€’ fileUrl β”‚ β€’ concept β”‚ +β”‚ β€’ displayName β”‚ β€’ type β”‚ β€’ embedding (List) β”‚ +β”‚ β€’ createdAt β”‚ β€’ createdAt β”‚ β€’ metadata β”‚ +β”‚ β”‚ β”‚ β€’ createdAt β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β–Ό β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ QUIZ β”‚ INTERACTIONS β”‚ SCHOOLS β”‚ -β”‚ β”‚ β”‚ β”‚ -β”‚ β€’ id β”‚ β€’ id β”‚ β€’ id β”‚ -β”‚ β€’ title β”‚ β€’ studentId β”‚ β€’ name β”‚ -β”‚ β€’ subject β”‚ β€’ query β”‚ β€’ email β”‚ -β”‚ β€’ concept β”‚ β€’ response β”‚ β€’ settings β”‚ -β”‚ β€’ questions β”‚ β€’ mode β”‚ β€’ subscription β”‚ -β”‚ β€’ timeLimit β”‚ β€’ timestamp β”‚ β€’ maxStudents β”‚ -β”‚ β€’ passingScore β”‚ β€’ feedback β”‚ β€’ maxTeachers β”‚ -β”‚ β€’ createdBy β”‚ β€’ metadata β”‚ β€’ isActive β”‚ -β”‚ β€’ createdAt β”‚ β€’ sources β”‚ β€’ createdAt β”‚ +β”‚ QUIZZES β”‚ CONVERSATIONS β”‚ CLASSES/ENROLLMENTS β”‚ +β”‚ β”‚ (userChats/*) β”‚ β”‚ +β”‚ β€’ id β”‚ β”‚ β€’ id β”‚ +β”‚ β€’ teacherId β”‚ β€’ id β”‚ β€’ teacherId/classId β”‚ +β”‚ β€’ title β”‚ β€’ title β”‚ β€’ name/code β”‚ +β”‚ β€’ description β”‚ β€’ selectedMaterialsβ”‚ β€’ studentId β”‚ +β”‚ β€’ questions β”‚ β€’ createdAt β”‚ β€’ createdAt/joinedAt β”‚ +β”‚ β€’ createdAt β”‚ β€’ hasUserMessageβ”‚ β”‚ +β”‚ β”‚ β€’ messages/* β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` +### Collections NOT Implemented +- ❌ `learningStates` - Not in codebase +- ❌ `auditLogs` - Not implemented +- ❌ `quizAttempts` - Not implemented +- ❌ `interactions` - Replaced by userChats/{uid}/conversations + +### Roles (Only 2 implemented) +- βœ… `student` - Can view content, take quizzes, ask tutor +- βœ… `teacher` - Can upload materials, create quizzes, view analytics +- ❌ `admin` - NOT IMPLEMENTED +- ❌ `super_admin` - NOT IMPLEMENTED + ### Data Flow Architecture ``` β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” @@ -524,88 +551,84 @@ class RAGPipeline: --- -## πŸ”§ TECHNOLOGY STACK +## πŸ”§ TECHNOLOGY STACK (ACTUAL) ### Frontend Technologies ```yaml Flutter Framework: - - SDK: 3.41.0+ + - SDK: ^3.11.5 (Dart 3.0+) - Language: Dart 3.0+ - State Management: Riverpod 2.4.9 - Navigation: GoRouter 12.1.3 - UI: Material Design 3 - - Testing: Flutter Test, Integration Test + - Testing: Flutter Test, Integration Test (not implemented) Firebase Services: - - Authentication: Firebase Auth - - Database: Cloud Firestore - - Storage: Firebase Storage - - Analytics: Firebase Analytics - - Crashlytics: Firebase Crashlytics - - Performance: Firebase Performance + - Authentication: firebase_auth ^4.17.8 + - Database: cloud_firestore ^4.15.8 + - Storage: firebase_storage ^11.6.9 + - Analytics: firebase_analytics ^10.8.0 + - Crashlytics: firebase_crashlytics ^3.5.7 + - Messaging: firebase_messaging ^14.9.3 + - Performance: NOT IMPLEMENTED + - Remote Config: NOT IMPLEMENTED Third-Party Libraries: - - HTTP: Dio 5.4.0 - - Caching: Cached Network Image 3.3.0 - - Fonts: Google Fonts 6.1.0 - - Animations: Flutter Animate 4.2.0 - - Local Storage: Hive 2.2.3 + - HTTP: Dio ^5.4.0, http ^1.1.2 + - PDF Processing: syncfusion_flutter_pdf ^33.2.6 + - Caching: cached_network_image ^3.3.0, hive ^2.2.3 + - Fonts: google_fonts ^6.1.0 + - Animations: flutter_animate ^4.2.0, lottie ^2.7.0 + - Charts: fl_chart ^0.64.0 + - File Handling: file_selector ^1.0.3, image_picker ^1.0.4 + - Utilities: intl ^0.20.2, uuid ^4.2.1, equatable ^2.0.5 ``` -### Backend Technologies +### Backend Technologies (NOT IMPLEMENTED) ```yaml -Runtime Environment: - - Platform: Firebase Cloud Functions - - Runtime: Node.js 18.x LTS - - Language: TypeScript 5.0+ - - Package Manager: npm 9.x +Status: NO BACKEND SERVER -Core Services: - - Authentication: Firebase Admin SDK - - Database: Firestore Admin SDK - - Storage: Cloud Storage Admin SDK - - HTTP Framework: Express.js 4.18+ - - Validation: Joi 17.9+ - - Security: Helmet 7.0+ +The following technologies are documented but NOT implemented: +❌ Firebase Cloud Functions - Not used +❌ Node.js / TypeScript - Not used +❌ Python RAG Engine - Not used +❌ FAISS Vector Database - Not used +❌ Sentence Transformers - Not used +❌ OpenAI API - Not used +❌ Anthropic Claude - Not used -AI/ML Services: - - Vector Database: FAISS 1.7.4 - - Embeddings: Sentence Transformers 2.2.2 - - LLM APIs: OpenAI 4.20.1, Anthropic 0.6.3 - - Processing: NumPy 1.21+, PyTorch 1.12+ - -Monitoring & Logging: - - Logging: Winston 3.8+ - - Metrics: Prometheus Client - - Tracing: OpenTelemetry - - Error Tracking: Sentry +Actual Implementation: +βœ… Flutter app calls Ollama directly via HTTP +βœ… Firebase services handle auth, database, storage +βœ… RAG logic implemented in Dart (keyword matching) +βœ… Embeddings: Mock/hash-based in Dart ``` ### Infrastructure Technologies ```yaml Cloud Platform: - - Provider: Google Cloud Platform - - Services: Firebase, Cloud Functions, Cloud Storage - - Regions: us-central1, europe-west1 - - CDN: Firebase Hosting + - Provider: Google Firebase (BaaS) + - Services: Firebase Auth, Firestore, Storage + - Hosting: Firebase Hosting (for web builds) + - Self-hosted: Ollama LLM server (89.114.196.110:11434) Database: - - Primary: Cloud Firestore - - Cache: Redis (MemoryStore) - - Search: Elasticsearch (if needed) - - Backup: Automated daily backups + - Primary: Cloud Firestore (NoSQL) + - Cache: Hive (local), Memory cache + - Search: Not implemented (no Elasticsearch) + - Backup: Firebase automated backups Security: - - TLS: 1.3 - - Authentication: Firebase Auth - - Authorization: Custom RBAC - - Monitoring: Security Command Center + - TLS: HTTPS for all communications + - Authentication: Firebase Auth (email/password, Google) + - Authorization: Client-side role checks (student/teacher) + - Note: No admin role implemented CI/CD: - - Pipeline: GitHub Actions - - Build: Cloud Build - - Deploy: Firebase CLI - - Testing: Automated test suites + - Pipeline: Manual builds + - Build: flutter build web/apk + - Deploy: Firebase CLI (manual) + - Testing: No automated tests implemented ``` --- diff --git a/docs/BACKEND_MVP_TASKS.md b/docs/BACKEND_MVP_TASKS.md index 607fc2b..830706a 100644 --- a/docs/BACKEND_MVP_TASKS.md +++ b/docs/BACKEND_MVP_TASKS.md @@ -1,71 +1,47 @@ # Backend MVP Tasks - AI Study Assistant -## πŸ”§ MVP BACKEND ROADMAP (8-12 WEEKS) +> ⚠️ **IMPORTANTE**: Este documento foi atualizado para refletir a arquitetura REAL do projeto. +> +> **NΓƒO EXISTE BACKEND NODE.JS/TYPESCRIPT**. O projeto utiliza apenas: +> - Firebase Services (Auth, Firestore, Storage) - BaaS +> - Ollama LLM auto-hospedado +> - LΓ³gica de negΓ³cio implementada em Dart no Flutter --- ## πŸ—οΈ WEEK 1-2: FIREBASE FOUNDATION ### Task 1.1: Firebase Project Setup -**Priority**: Critical -**Estimated Time**: 6 hours -**Dependencies**: None +**Status**: βœ… COMPLETED #### Subtasks: -- [ ] Create Firebase project in Google Cloud Console -- [ ] Enable required Firebase services: - - [ ] Firebase Authentication - - [ ] Cloud Firestore - - [ ] Cloud Storage - - [ ] Cloud Functions - - [ ] Firebase Analytics -- [ ] Configure project settings -- [ ] Set up billing account (if needed) -- [ ] Enable API access for LLM services +- βœ… Create Firebase project in Google Cloud Console +- βœ… Enable required Firebase services: + - βœ… Firebase Authentication + - βœ… Cloud Firestore + - βœ… Cloud Storage + - ❌ Cloud Functions - NOT IMPLEMENTED (not needed) + - βœ… Firebase Analytics +- βœ… Configure project settings +- βœ… Enable Ollama API access (self-hosted) -#### Detailed Steps: +#### Actual Configuration: -1. **Create Firebase Project** -```bash -# Using Firebase CLI -firebase projects create teachit-ai-assistant -firebase use teachit-ai-assistant +**pubspec.yaml dependencies:** +```yaml +dependencies: + firebase_core: ^2.25.4 + firebase_auth: ^4.17.8 + cloud_firestore: ^4.15.8 + firebase_storage: ^11.6.9 + firebase_analytics: ^10.8.0 + firebase_crashlytics: ^3.5.7 ``` -2. **Enable Services** -```bash -# Enable Authentication -firebase auth --enable - -# Enable Firestore -firebase firestore:databases:create - -# Enable Storage -firebase storage:buckets:create teachit-content - -# Enable Functions -firebase functions:config:set -``` - -3. **Project Configuration** -```json -// firebase.json -{ - "firestore": { - "rules": "firestore.rules", - "indexes": "firestore.indexes.json" - }, - "storage": { - "rules": "storage.rules" - }, - "functions": { - "predeploy": [ - "npm --prefix \"$RESOURCE_DIR\" run lint", - "npm --prefix \"$RESOURCE_DIR\" run build" - ], - "source": "functions" - } -} +**Ollama Configuration (in rag_ai_service.dart):** +```dart +static const String _baseUrl = 'http://89.114.196.110:11434/api/chat'; +static const String _model = 'qwen3-coder:30b'; ``` --- diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 4ecd44f..d78ef68 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,12 +1,16 @@ # Contributing Guidelines - AI Study Assistant +> ⚠️ **ATUALIZADO**: Este documento foi corrigido para refletir a arquitetura REAL (Flutter + Firebase apenas). +> +> **Nota:** NΓ£o existe backend Node.js nem Python RAG engine. Toda a lΓ³gica estΓ‘ no Flutter. + ## 🀝 HOW TO CONTRIBUTE --- ## πŸ“‹ OVERVIEW -Thank you for your interest in contributing to the AI Study Assistant! This guide provides comprehensive information on how to contribute to our project, including development workflows, coding standards, and community guidelines. +Thank you for your interest in contributing to the AI Study Assistant! This guide provides information on how to contribute to our Flutter + Firebase project. --- @@ -14,11 +18,10 @@ Thank you for your interest in contributing to the AI Study Assistant! This guid ### Prerequisites - **Git**: Version 2.30 or higher -- **Flutter**: Version 3.41.0+ -- **Node.js**: Version 18.x LTS -- **Python**: Version 3.9+ (for RAG engine) +- **Flutter**: Version 3.11.5+ (with Dart 3.0+) - **Firebase CLI**: Latest version - **Code Editor**: VS Code recommended +- **Note**: No Node.js or Python required (backend is Firebase BaaS) ### Development Environment Setup 1. Fork the repository @@ -32,19 +35,15 @@ Thank you for your interest in contributing to the AI Study Assistant! This guid git clone https://github.com/YOUR_USERNAME/teachit.git cd teachit -# Install Flutter dependencies +# Install Flutter dependencies only flutter pub get -# Install Node.js dependencies -cd functions && npm install && cd .. - -# Install Python dependencies -cd rag_engine && pip install -r requirements.txt && cd .. +# Note: No backend dependencies to install +# No Cloud Functions (Firebase BaaS is used) +# No Python RAG engine (implemented in Dart) # Run tests flutter test -npm test -pytest tests/ ``` --- diff --git a/docs/DEPLOYMENT_GUIDE.md b/docs/DEPLOYMENT_GUIDE.md index 287da19..538eaea 100644 --- a/docs/DEPLOYMENT_GUIDE.md +++ b/docs/DEPLOYMENT_GUIDE.md @@ -1,12 +1,18 @@ # Deployment Guide - AI Study Assistant -## πŸš€ COMPLETE DEPLOYMENT STRATEGY +> ⚠️ **ATUALIZADO**: Este documento foi corrigido para refletir a arquitetura REAL do projeto (Flutter + Firebase BaaS, sem backend Node.js). +> +> **O que mudou:** +> - ❌ Removido: Node.js dependencies, Cloud Functions, backend server setup +> - βœ… Atualizado: Flutter SDK ^3.11.5, Firebase BaaS only, Ollama LLM + +## πŸš€ DEPLOYMENT STRATEGY --- ## πŸ“‹ OVERVIEW -This comprehensive guide covers the complete deployment process for the AI Study Assistant project, including development, staging, and production environments, CI/CD pipelines, monitoring, and maintenance procedures. +This guide covers the deployment process for the AI Study Assistant project. **Note:** This is a Flutter + Firebase BaaS (Backend-as-a-Service) architecture. There is no custom backend server - all business logic is in the Flutter app. --- @@ -54,29 +60,25 @@ cd teachit # Install Flutter dependencies flutter pub get -# Install Node.js dependencies (for functions) -cd functions -npm install +# Note: No Node.js backend to install +# No Cloud Functions to set up -# Start Firebase emulators -firebase emulators:start - -# Run Flutter app +# Run Flutter app (Firebase services connect directly) flutter run ``` #### Development Firebase Project: - **Project ID**: `teachit-dev-12345` -- **Services**: All services enabled in test mode +- **Services**: Auth, Firestore, Storage, Analytics, Crashlytics - **Security Rules**: Relaxed for development -- **Emulators**: Local Firestore, Auth, Storage, Functions +- **Emulators**: Local Firestore, Auth, Storage (Functions not used) #### Environment Variables: ```bash # .env.development FIREBASE_PROJECT_ID=teachit-dev-12345 FLUTTER_ENV=development -API_BASE_URL=http://localhost:5001 +OLLAMA_BASE_URL=http://89.114.196.110:11434/api/chat ENABLE_LOGGING=true ENABLE_DEBUG=true ``` diff --git a/docs/DEVELOPMENT_SETUP.md b/docs/DEVELOPMENT_SETUP.md index e312f58..537eb1a 100644 --- a/docs/DEVELOPMENT_SETUP.md +++ b/docs/DEVELOPMENT_SETUP.md @@ -1,12 +1,16 @@ # Development Setup Guide - AI Study Assistant +> ⚠️ **ATUALIZADO**: Este documento foi corrigido para refletir a arquitetura REAL. +> +> **Nota:** NΓƒO Γ© necessΓ‘rio Node.js nem Python. O projeto usa Flutter + Firebase BaaS apenas. + ## πŸ› οΈ COMPLETE DEVELOPMENT ENVIRONMENT SETUP --- ## πŸ“‹ OVERVIEW -This guide provides step-by-step instructions for setting up a complete development environment for the AI Study Assistant project, including Flutter frontend, Node.js backend, Firebase services, and development tools. +This guide provides step-by-step instructions for setting up the development environment for the AI Study Assistant project. **Note:** This is a Flutter + Firebase BaaS (Backend-as-a-Service) project. There is no custom Node.js backend or Python RAG engine to set up. --- diff --git a/docs/FIREBASE_CONFIGURATION.md b/docs/FIREBASE_CONFIGURATION.md index 217616a..8b7b08f 100644 --- a/docs/FIREBASE_CONFIGURATION.md +++ b/docs/FIREBASE_CONFIGURATION.md @@ -1,12 +1,21 @@ # Firebase Configuration - AI Study Assistant +> ⚠️ **ATUALIZADO**: Este documento foi corrigido para refletir a configuraΓ§Γ£o REAL do projeto. +> +> **Notas Importantes:** +> - ❌ Cloud Functions: NΓƒO implementado +> - ❌ Performance Monitoring: NΓƒO implementado +> - ❌ Remote Config: NΓƒO implementado +> - ❌ Roles admin/super_admin: NΓƒO implementados (apenas student/teacher) +> - βœ… Estrutura real: users, materials, contentChunks, quizzes, classes, enrollments, userChats + ## πŸ”₯ COMPLETE FIREBASE SETUP GUIDE --- ## πŸ“‹ OVERVIEW -This document provides comprehensive instructions for setting up Firebase for the AI Study Assistant project, including authentication, database, storage, cloud functions, and security configurations. +This document provides instructions for setting up Firebase for the AI Study Assistant project. Note: This is a **Flutter + Firebase BaaS** architecture without a custom backend. --- @@ -32,15 +41,18 @@ This document provides comprehensive instructions for setting up Firebase for th ### 1.2 Enable Required Services -#### Firebase Services to Enable: +#### Firebase Services Actually Used: - βœ… Firebase Authentication - βœ… Cloud Firestore - βœ… Cloud Storage -- βœ… Cloud Functions - βœ… Firebase Analytics - βœ… Firebase Crashlytics -- βœ… Firebase Performance Monitoring -- βœ… Firebase Remote Config +- βœ… Firebase Cloud Messaging + +#### Firebase Services NOT Used: +- ❌ Cloud Functions (not needed - logic in Flutter) +- ❌ Firebase Performance Monitoring (not implemented) +- ❌ Firebase Remote Config (not implemented) #### Enable Commands: ```bash @@ -53,10 +65,9 @@ firebase firestore:databases:create # Enable Storage firebase storage:buckets:create teachit-content -# Enable Functions -firebase functions:config:set - # Enable Analytics (automatically enabled) + +# Note: Cloud Functions not needed ``` --- @@ -105,17 +116,23 @@ firebase functions:config:set ### 2.2 User Management Configuration -#### Custom Claims Setup: -```javascript -// Cloud Function to set custom claims -exports.setCustomClaims = functions.auth.user().onCreate(async (user) => { - const customClaims = { - role: 'student', // Default role - schoolId: 'default', - permissions: ['basic_access'] - }; - - await admin.auth().setCustomUserClaims(user.uid, customClaims); +#### User Roles (Only 2 implemented): +```dart +// lib/core/services/auth_service.dart +class AuthService { + static const String studentRole = 'student'; + static const String teacherRole = 'teacher'; + // ❌ adminRole - NOT IMPLEMENTED + // ❌ superAdminRole - NOT IMPLEMENTED +} +``` + +**Note:** Role assignment is done client-side during signup: +```dart +await FirebaseFirestore.instance.collection('users').doc(user.uid).set({ + 'role': selectedRole, // 'student' or 'teacher' + 'email': user.email, + 'createdAt': FieldValue.serverTimestamp(), }); ``` @@ -131,17 +148,25 @@ exports.setCustomClaims = functions.auth.user().onCreate(async (user) => { 3. Choose location (e.g., `europe-west1`) 4. Set up security rules -#### Database Structure: +#### Actual Database Structure: ```javascript -// Collections Structure -schools/{schoolId} -β”œβ”€β”€ users/{userId} -β”œβ”€β”€ learningStates/{studentId} -β”œβ”€β”€ contentChunks/{chunkId} -β”œβ”€β”€ quizzes/{quizId} -β”œβ”€β”€ quizAttempts/{attemptId} -β”œβ”€β”€ interactions/{interactionId} -└── auditLogs/{logId} +// Collections Structure (as implemented in code) + +// Top-level collections: +users/{userId} // User profiles with role +schools/{schoolId} // Schools/institutions +materials/{materialId} // Teacher uploaded content +contentChunks/{chunkId} // Text chunks with mock embeddings +quizzes/{quizId} // Quiz definitions +classes/{classId} // Teacher-created classes +enrollments/{enrollmentId} // Student class memberships +userChats/{userId}/conversations/{convId}/messages/{msgId} // Chat history + +// Collections NOT implemented: +// ❌ learningStates/{studentId} - Not in codebase +// ❌ quizAttempts/{attemptId} - Not implemented +// ❌ interactions/{interactionId} - Replaced by userChats subcollection +// ❌ auditLogs/{logId} - Not implemented ``` ### 3.2 Security Rules diff --git a/docs/FRONTEND_MVP_TASKS.md b/docs/FRONTEND_MVP_TASKS.md index 636f22e..01e5cca 100644 --- a/docs/FRONTEND_MVP_TASKS.md +++ b/docs/FRONTEND_MVP_TASKS.md @@ -1,5 +1,10 @@ # Frontend MVP Tasks - AI Study Assistant +> ⚠️ **ATUALIZADO**: Este documento foi corrigido para refletir a implementaΓ§Γ£o REAL. +> +> **VersΓ£o Flutter:** 3.11.5+ (nΓ£o 3.41.9 como documentado anteriormente) +> **Nota:** NΓ£o existe backend Node.js. Firebase BaaS Γ© usado diretamente. + ## πŸ“± MVP FRONTEND ROADMAP (8-12 WEEKS) --- @@ -13,50 +18,77 @@ #### Subtasks: - [ ] Create new Flutter project: `flutter create learn_it` -- [ ] Configure Flutter SDK version (3.41.9 or latest stable) +- [x] Configure Flutter SDK version (^3.11.5 or higher stable) - [ ] Set up version control (Git repository) - [ ] Create initial project structure - [ ] Configure pubspec.yaml with initial dependencies -#### Dependencies to Add: +#### Actual Dependencies (from pubspec.yaml): ```yaml dependencies: flutter: sdk: flutter + flutter_localizations: + sdk: flutter # State Management flutter_riverpod: ^2.4.9 + riverpod_annotation: ^2.3.3 + + # Navigation + go_router: ^12.1.3 + flutter_animate: ^4.2.0+1 # Firebase - firebase_core: ^2.24.2 - firebase_auth: ^4.15.3 - cloud_firestore: ^4.13.6 - firebase_storage: ^11.5.6 + firebase_core: ^2.25.4 + firebase_auth: ^4.17.8 + cloud_firestore: ^4.15.8 + firebase_storage: ^11.6.9 + firebase_analytics: ^10.8.0 + firebase_messaging: ^14.9.3 + firebase_crashlytics: ^3.5.7 # UI Components cupertino_icons: ^1.0.6 google_fonts: ^6.1.0 - - # Navigation - go_router: ^12.1.3 + cached_network_image: ^3.3.0 + flutter_svg: ^2.0.9 + lottie: ^2.7.0 + shimmer: ^3.0.0 # HTTP & Networking - http: ^1.1.2 dio: ^5.4.0 + http: ^1.1.2 + connectivity_plus: ^5.0.2 # Local Storage shared_preferences: ^2.2.2 + hive: ^2.2.3 + hive_flutter: ^1.1.0 + flutter_secure_storage: ^9.0.0 + + # PDF Processing (for RAG) + syncfusion_flutter_pdf: ^33.2.6 + file_selector: ^1.0.3 + image_picker: ^1.0.4 # Utilities - intl: ^0.19.0 + intl: ^0.20.2 uuid: ^4.2.1 + equatable: ^2.0.5 + + # Charts + fl_chart: ^0.64.0 + + # Biometrics + local_auth: ^2.1.7 dev_dependencies: flutter_test: sdk: flutter flutter_lints: ^3.0.1 - mockito: ^5.4.4 build_runner: ^2.4.7 + mockito: ^5.4.4 ``` #### Implementation Details: diff --git a/docs/PERFORMANCE_GUIDE.md b/docs/PERFORMANCE_GUIDE.md index 1718083..56d570d 100644 --- a/docs/PERFORMANCE_GUIDE.md +++ b/docs/PERFORMANCE_GUIDE.md @@ -1,12 +1,16 @@ # Performance Optimization Guide - AI Study Assistant +> ⚠️ **ATUALIZADO**: Este documento foi corrigido para refletir a arquitetura REAL. +> +> **Nota:** O projeto Γ© Flutter + Firebase BaaS + Ollama. NΓ£o existe backend Node.js para otimizar. + ## ⚑ COMPREHENSIVE PERFORMANCE STRATEGY --- ## πŸ“‹ OVERVIEW -This guide provides comprehensive performance optimization strategies for the AI Study Assistant platform, covering frontend performance, backend optimization, database efficiency, AI model performance, and overall system scalability. +This guide provides performance optimization strategies for the AI Study Assistant platform (Flutter + Firebase BaaS + Ollama). Focus areas: Flutter frontend performance, Firestore database efficiency, Ollama API response times, and Firebase service optimization. --- diff --git a/docs/PROJECT_OVERVIEW.md b/docs/PROJECT_OVERVIEW.md index 088c9eb..842ee51 100644 --- a/docs/PROJECT_OVERVIEW.md +++ b/docs/PROJECT_OVERVIEW.md @@ -6,12 +6,14 @@ Documento Completo de EspecificaΓ§Γ£o TΓ©cnica e PedagΓ³gica οΏ½ οΏ½ PARTE 1: VISΓƒO E ARQUITECTURA GLOBAL -1.1 DefiniΓ§Γ£o do Sistema -Este projeto Γ© uma Plataforma de InteligΓͺncia Educacional DistribuΓ­da baseada em: -β€’ LLMs condicionados por conhecimento institucional (nΓ£o conhecimento aberto) -β€’ Arquitectura RAG multi-camada (Retrieval-Augmented Generation) -β€’ Controlo de acesso baseado em papΓ©is (RBAC) -β€’ GeraΓ§Γ£o adaptativa de aprendizagem (pedagogically-constrained output) +> ⚠️ **NOTA IMPORTANTE**: Este documento descreve uma visΓ£o aspiracional. A implementaΓ§Γ£o REAL Γ©: Flutter + Firebase + Ollama (sem backend Node.js/Python). + +1.1 DefiniΓ§Γ£o do Sistema (VERSΓƒO REAL IMPLEMENTADA) +Este projeto Γ© uma Plataforma de InteligΓͺncia Educacional baseada em: +β€’ LLM local (Ollama qwen3-coder:30b) com materiais PDF de professores +β€’ RAG simplificado com keyword search em Dart (nΓ£o FAISS/BM25) +β€’ RBAC apenas com roles student/teacher (sem admin) +β€’ Flutter 3.11.5+ com Firebase BaaS (Backend-as-a-Service) Core Identity: Institutional AI Learning Operating System with controlled knowledge injection, diff --git a/docs/PROJECT_PROGRESS.md b/docs/PROJECT_PROGRESS.md index acc31b2..781e119 100644 --- a/docs/PROJECT_PROGRESS.md +++ b/docs/PROJECT_PROGRESS.md @@ -1,16 +1,14 @@ # πŸ“Š Project Progress - AI Study Assistant - +> ⚠️ **ATUALIZADO**: Este documento foi corrigido para refletir a arquitetura REAL. +> +> **Nota:** "Backend Integration" refere-se a Firebase BaaS (Backend-as-a-Service), nΓ£o a um backend Node.js/Python customizado. --- - - ## 🎯 OVERVIEW - - -This document tracks the overall progress of the AI Study Assistant project development. Updated in real-time as features are implemented. +This document tracks the overall progress of the AI Study Assistant project development (Flutter + Firebase BaaS + Ollama). diff --git a/docs/RAG_ENGINE_MVP_TASKS.md b/docs/RAG_ENGINE_MVP_TASKS.md index 9f884ba..3cfd732 100644 --- a/docs/RAG_ENGINE_MVP_TASKS.md +++ b/docs/RAG_ENGINE_MVP_TASKS.md @@ -1,43 +1,59 @@ # RAG Engine MVP Tasks - AI Study Assistant -## 🧠 MVP RAG ENGINE ROADMAP (8-12 WEEKS) +> ⚠️ **IMPORTANTE - DOCUMENTO DESATUALIZADO**: Este documento descreve uma arquitetura Python/FAISS que **NΓƒO FOI IMPLEMENTADA**. +> +> **ImplementaΓ§Γ£o Real:** +> - **Linguagem**: Dart (Flutter) +> - **LocalizaΓ§Γ£o**: `lib/core/services/materials_rag_service.dart`, `lib/core/services/rag_ai_service.dart` +> - **Vector Store**: Firestore com embeddings mock (hash-based) +> - **PDF Processing**: `syncfusion_flutter_pdf` (nΓ£o Python) +> - **Busca**: Keyword window search (nΓ£o FAISS) +> +> **NΓƒO EXISTE:** Python, FAISS, Sentence Transformers, OpenAI, Anthropic --- -## πŸ“š WEEK 1-2: FOUNDATION & SETUP +## 🧠 MVP RAG ENGINE ROADMAP (DOCUMENTAÇÃO ORIGINAL - NΓƒO IMPLEMENTADA) + +--- + +## πŸ“š WEEK 1-2: FOUNDATION & SETUP (NOT IMPLEMENTED) ### Task 1.1: Vector Database Setup -**Priority**: Critical -**Estimated Time**: 8 hours -**Dependencies**: None +**Status**: ❌ NOT IMPLEMENTED - FAISS nΓ£o Γ© utilizado -#### Subtasks: -- [ ] Choose vector database technology (FAISS for MVP) -- [ ] Set up development environment -- [ ] Install required dependencies -- [ ] Configure storage for vector indices -- [ ] Create basic vector operations -- [ ] Set up backup and recovery +#### What Actually Exists: +```dart +// lib/core/services/vector_service.dart +class VectorService { + // Mock embedding generation using text hashing + static List generateEmbedding(String text) { + final embedding = List.filled(384, 0.0); + // Hash-based deterministic embeddings (not ML) + return embedding; + } +} -#### Technology Stack: +// lib/core/services/materials_rag_service.dart +class MaterialsRAGService { + // Keyword-based window search for PDFs + static Future getContextForQuestion(...) async { + // 1. Extract PDF text with syncfusion_flutter_pdf + // 2. Find keyword matches + // 3. Return window of 1200 chars around match + // NO FAISS, NO VECTOR SEARCH, NO PYTHON + } +} +``` + +#### Technology Stack (Original - NOT USED): ```bash -# Core dependencies -pip install faiss-cpu # or faiss-gpu for GPU acceleration -pip install sentence-transformers -pip install numpy -pip install pandas -pip install scikit-learn - -# Text processing -pip install nltk -pip install spacy -python -m spacy download en_core_web_sm - -# Storage and utilities -pip install firebase-admin -pip install google-cloud-storage -pip install pickle -pip install h5py +# These dependencies DO NOT EXIST in the project: +# ❌ pip install faiss-cpu +# ❌ pip install sentence-transformers +# ❌ pip install numpy +# ❌ pip install nltk +# ❌ pip install spacy ``` #### Project Structure: diff --git a/docs/SECURITY_GUIDE.md b/docs/SECURITY_GUIDE.md index e4fb239..1e5b027 100644 --- a/docs/SECURITY_GUIDE.md +++ b/docs/SECURITY_GUIDE.md @@ -1,12 +1,16 @@ # Security Documentation - AI Study Assistant +> ⚠️ **ATUALIZADO**: Este documento foi corrigido para refletir a implementaΓ§Γ£o REAL. +> +> **Nota Importante sobre Roles:** Apenas `student` e `teacher` estΓ£o implementados. Roles `admin` e `super_admin` NΓƒO existem no cΓ³digo. + ## πŸ”’ COMPREHENSIVE SECURITY FRAMEWORK --- ## πŸ“‹ OVERVIEW -This document outlines the complete security architecture, policies, and procedures for the AI Study Assistant platform, ensuring data protection, privacy compliance, and secure operations across all components. +This document outlines the security architecture for the AI Study Assistant platform. Note: This is a Flutter + Firebase BaaS application without a custom backend server. --- diff --git a/docs/TESTING_STRATEGY.md b/docs/TESTING_STRATEGY.md index c2e82c4..0511758 100644 --- a/docs/TESTING_STRATEGY.md +++ b/docs/TESTING_STRATEGY.md @@ -1,12 +1,16 @@ # Testing Strategy - AI Study Assistant -## πŸ§ͺ COMPREHENSIVE TESTING APPROACH +> ⚠️ **ATUALIZADO**: Este documento foi corrigido para refletir a arquitetura REAL. +> +> **Nota:** O projeto Γ© Flutter + Firebase BaaS. NΓ£o existe backend Node.js/Python para testar. + +## πŸ§ͺ TESTING APPROACH --- ## πŸ“‹ OVERVIEW -This document outlines the complete testing strategy for the AI Study Assistant project, covering unit tests, integration tests, widget tests, end-to-end tests, performance testing, and quality assurance processes. +This document outlines the testing strategy for the AI Study Assistant project (Flutter + Firebase BaaS). Testing focuses on Flutter unit/widget tests and Firebase security rules. There is no custom backend to test. ---