897 lines
49 KiB
Markdown
897 lines
49 KiB
Markdown
# Architecture Overview - AI Study Assistant
|
|
|
|
## 🏗️ 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.
|
|
|
|
---
|
|
|
|
## 📋 OVERVIEW
|
|
|
|
This document provides a comprehensive overview of the AI Study Assistant system architecture, including component interactions, data flow, technology stack, and design decisions.
|
|
|
|
---
|
|
|
|
## 🎯 ARCHITECTURE PRINCIPLES
|
|
|
|
### Core Principles
|
|
- **Modularity**: Loosely coupled, highly cohesive components
|
|
- **Scalability**: Horizontal scaling capabilities
|
|
- **Maintainability**: Clean, well-documented code
|
|
- **Security**: Defense-in-depth security approach
|
|
- **Performance**: Optimized for educational workloads
|
|
- **Accessibility**: Universal design for learning
|
|
|
|
### Design Patterns
|
|
- **Clean Architecture**: Separation of concerns
|
|
- **Microservices**: Service-oriented architecture
|
|
- **Event-Driven**: Asynchronous communication
|
|
- **CQRS**: Command Query Responsibility Segregation
|
|
- **Repository Pattern**: Data access abstraction
|
|
|
|
---
|
|
|
|
## 🏛️ HIGH-LEVEL ARCHITECTURE
|
|
|
|
### System Overview (Real Implementation)
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ PRESENTATION LAYER │
|
|
├─────────────────┬─────────────────┬─────────────────────────────┤
|
|
│ Flutter App │ Web App │ (Same codebase) │
|
|
│ (Mobile/Web) │ (Flutter Web) │ │
|
|
└─────────────────┴─────────────────┴─────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ FLUTTER SERVICES │
|
|
├─────────────┬─────────────┬─────────────┬───────────────────────┤
|
|
│ Auth │ Tutor │ Quiz │ Gamification │
|
|
│ Service │ Service │ Service │ Service │
|
|
├─────────────┼─────────────┼─────────────┼───────────────────────┤
|
|
│ RAG │ Chat │ Content │ Vector │
|
|
│ Service │ Memory │ Service │ Service (Mock) │
|
|
└─────────────┴─────────────┴─────────────┴───────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ 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
|
|
|
|
### Flutter Application Architecture
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ PRESENTATION │
|
|
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
|
│ │ Features │ │ Shared │ │ Core │ │
|
|
│ │ │ │ │ │ │ │
|
|
│ │ • Auth │ │ • Widgets │ │ • Config │ │
|
|
│ │ • Tutor │ │ • Utils │ │ • Constants │ │
|
|
│ │ • Quiz │ │ • Extensions │ │ • Errors │ │
|
|
│ │ • Analytics │ │ • Models │ │ • Network │ │
|
|
│ │ • Content │ │ • Services │ │ • Storage │ │
|
|
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ BUSINESS LOGIC │
|
|
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
|
│ │ Repositories │ │ Use Cases │ │ Entities │ │
|
|
│ │ │ │ │ │ │ │
|
|
│ │ • Auth Repo │ │ • Sign In │ │ • User │ │
|
|
│ │ • Tutor Repo │ │ • Ask Tutor │ │ • Question │ │
|
|
│ │ • Quiz Repo │ │ • Submit Quiz │ │ • Quiz │ │
|
|
│ │ • Analytics Repo│ │ • Track Progress│ │ • Progress │ │
|
|
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ DATA LAYER │
|
|
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
|
│ │ Remote │ │ Local │ │ Cache │ │
|
|
│ │ │ │ │ │ │ │
|
|
│ │ • Firebase Auth │ │ • SharedPrefs │ │ • Memory Cache │ │
|
|
│ │ • Firestore │ │ • Hive │ │ • Image Cache │ │
|
|
│ │ • Storage │ │ • Secure Storage│ │ • API Cache │ │
|
|
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Component Architecture
|
|
```dart
|
|
// Clean Architecture Layers
|
|
|
|
// Presentation Layer
|
|
class AskTutorScreen extends StatelessWidget {
|
|
@override
|
|
Widget build(BuildContext context) {
|
|
return Scaffold(
|
|
body: Consumer(
|
|
builder: (context, ref, child) {
|
|
final tutorState = ref.watch(tutorProvider);
|
|
|
|
return AskTutorView(
|
|
state: tutorState,
|
|
onAskQuestion: (question) =>
|
|
ref.read(tutorProvider.notifier).askQuestion(question),
|
|
);
|
|
},
|
|
),
|
|
);
|
|
}
|
|
}
|
|
|
|
// Business Logic Layer
|
|
class AskTutorUseCase {
|
|
final TutorRepository _repository;
|
|
|
|
AskTutorUseCase(this._repository);
|
|
|
|
Future<Either<Failure, TutorResponse>> call(TutorRequest request) async {
|
|
try {
|
|
final response = await _repository.askTutor(request);
|
|
return Right(response);
|
|
} catch (e) {
|
|
return Left(ServerFailure(e.toString()));
|
|
}
|
|
}
|
|
}
|
|
|
|
// Data Layer
|
|
class TutorRepositoryImpl implements TutorRepository {
|
|
final TutorRemoteDataSource _remoteDataSource;
|
|
final TutorLocalDataSource _localDataSource;
|
|
|
|
TutorRepositoryImpl(
|
|
this._remoteDataSource,
|
|
this._localDataSource,
|
|
);
|
|
|
|
@override
|
|
Future<TutorResponse> askTutor(TutorRequest request) async {
|
|
// Cache check
|
|
final cached = await _localDataSource.getCachedResponse(request);
|
|
if (cached != null) return cached;
|
|
|
|
// Remote call
|
|
final response = await _remoteDataSource.askTutor(request);
|
|
|
|
// Cache response
|
|
await _localDataSource.cacheResponse(request, response);
|
|
|
|
return response;
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## ⚡ BACKEND 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 │
|
|
├─────────────────┬─────────────────┬─────────────────────────────┤
|
|
│ Middleware │ Validation │ Rate Limiting │
|
|
│ │ │ │
|
|
│ • Auth │ • Input Check │ • Per-User Limits │
|
|
│ • 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.
|
|
└─────────────────┴─────────────────┴─────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ SERVICE LAYER │
|
|
├─────────────┬─────────────┬─────────────┬───────────────────────┤
|
|
│ Auth │ Tutor │ Quiz │ Analytics │
|
|
│ Service │ Service │ Service │ Service │
|
|
│ │ │ │ │
|
|
│ • Sign Up │ • Ask Tutor │ • Create │ • Track Progress │
|
|
│ • Sign In │ • Get History│ • Submit │ • Generate Reports │
|
|
│ • Validate │ • Feedback │ • Grade │ • Calculate Mastery │
|
|
│ • Refresh │ • Rate Limit│ • Analytics │ • Recommendations │
|
|
└─────────────┴─────────────┴─────────────┴───────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ INTEGRATION LAYER │
|
|
├─────────────┬─────────────┬─────────────┬───────────────────────┤
|
|
│ Database │ Storage │ Cache │ External APIs │
|
|
│ Service │ Service │ Service │ │
|
|
│ │ │ │ │
|
|
│ • Firestore │ • File Upload│ • Redis │ • OpenAI │
|
|
│ • Queries │ • Download │ • MemCache │ • Anthropic │
|
|
│ • Transactions│ • Metadata │ • Session │ • Monitoring │
|
|
│ • Indexing │ • Security │ • Cache │ • Analytics │
|
|
└─────────────┴─────────────┴─────────────┴───────────────────────┘
|
|
```
|
|
|
|
### Service Architecture
|
|
```typescript
|
|
// Service Layer Structure
|
|
export class TutorService {
|
|
constructor(
|
|
private ragService: RAGService,
|
|
private llmService: LLMService,
|
|
private cacheService: CacheService,
|
|
private analyticsService: AnalyticsService,
|
|
) {}
|
|
|
|
async askTutor(request: TutorRequest): Promise<TutorResponse> {
|
|
// 1. Validate request
|
|
await this.validateRequest(request);
|
|
|
|
// 2. Check cache
|
|
const cached = await this.cacheService.get(request);
|
|
if (cached) return cached;
|
|
|
|
// 3. Process with RAG
|
|
const context = await this.ragService.retrieveContext(request.query);
|
|
|
|
// 4. Generate response with LLM
|
|
const response = await this.llmService.generateResponse({
|
|
query: request.query,
|
|
context: context,
|
|
mode: request.mode,
|
|
});
|
|
|
|
// 5. Cache response
|
|
await this.cacheService.set(request, response);
|
|
|
|
// 6. Track analytics
|
|
await this.analyticsService.trackInteraction({
|
|
userId: request.userId,
|
|
query: request.query,
|
|
response: response,
|
|
mode: request.mode,
|
|
});
|
|
|
|
return response;
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 🤖 AI/ML ARCHITECTURE (DART IMPLEMENTATION)
|
|
|
|
### RAG Engine Architecture (Real Implementation)
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ INPUT PROCESSING (Dart) │
|
|
├─────────────────┬─────────────────┬─────────────────────────────┤
|
|
│ Text Input │ Content │ Query Processing │
|
|
│ Processing │ Processing │ │
|
|
│ │ │ │
|
|
│ • Text Cleaning │ • PDF Parsing │ • Keyword Extraction │
|
|
│ • LaTeX Filter │ • Text Extract │ • Window Search │
|
|
│ • Normalization │ • Chunking │ • Similarity Matching │
|
|
│ • Validation │ • Cache (Hive) │ • Content Ranking │
|
|
└─────────────────┴─────────────────┴─────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ VECTOR STORE (Mock/Simple) │
|
|
├─────────────────┬─────────────────┬─────────────────────────────┤
|
|
│ Embeddings │ Storage │ Retrieval │
|
|
│ │ │ │
|
|
│ • Hash-based │ • Firestore │ • Cosine Similarity │
|
|
│ • 384 dims │ • contentChunks │ • Keyword Matching │
|
|
│ • Deterministic │ • materials │ • Window-based Search │
|
|
│ • Fast/Cheap │ • No FAISS │ • No Approximate Search │
|
|
└─────────────────┴─────────────────┴─────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ LLM INTEGRATION │
|
|
├─────────────────┬─────────────────┬─────────────────────────────┤
|
|
│ Prompt │ Generation │ Post-Processing │
|
|
│ Engineering │ │ │
|
|
│ │ │ │
|
|
│ • 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 (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<String> askTutor({
|
|
required String question,
|
|
required List<String> materialIds,
|
|
required String mode,
|
|
}) async {
|
|
// Step 1: Retrieve context from materials (keyword-based)
|
|
final context = await MaterialsRAGService.getContextForQuestion(
|
|
question: question,
|
|
materialIds: materialIds,
|
|
);
|
|
|
|
// Step 2: Build prompt with embedded context
|
|
final prompt = _buildPrompt(
|
|
question: question,
|
|
context: context,
|
|
mode: mode,
|
|
);
|
|
|
|
// 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<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
|
|
|
|
### Database Schema (Actual Implementation)
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ FIRESTORE DATABASE │
|
|
├─────────────────┬─────────────────┬─────────────────────────────┤
|
|
│ USERS │ MATERIALS │ CONTENTCHUNKS │
|
|
│ │ │ │
|
|
│ • uid │ • id │ • id │
|
|
│ • email │ • teacherId │ • text │
|
|
│ • role │ • fileName │ • subject │
|
|
│ • schoolId │ • fileUrl │ • concept │
|
|
│ • displayName │ • type │ • embedding (List<double>) │
|
|
│ • createdAt │ • createdAt │ • metadata │
|
|
│ │ │ • 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
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ DATA FLOW PATTERNS │
|
|
├─────────────────┬─────────────────┬─────────────────────────────┤
|
|
│ Write Path │ Read Path │ Analytics Path │
|
|
│ │ │ │
|
|
│ 1. User Action │ 1. Cache Check │ 1. Event Capture │
|
|
│ 2. Validation │ 2. DB Query │ 2. Stream Processing │
|
|
│ 3. DB Write │ 3. Cache Update│ 3. Aggregation │
|
|
│ 4. Cache Update │ 4. Response │ 4. Storage │
|
|
│ 5. Event Emit │ 5. Analytics │ 5. Dashboard Update │
|
|
└─────────────────┴─────────────────┴─────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 🔐 SECURITY ARCHITECTURE
|
|
|
|
### Security Layers
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ SECURITY LAYERS │
|
|
├─────────────────┬─────────────────┬─────────────────────────────┤
|
|
│ Network │ Application │ Data │
|
|
│ │ │ │
|
|
│ • HTTPS/TLS │ • Authentication│ • Encryption at Rest │
|
|
│ • CORS Policy │ • Authorization│ • Field-Level Encryption │
|
|
│ • Rate Limiting │ • Input Validation│ • Access Control │
|
|
│ • DDoS Protection│ • Output Encoding│ • Audit Logging │
|
|
│ • VPN Access │ • Session Mgmt │ • Data Retention │
|
|
└─────────────────┴─────────────────┴─────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ COMPLIANCE LAYER │
|
|
├─────────────────┬─────────────────┬─────────────────────────────┤
|
|
│ GDPR │ FERPA │ Educational Standards │
|
|
│ │ │ │
|
|
│ • Data Consent │ • Directory Info│ • Accessibility │
|
|
│ • Right to Access│ • Educational │ • Privacy by Design │
|
|
│ • Data Portability│ Records │ • Age Appropriateness │
|
|
│ • Right to Erasure│ • Parent Access│ • Content Filtering │
|
|
└─────────────────┴─────────────────┴─────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 🚀 DEPLOYMENT ARCHITECTURE
|
|
|
|
### Infrastructure Architecture
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ INFRASTRUCTURE │
|
|
├─────────────────┬─────────────────┬─────────────────────────────┤
|
|
│ Frontend │ Backend │ AI/ML │
|
|
│ │ │ │
|
|
│ • Firebase Host │ • Cloud Functions│ • Vector Database │
|
|
│ • CDN │ • Auto Scaling │ • Model Servers │
|
|
│ • Edge Caching │ • Load Balancer │ • GPU Resources │
|
|
│ • SSL/TLS │ • Monitoring │ • Model Caching │
|
|
│ • CI/CD │ • Logging │ • Batch Processing │
|
|
└─────────────────┴─────────────────┴─────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ MONITORING & LOGGING │
|
|
├─────────────────┬─────────────────┬─────────────────────────────┤
|
|
│ Application │ Infrastructure│ Security │
|
|
│ │ │ │
|
|
│ • Error Tracking │ • Resource Usage│ • Threat Detection │
|
|
│ • Performance │ • Uptime │ • Access Logs │
|
|
│ • User Analytics │ • Health Checks│ • Vulnerability Scanning │
|
|
│ • A/B Testing │ • Alerts │ • Compliance Monitoring │
|
|
│ • Feature Flags │ • Metrics │ • Audit Trails │
|
|
└─────────────────┴─────────────────┴─────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 📊 SCALABILITY ARCHITECTURE
|
|
|
|
### Horizontal Scaling Strategy
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ SCALING PATTERNS │
|
|
├─────────────────┬─────────────────┬─────────────────────────────┤
|
|
│ Database │ Application │ AI/ML │
|
|
│ │ │ │
|
|
│ • Sharding │ • Load Balancer│ • Model Sharding │
|
|
│ • Replication │ • Auto Scaling │ • Distributed Inference │
|
|
│ • Caching │ • Microservices│ • Batch Queues │
|
|
│ • Read Replicas │ • Containerization│ • GPU Pooling │
|
|
│ • Connection Pool│ • Serverless │ • Model Versioning │
|
|
└─────────────────┴─────────────────┴─────────────────────────────┘
|
|
```
|
|
|
|
### Performance Optimization
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ PERFORMANCE LAYERS │
|
|
├─────────────────┬─────────────────┬─────────────────────────────┤
|
|
│ Frontend │ Backend │ Database │
|
|
│ │ │ │
|
|
│ • Lazy Loading │ • Caching │ • Indexing │
|
|
│ • Code Splitting│ • Connection Pool│ • Query Optimization │
|
|
│ • Image Opt │ • Batch Ops │ • Data Compression │
|
|
│ • Memory Mgmt │ • Async Processing│ • Partitioning │
|
|
│ • Bundle Size │ • Rate Limiting │ • Caching Strategy │
|
|
└─────────────────┴─────────────────┴─────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 🔧 TECHNOLOGY STACK (ACTUAL)
|
|
|
|
### Frontend Technologies
|
|
```yaml
|
|
Flutter Framework:
|
|
- 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 (not implemented)
|
|
|
|
Firebase Services:
|
|
- 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, 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 (NOT IMPLEMENTED)
|
|
```yaml
|
|
Status: NO BACKEND SERVER
|
|
|
|
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
|
|
|
|
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 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 (NoSQL)
|
|
- Cache: Hive (local), Memory cache
|
|
- Search: Not implemented (no Elasticsearch)
|
|
- Backup: Firebase automated backups
|
|
|
|
Security:
|
|
- 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: Manual builds
|
|
- Build: flutter build web/apk
|
|
- Deploy: Firebase CLI (manual)
|
|
- Testing: No automated tests implemented
|
|
```
|
|
|
|
---
|
|
|
|
## 🔄 INTEGRATION PATTERNS
|
|
|
|
### Service Communication
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ COMMUNICATION PATTERNS │
|
|
├─────────────────┬─────────────────┬─────────────────────────────┤
|
|
│ Synchronous │ Asynchronous │ Event-Driven │
|
|
│ │ │ │
|
|
│ • HTTP/REST │ • Message Queue │ • Event Streaming │
|
|
│ • GraphQL │ • Pub/Sub │ • CQRS │
|
|
│ • gRPC │ • Background Jobs│ • Event Sourcing │
|
|
│ • WebSocket │ • Worker Threads│ • Saga Pattern │
|
|
│ • API Gateway │ • Batch Processing│ • Domain Events │
|
|
└─────────────────┴─────────────────┴─────────────────────────────┘
|
|
```
|
|
|
|
### Data Integration
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ DATA INTEGRATION │
|
|
├─────────────────┬─────────────────┬─────────────────────────────┤
|
|
│ Real-time │ Batch │ Hybrid │
|
|
│ │ │ │
|
|
│ • Firestore │ • Cloud Storage │ • Stream Processing │
|
|
│ • Realtime DB │ • BigQuery │ • Lambda Architecture │
|
|
│ • WebSocket │ • Dataflow │ • Change Data Capture │
|
|
│ • Pub/Sub │ • Cloud Functions│ • Event-Driven Updates │
|
|
│ • Webhooks │ • Scheduled Jobs│ • Reactive Programming │
|
|
└─────────────────┴─────────────────┴─────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 🎯 DESIGN DECISIONS
|
|
|
|
### Architectural Decisions
|
|
|
|
#### 1. Clean Architecture
|
|
**Decision**: Adopt Clean Architecture principles
|
|
**Rationale**:
|
|
- Separation of concerns
|
|
- Testability
|
|
- Maintainability
|
|
- Framework independence
|
|
|
|
#### 2. Microservices Architecture
|
|
**Decision**: Use microservices for backend
|
|
**Rationale**:
|
|
- Independent scaling
|
|
- Technology diversity
|
|
- Fault isolation
|
|
- Team autonomy
|
|
|
|
#### 3. Firebase as Backend
|
|
**Decision**: Use Firebase as primary backend
|
|
**Rationale**:
|
|
- Rapid development
|
|
- Built-in security
|
|
- Real-time capabilities
|
|
- Managed infrastructure
|
|
|
|
#### 4. RAG for AI Tutoring
|
|
**Decision**: Use Retrieval-Augmented Generation
|
|
**Rationale**:
|
|
- Context-aware responses
|
|
- Reduced hallucinations
|
|
- Educational content integration
|
|
- Explainable AI
|
|
|
|
#### 5. Flutter for Cross-Platform
|
|
**Decision**: Use Flutter for frontend
|
|
**Rationale**:
|
|
- Single codebase
|
|
- Native performance
|
|
- Consistent UI
|
|
- Rapid development
|
|
|
|
### Technology Trade-offs
|
|
|
|
#### Firebase vs. Custom Backend
|
|
**Firebase Chosen**:
|
|
- ✅ Rapid development
|
|
- ✅ Built-in security
|
|
- ✅ Real-time features
|
|
- ✅ Managed infrastructure
|
|
- ❌ Vendor lock-in
|
|
- ❌ Limited customization
|
|
- ❌ Cost at scale
|
|
|
|
#### Vector Database Options
|
|
**FAISS Chosen**:
|
|
- ✅ Performance
|
|
- ✅ Open source
|
|
- ✅ Python integration
|
|
- ❌ Limited features
|
|
- ❌ No managed service
|
|
- ❌ Scaling complexity
|
|
|
|
#### LLM Provider Strategy
|
|
**Multiple Providers**:
|
|
- ✅ Redundancy
|
|
- ✅ Cost optimization
|
|
- ✅ Feature diversity
|
|
- ❌ Integration complexity
|
|
- ❌ Consistency challenges
|
|
|
|
---
|
|
|
|
## 📈 PERFORMANCE ARCHITECTURE
|
|
|
|
### Performance Optimization Layers
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ PERFORMANCE LAYERS │
|
|
├─────────────────┬─────────────────┬─────────────────────────────┤
|
|
│ Frontend │ Backend │ Database │
|
|
│ │ │ │
|
|
│ • Code Splitting│ • Function Cold │ • Query Optimization │
|
|
│ • Lazy Loading │ Starts │ • Indexing Strategy │
|
|
│ • Image Opt │ • Connection │ • Caching Layers │
|
|
│ • Memory Mgmt │ Pooling │ • Data Sharding │
|
|
│ • Bundle Size │ • Batch Ops │ • Read Replicas │
|
|
│ • Animations │ • Async Processing│ • Compression │
|
|
└─────────────────┴─────────────────┴─────────────────────────────┘
|
|
```
|
|
|
|
### Caching Strategy
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ CACHING HIERARCHY │
|
|
├─────────────────┬─────────────────┬─────────────────────────────┤
|
|
│ Client Cache │ Edge Cache │ Server Cache │
|
|
│ │ │ │
|
|
│ • Memory Cache │ • CDN Cache │ • Redis Cache │
|
|
│ • Local Storage │ • Browser Cache │ • Application Cache │
|
|
│ • Image Cache │ • API Cache │ • Database Cache │
|
|
│ • Response Cache │ • Static Assets │ • Session Cache │
|
|
│ • Offline Cache │ • Global Cache │ • Distributed Cache │
|
|
└─────────────────┴─────────────────┴─────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 🔍 MONITORING ARCHITECTURE
|
|
|
|
### Monitoring Stack
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ MONITORING STACK │
|
|
├─────────────────┬─────────────────┬─────────────────────────────┤
|
|
│ Application │ Infrastructure│ Business │
|
|
│ │ │ │
|
|
│ • Error Tracking│ • Resource Usage│ • User Analytics │
|
|
│ • Performance │ • Health Checks│ • Learning Metrics │
|
|
│ • User Behavior │ • Uptime │ • Engagement Tracking │
|
|
│ • Feature Usage │ • Latency │ • Content Analytics │
|
|
│ • A/B Testing │ • Throughput │ • Progress Analytics │
|
|
│ • Custom Events │ • Error Rates │ • Quiz Performance │
|
|
└─────────────────┴─────────────────┴─────────────────────────────┘
|
|
```
|
|
|
|
### Alerting Strategy
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ ALERTING LAYERS │
|
|
├─────────────────┬─────────────────┬─────────────────────────────┤
|
|
│ Technical │ Business │ Security │
|
|
│ │ │ │
|
|
│ • Error Rate │ • User Activity│ • Threat Detection │
|
|
│ • Response Time │ • Conversion │ • Access Violations │
|
|
│ • Memory Usage │ • Engagement │ • Anomalous Behavior │
|
|
│ • CPU Usage │ • Learning │ • Data Breaches │
|
|
│ • Disk Space │ • Quiz Completion│ • Compliance Violations │
|
|
│ • Network Latency│ • Content Usage│ • Authentication Failures │
|
|
└─────────────────┴─────────────────┴─────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 🚀 FUTURE ARCHITECTURE
|
|
|
|
### Scalability Roadmap
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ EVOLUTION PATH │
|
|
├─────────────────┬─────────────────┬─────────────────────────────┤
|
|
│ Phase 1 │ Phase 2 │ Phase 3 │
|
|
│ (Current) │ (6 months) │ (1 year) │
|
|
│ │ │ │
|
|
│ • Firebase │ • Hybrid Cloud │ • Multi-Region │
|
|
│ • Single Region │ • Custom Backend│ • Edge Computing │
|
|
│ • Basic AI │ • Advanced AI │ • Federated Learning │
|
|
│ • Mobile/Web │ • Desktop Apps │ • AR/VR Support │
|
|
│ • Basic Analytics│• Advanced Analytics│• Predictive Analytics │
|
|
└─────────────────┴─────────────────┴─────────────────────────────┘
|
|
```
|
|
|
|
### Technology Evolution
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ TECHNOLOGY ROADMAP │
|
|
├─────────────────┬─────────────────┬─────────────────────────────┤
|
|
│ Frontend │ Backend │ AI/ML │
|
|
│ │ │ │
|
|
│ • Flutter Web │ • GraphQL API │ • Custom Models │
|
|
│ • Desktop Apps │ • Microservices│ • Fine-tuned LLMs │
|
|
│ • AR/VR Support │ • Event Sourcing│ • Multi-modal AI │
|
|
│ • Voice UI │ • CQRS │ • Real-time Learning │
|
|
│ • Offline Mode │ • Distributed │ • Federated Learning │
|
|
│ • Progressive │ Systems │ • Edge AI │
|
|
│ Web Apps │ • Kubernetes │ • Custom Hardware │
|
|
└─────────────────┴─────────────────┴─────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 📚 DOCUMENTATION ARCHITECTURE
|
|
|
|
### Documentation Structure
|
|
```
|
|
docs/
|
|
├── technical/ # Technical documentation
|
|
│ ├── api/ # API documentation
|
|
│ ├── architecture/ # Architecture docs
|
|
│ ├── database/ # Database docs
|
|
│ └── security/ # Security docs
|
|
├── user/ # User documentation
|
|
│ ├── student/ # Student guides
|
|
│ ├── teacher/ # Teacher guides
|
|
│ └── admin/ # Admin guides
|
|
├── development/ # Development docs
|
|
│ ├── setup/ # Setup guides
|
|
│ ├── contributing/ # Contributing guide
|
|
│ ├── testing/ # Testing guide
|
|
│ └── deployment/ # Deployment guide
|
|
└── business/ # Business documentation
|
|
├── requirements/ # Requirements
|
|
├── roadmap/ # Product roadmap
|
|
└── metrics/ # Business metrics
|
|
```
|
|
|
|
---
|
|
|
|
## 🎯 CONCLUSION
|
|
|
|
The AI Study Assistant architecture is designed to be:
|
|
- **Scalable**: Handle growth in users and content
|
|
- **Maintainable**: Clean, well-documented code
|
|
- **Secure**: Multi-layered security approach
|
|
- **Performant**: Optimized for educational workloads
|
|
- **Accessible**: Universal design principles
|
|
- **Innovative**: Cutting-edge AI/ML integration
|
|
|
|
This architecture provides a solid foundation for delivering high-quality educational experiences while maintaining flexibility for future enhancements and scaling requirements.
|
|
|
|
---
|
|
|
|
*Last Updated: 2026-05-06*
|
|
*Version: 1.0.0*
|
|
*Architecture Team: System Design & Engineering*
|