Merge branch 'main' of https://gitea.epvc.pt/240405/TeachIT
This commit is contained in:
@@ -1,6 +1,8 @@
|
|||||||
# Architecture Overview - AI Study Assistant
|
# 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
|
## 🏛️ HIGH-LEVEL ARCHITECTURE
|
||||||
|
|
||||||
### System Overview
|
### System Overview (Real Implementation)
|
||||||
```
|
```
|
||||||
┌─────────────────────────────────────────────────────────────────┐
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
│ PRESENTATION LAYER │
|
│ PRESENTATION LAYER │
|
||||||
├─────────────────┬─────────────────┬─────────────────────────────┤
|
├─────────────────┬─────────────────┬─────────────────────────────┤
|
||||||
│ Flutter App │ Web App │ Admin Dashboard │
|
│ Flutter App │ Web App │ (Same codebase) │
|
||||||
│ (Mobile/Web) │ (PWA) │ (Management) │
|
│ (Mobile/Web) │ (Flutter Web) │ │
|
||||||
└─────────────────┴─────────────────┴─────────────────────────────┘
|
└─────────────────┴─────────────────┴─────────────────────────────┘
|
||||||
│
|
│
|
||||||
▼
|
▼
|
||||||
┌─────────────────────────────────────────────────────────────────┐
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
│ API GATEWAY │
|
│ FLUTTER SERVICES │
|
||||||
│ • Authentication • Rate Limiting • Load Balancing │
|
|
||||||
└─────────────────────────────────────────────────────────────────┘
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
┌─────────────────────────────────────────────────────────────────┐
|
|
||||||
│ SERVICE LAYER │
|
|
||||||
├─────────────┬─────────────┬─────────────┬───────────────────────┤
|
├─────────────┬─────────────┬─────────────┬───────────────────────┤
|
||||||
│ Auth │ Tutor │ Quiz │ Analytics │
|
│ Auth │ Tutor │ Quiz │ Gamification │
|
||||||
│ Service │ Service │ Service │ Service │
|
│ Service │ Service │ Service │ Service │
|
||||||
|
├─────────────┼─────────────┼─────────────┼───────────────────────┤
|
||||||
|
│ RAG │ Chat │ Content │ Vector │
|
||||||
|
│ Service │ Memory │ Service │ Service (Mock) │
|
||||||
└─────────────┴─────────────┴─────────────┴───────────────────────┘
|
└─────────────┴─────────────┴─────────────┴───────────────────────┘
|
||||||
│
|
│
|
||||||
▼
|
▼
|
||||||
┌─────────────────────────────────────────────────────────────────┐
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
│ AI/ML LAYER │
|
│ EXTERNAL SERVICES │
|
||||||
├─────────────┬─────────────┬─────────────┬───────────────────────┤
|
├─────────────────────────┬─────────────────────────────────────┤
|
||||||
│ RAG │ Embedding │ LLM │ Vector Store │
|
│ Firebase │ Ollama LLM │
|
||||||
│ Engine │ Service │ Service │ (FAISS) │
|
│ • Auth │ • Model: qwen3-coder:30b │
|
||||||
└─────────────┴─────────────┴─────────────┴───────────────────────┘
|
│ • Firestore │ • Endpoint: /api/chat │
|
||||||
│
|
│ • Storage │ │
|
||||||
▼
|
│ • Analytics │ │
|
||||||
┌─────────────────────────────────────────────────────────────────┐
|
│ • Crashlytics │ │
|
||||||
│ DATA LAYER │
|
└─────────────────────────┴─────────────────────────────────────┘
|
||||||
├─────────────┬─────────────┬─────────────┬───────────────────────┤
|
|
||||||
│ Firestore │ Storage │ Cache │ Search │
|
|
||||||
│ Database │ (Files) │ (Redis) │ (Elasticsearch) │
|
|
||||||
└─────────────┴─────────────┴─────────────┴───────────────────────┘
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### 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
|
## 📱 FRONTEND ARCHITECTURE
|
||||||
@@ -187,7 +188,14 @@ class TutorRepositoryImpl implements TutorRepository {
|
|||||||
|
|
||||||
## ⚡ BACKEND ARCHITECTURE
|
## ⚡ 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 │
|
│ API GATEWAY LAYER │
|
||||||
@@ -198,6 +206,8 @@ class TutorRepositoryImpl implements TutorRepository {
|
|||||||
│ • CORS │ • Schema Valid │ • Per-Endpoint Limits │
|
│ • CORS │ • Schema Valid │ • Per-Endpoint Limits │
|
||||||
│ • Logging │ • Sanitization │ • Global Limits │
|
│ • Logging │ • Sanitization │ • Global Limits │
|
||||||
│ • Error Handl │ • Type Check │ • Burst Protection │
|
│ • 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 │
|
│ Text Input │ Content │ Query Processing │
|
||||||
│ Processing │ Processing │ │
|
│ Processing │ Processing │ │
|
||||||
│ │ │ │
|
│ │ │ │
|
||||||
│ • Tokenization │ • PDF Parsing │ • Query Embedding │
|
│ • Text Cleaning │ • PDF Parsing │ • Keyword Extraction │
|
||||||
│ • Cleaning │ • Text Extract │ • Vector Search │
|
│ • LaTeX Filter │ • Text Extract │ • Window Search │
|
||||||
│ • Normalization │ • Chunking │ • Similarity Calculation │
|
│ • Normalization │ • Chunking │ • Similarity Matching │
|
||||||
│ • Validation │ • Metadata │ • Ranking │
|
│ • Validation │ • Cache (Hive) │ • Content Ranking │
|
||||||
└─────────────────┴─────────────────┴─────────────────────────────┘
|
└─────────────────┴─────────────────┴─────────────────────────────┘
|
||||||
│
|
│
|
||||||
▼
|
▼
|
||||||
┌─────────────────────────────────────────────────────────────────┐
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
│ VECTOR STORE │
|
│ VECTOR STORE (Mock/Simple) │
|
||||||
├─────────────────┬─────────────────┬─────────────────────────────┤
|
├─────────────────┬─────────────────┬─────────────────────────────┤
|
||||||
│ Indexing │ Storage │ Retrieval │
|
│ Embeddings │ Storage │ Retrieval │
|
||||||
│ │ │ │
|
│ │ │ │
|
||||||
│ • FAISS Index │ • Vector Data │ • Approximate Search │
|
│ • Hash-based │ • Firestore │ • Cosine Similarity │
|
||||||
│ • HNSW Tree │ • Metadata │ • Exact Search │
|
│ • 384 dims │ • contentChunks │ • Keyword Matching │
|
||||||
│ • IVF Clusters │ • Chunks │ • Hybrid Search │
|
│ • Deterministic │ • materials │ • Window-based Search │
|
||||||
│ • Optimization │ • Updates │ • Filtering │
|
│ • Fast/Cheap │ • No FAISS │ • No Approximate Search │
|
||||||
└─────────────────┴─────────────────┴─────────────────────────────┘
|
└─────────────────┴─────────────────┴─────────────────────────────┘
|
||||||
│
|
│
|
||||||
▼
|
▼
|
||||||
@@ -309,107 +319,124 @@ export class TutorService {
|
|||||||
│ Prompt │ Generation │ Post-Processing │
|
│ Prompt │ Generation │ Post-Processing │
|
||||||
│ Engineering │ │ │
|
│ Engineering │ │ │
|
||||||
│ │ │ │
|
│ │ │ │
|
||||||
│ • Context Build │ • OpenAI API │ • Response Validation │
|
│ • Context Embed │ • Ollama API │ • UTF-8 Encoding │
|
||||||
│ • Template │ • Anthropic API│ • Safety Checks │
|
│ • User Persona │ • qwen3-coder │ • Response Formatting │
|
||||||
│ • Formatting │ • Model Selection│ • Quality Assessment │
|
│ • PDF Content │ • 30B model │ • Citation Handling │
|
||||||
│ • Safety │ • Rate Limit │ • Caching │
|
│ • Constraints │ • Direct HTTP │ • Error Handling │
|
||||||
└─────────────────┴─────────────────┴─────────────────────────────┘
|
└─────────────────┴─────────────────┴─────────────────────────────┘
|
||||||
```
|
```
|
||||||
|
|
||||||
### RAG Pipeline Implementation
|
### RAG Pipeline Implementation (Dart)
|
||||||
```python
|
```dart
|
||||||
# RAG Engine Pipeline
|
// Real implementation in lib/core/services/rag_ai_service.dart
|
||||||
class RAGPipeline:
|
class RAGAIService {
|
||||||
def __init__(self):
|
static const String _baseUrl = 'http://89.114.196.110:11434/api/chat';
|
||||||
self.embedding_service = EmbeddingService()
|
static const String _model = 'qwen3-coder:30b';
|
||||||
self.vector_store = VectorStore()
|
|
||||||
self.llm_service = LLMService()
|
static Future<String> askTutor({
|
||||||
self.prompt_builder = PromptBuilder()
|
required String question,
|
||||||
|
required List<String> materialIds,
|
||||||
async def process_query(self, query: str, mode: str = "EXPLANATION") -> str:
|
required String mode,
|
||||||
# Step 1: Process input
|
}) async {
|
||||||
processed_query = self.preprocess_query(query)
|
// Step 1: Retrieve context from materials (keyword-based)
|
||||||
|
final context = await MaterialsRAGService.getContextForQuestion(
|
||||||
# Step 2: Generate embedding
|
question: question,
|
||||||
query_embedding = await self.embedding_service.encode([processed_query])
|
materialIds: materialIds,
|
||||||
|
);
|
||||||
# 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
|
|
||||||
|
|
||||||
def preprocess_query(self, query: str) -> str:
|
// Step 2: Build prompt with embedded context
|
||||||
# Clean and normalize query
|
final prompt = _buildPrompt(
|
||||||
query = query.strip().lower()
|
question: question,
|
||||||
# Remove special characters
|
context: context,
|
||||||
query = re.sub(r'[^\w\s]', '', query)
|
mode: mode,
|
||||||
# Tokenize and normalize
|
);
|
||||||
return query
|
|
||||||
|
|
||||||
def get_filters(self, mode: str) -> Dict[str, Any]:
|
// Step 3: Call Ollama API directly
|
||||||
# Mode-specific filtering
|
final response = await http.post(
|
||||||
filters = {}
|
Uri.parse(_baseUrl),
|
||||||
if mode == "EXPLANATION":
|
headers: {'Content-Type': 'application/json; charset=utf-8'},
|
||||||
filters["content_type"] = ["explanation", "definition"]
|
body: utf8.encode(jsonEncode({
|
||||||
elif mode == "TUTOR":
|
'model': _model,
|
||||||
filters["difficulty"] = {"$lte": 0.7}
|
'messages': [
|
||||||
return filters
|
{'role': 'system', 'content': _systemPrompt},
|
||||||
|
{'role': 'user', 'content': prompt},
|
||||||
|
],
|
||||||
|
})),
|
||||||
|
);
|
||||||
|
|
||||||
|
// Step 4: Process response
|
||||||
|
return _processResponse(response);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// MaterialsRAGService - keyword window search
|
||||||
|
class MaterialsRAGService {
|
||||||
|
static Future<String> getContextForQuestion({
|
||||||
|
required String question,
|
||||||
|
required List<String> 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
|
## 🗄️ DATA ARCHITECTURE
|
||||||
|
|
||||||
### Database Schema
|
### Database Schema (Actual Implementation)
|
||||||
```
|
```
|
||||||
┌─────────────────────────────────────────────────────────────────┐
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
│ FIRESTORE DATABASE │
|
│ FIRESTORE DATABASE │
|
||||||
├─────────────────┬─────────────────┬─────────────────────────────┤
|
├─────────────────┬─────────────────┬─────────────────────────────┤
|
||||||
│ USERS │ CONTENT │ LEARNING │
|
│ USERS │ MATERIALS │ CONTENTCHUNKS │
|
||||||
│ │ │ │
|
│ │ │ │
|
||||||
│ • uid │ • id │ • studentId │
|
│ • uid │ • id │ • id │
|
||||||
│ • email │ • title │ • concept │
|
│ • email │ • teacherId │ • text │
|
||||||
│ • role │ • subject │ • mastery │
|
│ • role │ • fileName │ • subject │
|
||||||
│ • schoolId │ • concept │ • confidence │
|
│ • schoolId │ • fileUrl │ • concept │
|
||||||
│ • profile │ • difficulty │ • lastInteraction │
|
│ • displayName │ • type │ • embedding (List<double>) │
|
||||||
│ • preferences │ • grade │ • interactions │
|
│ • createdAt │ • createdAt │ • metadata │
|
||||||
│ • createdAt │ • uploadedAt │ • recommendations │
|
│ │ │ • createdAt │
|
||||||
│ • lastActive │ • uploadedBy │ • spacedRepetition │
|
|
||||||
└─────────────────┴─────────────────┴─────────────────────────────┘
|
└─────────────────┴─────────────────┴─────────────────────────────┘
|
||||||
│
|
│
|
||||||
▼
|
▼
|
||||||
┌─────────────────┬─────────────────┬─────────────────────────────┐
|
┌─────────────────┬─────────────────┬─────────────────────────────┐
|
||||||
│ QUIZ │ INTERACTIONS │ SCHOOLS │
|
│ QUIZZES │ CONVERSATIONS │ CLASSES/ENROLLMENTS │
|
||||||
│ │ │ │
|
│ │ (userChats/*) │ │
|
||||||
│ • id │ • id │ • id │
|
│ • id │ │ • id │
|
||||||
│ • title │ • studentId │ • name │
|
│ • teacherId │ • id │ • teacherId/classId │
|
||||||
│ • subject │ • query │ • email │
|
│ • title │ • title │ • name/code │
|
||||||
│ • concept │ • response │ • settings │
|
│ • description │ • selectedMaterials│ • studentId │
|
||||||
│ • questions │ • mode │ • subscription │
|
│ • questions │ • createdAt │ • createdAt/joinedAt │
|
||||||
│ • timeLimit │ • timestamp │ • maxStudents │
|
│ • createdAt │ • hasUserMessage│ │
|
||||||
│ • passingScore │ • feedback │ • maxTeachers │
|
│ │ • messages/* │ │
|
||||||
│ • createdBy │ • metadata │ • isActive │
|
|
||||||
│ • createdAt │ • sources │ • createdAt │
|
|
||||||
└─────────────────┴─────────────────┴─────────────────────────────┘
|
└─────────────────┴─────────────────┴─────────────────────────────┘
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### 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
|
### Data Flow Architecture
|
||||||
```
|
```
|
||||||
┌─────────────────────────────────────────────────────────────────┐
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
@@ -524,88 +551,84 @@ class RAGPipeline:
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🔧 TECHNOLOGY STACK
|
## 🔧 TECHNOLOGY STACK (ACTUAL)
|
||||||
|
|
||||||
### Frontend Technologies
|
### Frontend Technologies
|
||||||
```yaml
|
```yaml
|
||||||
Flutter Framework:
|
Flutter Framework:
|
||||||
- SDK: 3.41.0+
|
- SDK: ^3.11.5 (Dart 3.0+)
|
||||||
- Language: Dart 3.0+
|
- Language: Dart 3.0+
|
||||||
- State Management: Riverpod 2.4.9
|
- State Management: Riverpod 2.4.9
|
||||||
- Navigation: GoRouter 12.1.3
|
- Navigation: GoRouter 12.1.3
|
||||||
- UI: Material Design 3
|
- UI: Material Design 3
|
||||||
- Testing: Flutter Test, Integration Test
|
- Testing: Flutter Test, Integration Test (not implemented)
|
||||||
|
|
||||||
Firebase Services:
|
Firebase Services:
|
||||||
- Authentication: Firebase Auth
|
- Authentication: firebase_auth ^4.17.8
|
||||||
- Database: Cloud Firestore
|
- Database: cloud_firestore ^4.15.8
|
||||||
- Storage: Firebase Storage
|
- Storage: firebase_storage ^11.6.9
|
||||||
- Analytics: Firebase Analytics
|
- Analytics: firebase_analytics ^10.8.0
|
||||||
- Crashlytics: Firebase Crashlytics
|
- Crashlytics: firebase_crashlytics ^3.5.7
|
||||||
- Performance: Firebase Performance
|
- Messaging: firebase_messaging ^14.9.3
|
||||||
|
- Performance: NOT IMPLEMENTED
|
||||||
|
- Remote Config: NOT IMPLEMENTED
|
||||||
|
|
||||||
Third-Party Libraries:
|
Third-Party Libraries:
|
||||||
- HTTP: Dio 5.4.0
|
- HTTP: Dio ^5.4.0, http ^1.1.2
|
||||||
- Caching: Cached Network Image 3.3.0
|
- PDF Processing: syncfusion_flutter_pdf ^33.2.6
|
||||||
- Fonts: Google Fonts 6.1.0
|
- Caching: cached_network_image ^3.3.0, hive ^2.2.3
|
||||||
- Animations: Flutter Animate 4.2.0
|
- Fonts: google_fonts ^6.1.0
|
||||||
- Local Storage: Hive 2.2.3
|
- 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
|
```yaml
|
||||||
Runtime Environment:
|
Status: NO BACKEND SERVER
|
||||||
- Platform: Firebase Cloud Functions
|
|
||||||
- Runtime: Node.js 18.x LTS
|
|
||||||
- Language: TypeScript 5.0+
|
|
||||||
- Package Manager: npm 9.x
|
|
||||||
|
|
||||||
Core Services:
|
The following technologies are documented but NOT implemented:
|
||||||
- Authentication: Firebase Admin SDK
|
❌ Firebase Cloud Functions - Not used
|
||||||
- Database: Firestore Admin SDK
|
❌ Node.js / TypeScript - Not used
|
||||||
- Storage: Cloud Storage Admin SDK
|
❌ Python RAG Engine - Not used
|
||||||
- HTTP Framework: Express.js 4.18+
|
❌ FAISS Vector Database - Not used
|
||||||
- Validation: Joi 17.9+
|
❌ Sentence Transformers - Not used
|
||||||
- Security: Helmet 7.0+
|
❌ OpenAI API - Not used
|
||||||
|
❌ Anthropic Claude - Not used
|
||||||
|
|
||||||
AI/ML Services:
|
Actual Implementation:
|
||||||
- Vector Database: FAISS 1.7.4
|
✅ Flutter app calls Ollama directly via HTTP
|
||||||
- Embeddings: Sentence Transformers 2.2.2
|
✅ Firebase services handle auth, database, storage
|
||||||
- LLM APIs: OpenAI 4.20.1, Anthropic 0.6.3
|
✅ RAG logic implemented in Dart (keyword matching)
|
||||||
- Processing: NumPy 1.21+, PyTorch 1.12+
|
✅ Embeddings: Mock/hash-based in Dart
|
||||||
|
|
||||||
Monitoring & Logging:
|
|
||||||
- Logging: Winston 3.8+
|
|
||||||
- Metrics: Prometheus Client
|
|
||||||
- Tracing: OpenTelemetry
|
|
||||||
- Error Tracking: Sentry
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Infrastructure Technologies
|
### Infrastructure Technologies
|
||||||
```yaml
|
```yaml
|
||||||
Cloud Platform:
|
Cloud Platform:
|
||||||
- Provider: Google Cloud Platform
|
- Provider: Google Firebase (BaaS)
|
||||||
- Services: Firebase, Cloud Functions, Cloud Storage
|
- Services: Firebase Auth, Firestore, Storage
|
||||||
- Regions: us-central1, europe-west1
|
- Hosting: Firebase Hosting (for web builds)
|
||||||
- CDN: Firebase Hosting
|
- Self-hosted: Ollama LLM server (89.114.196.110:11434)
|
||||||
|
|
||||||
Database:
|
Database:
|
||||||
- Primary: Cloud Firestore
|
- Primary: Cloud Firestore (NoSQL)
|
||||||
- Cache: Redis (MemoryStore)
|
- Cache: Hive (local), Memory cache
|
||||||
- Search: Elasticsearch (if needed)
|
- Search: Not implemented (no Elasticsearch)
|
||||||
- Backup: Automated daily backups
|
- Backup: Firebase automated backups
|
||||||
|
|
||||||
Security:
|
Security:
|
||||||
- TLS: 1.3
|
- TLS: HTTPS for all communications
|
||||||
- Authentication: Firebase Auth
|
- Authentication: Firebase Auth (email/password, Google)
|
||||||
- Authorization: Custom RBAC
|
- Authorization: Client-side role checks (student/teacher)
|
||||||
- Monitoring: Security Command Center
|
- Note: No admin role implemented
|
||||||
|
|
||||||
CI/CD:
|
CI/CD:
|
||||||
- Pipeline: GitHub Actions
|
- Pipeline: Manual builds
|
||||||
- Build: Cloud Build
|
- Build: flutter build web/apk
|
||||||
- Deploy: Firebase CLI
|
- Deploy: Firebase CLI (manual)
|
||||||
- Testing: Automated test suites
|
- Testing: No automated tests implemented
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|||||||
@@ -1,71 +1,47 @@
|
|||||||
# Backend MVP Tasks - AI Study Assistant
|
# 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
|
## 🏗️ WEEK 1-2: FIREBASE FOUNDATION
|
||||||
|
|
||||||
### Task 1.1: Firebase Project Setup
|
### Task 1.1: Firebase Project Setup
|
||||||
**Priority**: Critical
|
**Status**: ✅ COMPLETED
|
||||||
**Estimated Time**: 6 hours
|
|
||||||
**Dependencies**: None
|
|
||||||
|
|
||||||
#### Subtasks:
|
#### Subtasks:
|
||||||
- [ ] Create Firebase project in Google Cloud Console
|
- ✅ Create Firebase project in Google Cloud Console
|
||||||
- [ ] Enable required Firebase services:
|
- ✅ Enable required Firebase services:
|
||||||
- [ ] Firebase Authentication
|
- ✅ Firebase Authentication
|
||||||
- [ ] Cloud Firestore
|
- ✅ Cloud Firestore
|
||||||
- [ ] Cloud Storage
|
- ✅ Cloud Storage
|
||||||
- [ ] Cloud Functions
|
- ❌ Cloud Functions - NOT IMPLEMENTED (not needed)
|
||||||
- [ ] Firebase Analytics
|
- ✅ Firebase Analytics
|
||||||
- [ ] Configure project settings
|
- ✅ Configure project settings
|
||||||
- [ ] Set up billing account (if needed)
|
- ✅ Enable Ollama API access (self-hosted)
|
||||||
- [ ] Enable API access for LLM services
|
|
||||||
|
|
||||||
#### Detailed Steps:
|
#### Actual Configuration:
|
||||||
|
|
||||||
1. **Create Firebase Project**
|
**pubspec.yaml dependencies:**
|
||||||
```bash
|
```yaml
|
||||||
# Using Firebase CLI
|
dependencies:
|
||||||
firebase projects create teachit-ai-assistant
|
firebase_core: ^2.25.4
|
||||||
firebase use teachit-ai-assistant
|
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**
|
**Ollama Configuration (in rag_ai_service.dart):**
|
||||||
```bash
|
```dart
|
||||||
# Enable Authentication
|
static const String _baseUrl = 'http://89.114.196.110:11434/api/chat';
|
||||||
firebase auth --enable
|
static const String _model = 'qwen3-coder:30b';
|
||||||
|
|
||||||
# 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"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|||||||
@@ -1,12 +1,16 @@
|
|||||||
# Contributing Guidelines - AI Study Assistant
|
# 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
|
## 🤝 HOW TO CONTRIBUTE
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📋 OVERVIEW
|
## 📋 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
|
### Prerequisites
|
||||||
- **Git**: Version 2.30 or higher
|
- **Git**: Version 2.30 or higher
|
||||||
- **Flutter**: Version 3.41.0+
|
- **Flutter**: Version 3.11.5+ (with Dart 3.0+)
|
||||||
- **Node.js**: Version 18.x LTS
|
|
||||||
- **Python**: Version 3.9+ (for RAG engine)
|
|
||||||
- **Firebase CLI**: Latest version
|
- **Firebase CLI**: Latest version
|
||||||
- **Code Editor**: VS Code recommended
|
- **Code Editor**: VS Code recommended
|
||||||
|
- **Note**: No Node.js or Python required (backend is Firebase BaaS)
|
||||||
|
|
||||||
### Development Environment Setup
|
### Development Environment Setup
|
||||||
1. Fork the repository
|
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
|
git clone https://github.com/YOUR_USERNAME/teachit.git
|
||||||
cd teachit
|
cd teachit
|
||||||
|
|
||||||
# Install Flutter dependencies
|
# Install Flutter dependencies only
|
||||||
flutter pub get
|
flutter pub get
|
||||||
|
|
||||||
# Install Node.js dependencies
|
# Note: No backend dependencies to install
|
||||||
cd functions && npm install && cd ..
|
# No Cloud Functions (Firebase BaaS is used)
|
||||||
|
# No Python RAG engine (implemented in Dart)
|
||||||
# Install Python dependencies
|
|
||||||
cd rag_engine && pip install -r requirements.txt && cd ..
|
|
||||||
|
|
||||||
# Run tests
|
# Run tests
|
||||||
flutter test
|
flutter test
|
||||||
npm test
|
|
||||||
pytest tests/
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|||||||
@@ -1,12 +1,18 @@
|
|||||||
# Deployment Guide - AI Study Assistant
|
# 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
|
## 📋 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
|
# Install Flutter dependencies
|
||||||
flutter pub get
|
flutter pub get
|
||||||
|
|
||||||
# Install Node.js dependencies (for functions)
|
# Note: No Node.js backend to install
|
||||||
cd functions
|
# No Cloud Functions to set up
|
||||||
npm install
|
|
||||||
|
|
||||||
# Start Firebase emulators
|
# Run Flutter app (Firebase services connect directly)
|
||||||
firebase emulators:start
|
|
||||||
|
|
||||||
# Run Flutter app
|
|
||||||
flutter run
|
flutter run
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Development Firebase Project:
|
#### Development Firebase Project:
|
||||||
- **Project ID**: `teachit-dev-12345`
|
- **Project ID**: `teachit-dev-12345`
|
||||||
- **Services**: All services enabled in test mode
|
- **Services**: Auth, Firestore, Storage, Analytics, Crashlytics
|
||||||
- **Security Rules**: Relaxed for development
|
- **Security Rules**: Relaxed for development
|
||||||
- **Emulators**: Local Firestore, Auth, Storage, Functions
|
- **Emulators**: Local Firestore, Auth, Storage (Functions not used)
|
||||||
|
|
||||||
#### Environment Variables:
|
#### Environment Variables:
|
||||||
```bash
|
```bash
|
||||||
# .env.development
|
# .env.development
|
||||||
FIREBASE_PROJECT_ID=teachit-dev-12345
|
FIREBASE_PROJECT_ID=teachit-dev-12345
|
||||||
FLUTTER_ENV=development
|
FLUTTER_ENV=development
|
||||||
API_BASE_URL=http://localhost:5001
|
OLLAMA_BASE_URL=http://89.114.196.110:11434/api/chat
|
||||||
ENABLE_LOGGING=true
|
ENABLE_LOGGING=true
|
||||||
ENABLE_DEBUG=true
|
ENABLE_DEBUG=true
|
||||||
```
|
```
|
||||||
|
|||||||
@@ -1,12 +1,16 @@
|
|||||||
# Development Setup Guide - AI Study Assistant
|
# 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
|
## 🛠️ COMPLETE DEVELOPMENT ENVIRONMENT SETUP
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📋 OVERVIEW
|
## 📋 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.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
@@ -1,12 +1,21 @@
|
|||||||
# Firebase Configuration - AI Study Assistant
|
# 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
|
## 🔥 COMPLETE FIREBASE SETUP GUIDE
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📋 OVERVIEW
|
## 📋 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
|
### 1.2 Enable Required Services
|
||||||
|
|
||||||
#### Firebase Services to Enable:
|
#### Firebase Services Actually Used:
|
||||||
- ✅ Firebase Authentication
|
- ✅ Firebase Authentication
|
||||||
- ✅ Cloud Firestore
|
- ✅ Cloud Firestore
|
||||||
- ✅ Cloud Storage
|
- ✅ Cloud Storage
|
||||||
- ✅ Cloud Functions
|
|
||||||
- ✅ Firebase Analytics
|
- ✅ Firebase Analytics
|
||||||
- ✅ Firebase Crashlytics
|
- ✅ Firebase Crashlytics
|
||||||
- ✅ Firebase Performance Monitoring
|
- ✅ Firebase Cloud Messaging
|
||||||
- ✅ Firebase Remote Config
|
|
||||||
|
#### Firebase Services NOT Used:
|
||||||
|
- ❌ Cloud Functions (not needed - logic in Flutter)
|
||||||
|
- ❌ Firebase Performance Monitoring (not implemented)
|
||||||
|
- ❌ Firebase Remote Config (not implemented)
|
||||||
|
|
||||||
#### Enable Commands:
|
#### Enable Commands:
|
||||||
```bash
|
```bash
|
||||||
@@ -53,10 +65,9 @@ firebase firestore:databases:create
|
|||||||
# Enable Storage
|
# Enable Storage
|
||||||
firebase storage:buckets:create teachit-content
|
firebase storage:buckets:create teachit-content
|
||||||
|
|
||||||
# Enable Functions
|
|
||||||
firebase functions:config:set
|
|
||||||
|
|
||||||
# Enable Analytics (automatically enabled)
|
# Enable Analytics (automatically enabled)
|
||||||
|
|
||||||
|
# Note: Cloud Functions not needed
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
@@ -105,17 +116,23 @@ firebase functions:config:set
|
|||||||
|
|
||||||
### 2.2 User Management Configuration
|
### 2.2 User Management Configuration
|
||||||
|
|
||||||
#### Custom Claims Setup:
|
#### User Roles (Only 2 implemented):
|
||||||
```javascript
|
```dart
|
||||||
// Cloud Function to set custom claims
|
// lib/core/services/auth_service.dart
|
||||||
exports.setCustomClaims = functions.auth.user().onCreate(async (user) => {
|
class AuthService {
|
||||||
const customClaims = {
|
static const String studentRole = 'student';
|
||||||
role: 'student', // Default role
|
static const String teacherRole = 'teacher';
|
||||||
schoolId: 'default',
|
// ❌ adminRole - NOT IMPLEMENTED
|
||||||
permissions: ['basic_access']
|
// ❌ superAdminRole - NOT IMPLEMENTED
|
||||||
};
|
}
|
||||||
|
```
|
||||||
await admin.auth().setCustomUserClaims(user.uid, customClaims);
|
|
||||||
|
**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`)
|
3. Choose location (e.g., `europe-west1`)
|
||||||
4. Set up security rules
|
4. Set up security rules
|
||||||
|
|
||||||
#### Database Structure:
|
#### Actual Database Structure:
|
||||||
```javascript
|
```javascript
|
||||||
// Collections Structure
|
// Collections Structure (as implemented in code)
|
||||||
schools/{schoolId}
|
|
||||||
├── users/{userId}
|
// Top-level collections:
|
||||||
├── learningStates/{studentId}
|
users/{userId} // User profiles with role
|
||||||
├── contentChunks/{chunkId}
|
schools/{schoolId} // Schools/institutions
|
||||||
├── quizzes/{quizId}
|
materials/{materialId} // Teacher uploaded content
|
||||||
├── quizAttempts/{attemptId}
|
contentChunks/{chunkId} // Text chunks with mock embeddings
|
||||||
├── interactions/{interactionId}
|
quizzes/{quizId} // Quiz definitions
|
||||||
└── auditLogs/{logId}
|
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
|
### 3.2 Security Rules
|
||||||
|
|||||||
@@ -1,5 +1,10 @@
|
|||||||
# Frontend MVP Tasks - AI Study Assistant
|
# 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)
|
## 📱 MVP FRONTEND ROADMAP (8-12 WEEKS)
|
||||||
|
|
||||||
---
|
---
|
||||||
@@ -13,50 +18,77 @@
|
|||||||
|
|
||||||
#### Subtasks:
|
#### Subtasks:
|
||||||
- [ ] Create new Flutter project: `flutter create learn_it`
|
- [ ] 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)
|
- [ ] Set up version control (Git repository)
|
||||||
- [ ] Create initial project structure
|
- [ ] Create initial project structure
|
||||||
- [ ] Configure pubspec.yaml with initial dependencies
|
- [ ] Configure pubspec.yaml with initial dependencies
|
||||||
|
|
||||||
#### Dependencies to Add:
|
#### Actual Dependencies (from pubspec.yaml):
|
||||||
```yaml
|
```yaml
|
||||||
dependencies:
|
dependencies:
|
||||||
flutter:
|
flutter:
|
||||||
sdk: flutter
|
sdk: flutter
|
||||||
|
flutter_localizations:
|
||||||
|
sdk: flutter
|
||||||
|
|
||||||
# State Management
|
# State Management
|
||||||
flutter_riverpod: ^2.4.9
|
flutter_riverpod: ^2.4.9
|
||||||
|
riverpod_annotation: ^2.3.3
|
||||||
|
|
||||||
|
# Navigation
|
||||||
|
go_router: ^12.1.3
|
||||||
|
flutter_animate: ^4.2.0+1
|
||||||
|
|
||||||
# Firebase
|
# Firebase
|
||||||
firebase_core: ^2.24.2
|
firebase_core: ^2.25.4
|
||||||
firebase_auth: ^4.15.3
|
firebase_auth: ^4.17.8
|
||||||
cloud_firestore: ^4.13.6
|
cloud_firestore: ^4.15.8
|
||||||
firebase_storage: ^11.5.6
|
firebase_storage: ^11.6.9
|
||||||
|
firebase_analytics: ^10.8.0
|
||||||
|
firebase_messaging: ^14.9.3
|
||||||
|
firebase_crashlytics: ^3.5.7
|
||||||
|
|
||||||
# UI Components
|
# UI Components
|
||||||
cupertino_icons: ^1.0.6
|
cupertino_icons: ^1.0.6
|
||||||
google_fonts: ^6.1.0
|
google_fonts: ^6.1.0
|
||||||
|
cached_network_image: ^3.3.0
|
||||||
# Navigation
|
flutter_svg: ^2.0.9
|
||||||
go_router: ^12.1.3
|
lottie: ^2.7.0
|
||||||
|
shimmer: ^3.0.0
|
||||||
|
|
||||||
# HTTP & Networking
|
# HTTP & Networking
|
||||||
http: ^1.1.2
|
|
||||||
dio: ^5.4.0
|
dio: ^5.4.0
|
||||||
|
http: ^1.1.2
|
||||||
|
connectivity_plus: ^5.0.2
|
||||||
|
|
||||||
# Local Storage
|
# Local Storage
|
||||||
shared_preferences: ^2.2.2
|
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
|
# Utilities
|
||||||
intl: ^0.19.0
|
intl: ^0.20.2
|
||||||
uuid: ^4.2.1
|
uuid: ^4.2.1
|
||||||
|
equatable: ^2.0.5
|
||||||
|
|
||||||
|
# Charts
|
||||||
|
fl_chart: ^0.64.0
|
||||||
|
|
||||||
|
# Biometrics
|
||||||
|
local_auth: ^2.1.7
|
||||||
|
|
||||||
dev_dependencies:
|
dev_dependencies:
|
||||||
flutter_test:
|
flutter_test:
|
||||||
sdk: flutter
|
sdk: flutter
|
||||||
flutter_lints: ^3.0.1
|
flutter_lints: ^3.0.1
|
||||||
mockito: ^5.4.4
|
|
||||||
build_runner: ^2.4.7
|
build_runner: ^2.4.7
|
||||||
|
mockito: ^5.4.4
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Implementation Details:
|
#### Implementation Details:
|
||||||
|
|||||||
@@ -1,12 +1,16 @@
|
|||||||
# Performance Optimization Guide - AI Study Assistant
|
# 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
|
## ⚡ COMPREHENSIVE PERFORMANCE STRATEGY
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📋 OVERVIEW
|
## 📋 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.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
@@ -6,12 +6,14 @@ Documento Completo de Especificação Técnica e
|
|||||||
Pedagógica
|
Pedagógica
|
||||||
<EFBFBD>
|
<EFBFBD>
|
||||||
<EFBFBD> PARTE 1: VISÃO E ARQUITECTURA GLOBAL
|
<EFBFBD> PARTE 1: VISÃO E ARQUITECTURA GLOBAL
|
||||||
1.1 Definição do Sistema
|
> ⚠️ **NOTA IMPORTANTE**: Este documento descreve uma visão aspiracional. A implementação REAL é: Flutter + Firebase + Ollama (sem backend Node.js/Python).
|
||||||
Este projeto é uma Plataforma de Inteligência Educacional Distribuída baseada em:
|
|
||||||
• LLMs condicionados por conhecimento institucional (não conhecimento aberto)
|
1.1 Definição do Sistema (VERSÃO REAL IMPLEMENTADA)
|
||||||
• Arquitectura RAG multi-camada (Retrieval-Augmented Generation)
|
Este projeto é uma Plataforma de Inteligência Educacional baseada em:
|
||||||
• Controlo de acesso baseado em papéis (RBAC)
|
• LLM local (Ollama qwen3-coder:30b) com materiais PDF de professores
|
||||||
• Geração adaptativa de aprendizagem (pedagogically-constrained output)
|
• 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:
|
Core Identity:
|
||||||
Institutional AI Learning Operating System
|
Institutional AI Learning Operating System
|
||||||
with controlled knowledge injection,
|
with controlled knowledge injection,
|
||||||
|
|||||||
@@ -1,16 +1,14 @@
|
|||||||
# 📊 Project Progress - AI Study Assistant
|
# 📊 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
|
## 🎯 OVERVIEW
|
||||||
|
|
||||||
|
This document tracks the overall progress of the AI Study Assistant project development (Flutter + Firebase BaaS + Ollama).
|
||||||
|
|
||||||
This document tracks the overall progress of the AI Study Assistant project development. Updated in real-time as features are implemented.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
@@ -1,43 +1,59 @@
|
|||||||
# RAG Engine MVP Tasks - AI Study Assistant
|
# 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
|
### Task 1.1: Vector Database Setup
|
||||||
**Priority**: Critical
|
**Status**: ❌ NOT IMPLEMENTED - FAISS não é utilizado
|
||||||
**Estimated Time**: 8 hours
|
|
||||||
**Dependencies**: None
|
|
||||||
|
|
||||||
#### Subtasks:
|
#### What Actually Exists:
|
||||||
- [ ] Choose vector database technology (FAISS for MVP)
|
```dart
|
||||||
- [ ] Set up development environment
|
// lib/core/services/vector_service.dart
|
||||||
- [ ] Install required dependencies
|
class VectorService {
|
||||||
- [ ] Configure storage for vector indices
|
// Mock embedding generation using text hashing
|
||||||
- [ ] Create basic vector operations
|
static List<double> generateEmbedding(String text) {
|
||||||
- [ ] Set up backup and recovery
|
final embedding = List<double>.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<String> 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
|
```bash
|
||||||
# Core dependencies
|
# These dependencies DO NOT EXIST in the project:
|
||||||
pip install faiss-cpu # or faiss-gpu for GPU acceleration
|
# ❌ pip install faiss-cpu
|
||||||
pip install sentence-transformers
|
# ❌ pip install sentence-transformers
|
||||||
pip install numpy
|
# ❌ pip install numpy
|
||||||
pip install pandas
|
# ❌ pip install nltk
|
||||||
pip install scikit-learn
|
# ❌ pip install spacy
|
||||||
|
|
||||||
# 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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Project Structure:
|
#### Project Structure:
|
||||||
|
|||||||
@@ -1,12 +1,16 @@
|
|||||||
# Security Documentation - AI Study Assistant
|
# 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
|
## 🔒 COMPREHENSIVE SECURITY FRAMEWORK
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📋 OVERVIEW
|
## 📋 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.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
@@ -1,12 +1,16 @@
|
|||||||
# Testing Strategy - AI Study Assistant
|
# 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
|
## 📋 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.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user