First Commit

2026-05-06 20:16:11 +01:00
parent e45b7eb586
commit 547d5f5484
146 changed files with 28546 additions and 0 deletions
--- a/docs/DEVELOPMENT_SETUP.md
+++ b/docs/DEVELOPMENT_SETUP.md
@@ -0,0 +1,798 @@
+# Development Setup Guide - AI Study Assistant
+
+## 🛠️ 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.
+
+---
+
+## 🎯 PREREQUISITES
+
+### System Requirements
+- **Operating System**: Windows 10+, macOS 10.15+, or Ubuntu 18.04+
+- **RAM**: Minimum 8GB, recommended 16GB
+- **Storage**: Minimum 20GB free space
+- **Internet**: Stable connection for Firebase and API access
+
+### Required Software
+- **Git**: Version 2.30+
+- **Node.js**: Version 18.x LTS
+- **Flutter**: Version 3.41.0+
+- **Python**: Version 3.9+ (for RAG engine)
+- **Firebase CLI**: Latest version
+- **Docker**: Optional, for containerized development
+
+---
+
+## 📥 INITIAL SETUP
+
+### 1. Clone Repository
+```bash
+git clone https://github.com/your-org/teachit.git
+cd teachit
+```
+
+### 2. Install Development Tools
+```bash
+# Install Flutter
+# Download from https://flutter.dev/docs/get-started/install
+# Add to PATH and run:
+flutter doctor
+
+# Install Node.js
+# Download from https://nodejs.org/
+# Verify installation:
+node --version
+npm --version
+
+# Install Python
+# Download from https://python.org/
+# Verify installation:
+python --version
+
+# Install Firebase CLI
+npm install -g firebase-tools
+firebase --version
+
+# Install Git
+# Download from https://git-scm.com/
+# Verify installation:
+git --version
+```
+
+### 3. Environment Configuration
+```bash
+# Create environment files
+cp .env.example .env.development
+cp .env.example .env.staging
+cp .env.example .env.production
+
+# Configure development environment
+# Edit .env.development with your local settings
+```
+
+---
+
+## 📱 FLUTTER SETUP
+
+### 1. Flutter Environment
+```bash
+# Check Flutter installation
+flutter doctor -v
+
+# Install required Flutter tools
+flutter pub get
+
+# Install iOS dependencies (macOS only)
+cd ios && pod install && cd ..
+
+# Install Android dependencies
+# Open android/ in Android Studio and let it setup
+```
+
+### 2. IDE Configuration
+
+#### VS Code Setup
+```bash
+# Install VS Code extensions
+code --install-extension Dart-Code.flutter
+code --install-extension Dart-Code.dart-code
+code --install-extension ms-vscode.vscode-json
+code --install-extension bradlc.vscode-tailwindcss
+code --install-extension ms-vscode.vscode-eslint
+code --install-extension esbenp.prettier-vscode
+```
+
+#### VS Code Settings
+```json
+// .vscode/settings.json
+{
+  "dart.flutterSdkPath": "flutter",
+  "dart.debugExternalLibraries": false,
+  "dart.debugSdkLibraries": false,
+  "files.associations": {
+    "*.arb": "json"
+  },
+  "editor.formatOnSave": true,
+  "editor.codeActionsOnSave": {
+    "source.fixAll": true
+  }
+}
+```
+
+#### Android Studio Setup
+1. Install Flutter plugin
+2. Install Dart plugin
+3. Configure SDK paths
+4. Setup Android emulator
+5. Enable hot reload
+
+### 3. Flutter Configuration
+```bash
+# Create local properties
+echo "flutter.sdk=/path/to/flutter" > local.properties
+
+# Configure Firebase for Flutter
+flutter pub add firebase_core
+flutter pub add firebase_auth
+flutter pub add cloud_firestore
+flutter pub add firebase_storage
+flutter pub add firebase_analytics
+
+# Download Firebase config files
+# Place google-services.json in android/app/
+# Place GoogleService-Info.plist in ios/Runner/
+```
+
+### 4. Run Flutter App
+```bash
+# Run on web
+flutter run -d chrome --web-renderer canvaskit
+
+# Run on Android
+flutter run -d android
+
+# Run on iOS
+flutter run -d ios
+
+# Run on all available devices
+flutter run -d all
+```
+
+---
+
+## ⚡ BACKEND SETUP
+
+### 1. Node.js Environment
+```bash
+cd functions
+
+# Install dependencies
+npm install
+
+# Install global packages
+npm install -g nodemon
+npm install -g typescript
+npm install -g ts-node
+
+# Verify installation
+node --version
+npm --version
+```
+
+### 2. Firebase Functions Setup
+```bash
+# Initialize Firebase functions
+firebase init functions
+
+# Select TypeScript
+# Select ESLint
+# Configure npm
+# Install dependencies
+```
+
+### 3. Environment Variables
+```bash
+# Create .env file in functions/
+cp .env.example .env
+
+# Configure environment variables
+# OPENAI_API_KEY=your_openai_api_key
+# ANTHROPIC_API_KEY=your_anthropic_api_key
+# FIREBASE_PROJECT_ID=teachit-dev-12345
+# NODE_ENV=development
+```
+
+### 4. Firebase Functions Configuration
+```bash
+# Set Firebase config
+firebase functions:config:set \
+  openai.api_key=your_openai_api_key \
+  anthropic.api_key=your_anthropic_api_key \
+  environment=development
+
+# Deploy functions (development)
+firebase deploy --only functions --project teachit-dev-12345
+```
+
+### 5. Local Development Server
+```bash
+# Start local functions
+npm run serve
+
+# Start with hot reload
+npm run dev
+
+# Start with debugging
+npm run debug
+```
+
+---
+
+## 🔥 FIREBASE SETUP
+
+### 1. Firebase Projects
+Create three Firebase projects:
+- **Development**: `teachit-dev-12345`
+- **Staging**: `teachit-staging-12345`
+- **Production**: `teachit-prod-12345`
+
+### 2. Firebase CLI Configuration
+```bash
+# Login to Firebase
+firebase login
+
+# Use development project
+firebase use teachit-dev-12345
+
+# List projects
+firebase projects:list
+
+# Switch projects
+firebase use teachit-staging-12345
+```
+
+### 3. Firebase Services Setup
+```bash
+# Enable required services
+firebase auth --enable
+firebase firestore:databases:create
+firebase storage:buckets:create teachit-content
+
+# Deploy security rules
+firebase deploy --only firestore:rules
+firebase deploy --only storage:rules
+
+# Deploy indexes
+firebase deploy --only firestore:indexes
+```
+
+### 4. Firebase Emulators
+```bash
+# Start emulators
+firebase emulators:start
+
+# Start specific emulators
+firebase emulators:start --only firestore,auth,functions
+
+# Start with UI
+firebase emulators:start --ui
+
+# Import test data
+firebase emulators:import --project teachit-dev-12345 test-data/
+```
+
+---
+
+## 🤖 RAG ENGINE SETUP
+
+### 1. Python Environment
+```bash
+# Create virtual environment
+python -m venv rag_env
+
+# Activate virtual environment
+# Windows
+rag_env\Scripts\activate
+# macOS/Linux
+source rag_env/bin/activate
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Install development dependencies
+pip install pytest pytest-asyncio black flake8 mypy
+```
+
+### 2. RAG Engine Configuration
+```bash
+cd rag_engine
+
+# Create configuration file
+cp config/default.yaml config/local.yaml
+
+# Edit local.yaml with your settings
+# Update API keys and paths
+```
+
+### 3. Vector Database Setup
+```bash
+# Install FAISS
+pip install faiss-cpu
+
+# Or with GPU support
+pip install faiss-gpu
+
+# Install sentence-transformers
+pip install sentence-transformers
+
+# Download models
+python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')"
+```
+
+### 4. Run RAG Engine
+```bash
+# Start development server
+python src/main.py
+
+# Run with specific configuration
+python src/main.py --config local
+
+# Run tests
+pytest tests/
+```
+
+---
+
+## 🗄️ DATABASE SETUP
+
+### 1. Firestore Database
+```bash
+# Create database
+firebase firestore:databases:create
+
+# Set up collections
+firebase firestore:databases:create --database "teachit-db"
+
+# Import schema
+firebase firestore:import schema.json
+```
+
+### 2. Local Development Data
+```bash
+# Create test data
+node scripts/create-test-data.js
+
+# Import to emulator
+firebase emulators:import --project teachit-dev-12345 test-data/
+
+# Export data
+firebase emulators:export --project teachit-dev-12345 export-data/
+```
+
+### 3. Database Indexes
+```bash
+# Create indexes
+firebase deploy --only firestore:indexes
+
+# Check index status
+firebase firestore:indexes:list
+
+# Monitor index creation
+firebase firestore:indexes:describe
+```
+
+---
+
+## 🧪 TESTING SETUP
+
+### 1. Flutter Testing
+```bash
+# Run unit tests
+flutter test
+
+# Run widget tests
+flutter test test/widget/
+
+# Run integration tests
+flutter test integration_test/
+
+# Generate coverage
+flutter test --coverage
+genhtml coverage/lcov.info -o coverage/html
+```
+
+### 2. Backend Testing
+```bash
+cd functions
+
+# Run unit tests
+npm test
+
+# Run integration tests
+npm run test:integration
+
+# Run with coverage
+npm run test:coverage
+
+# Run tests in watch mode
+npm run test:watch
+```
+
+### 3. RAG Engine Testing
+```bash
+cd rag_engine
+
+# Run unit tests
+pytest tests/unit/
+
+# Run integration tests
+pytest tests/integration/
+
+# Run with coverage
+pytest --cov=src tests/
+
+# Run performance tests
+pytest tests/performance/
+```
+
+---
+
+## 🔧 DEVELOPMENT TOOLS
+
+### 1. Git Configuration
+```bash
+# Configure Git
+git config --global user.name "Your Name"
+git config --global user.email "your.email@example.com"
+
+# Set up Git hooks
+cp scripts/pre-commit .git/hooks/
+chmod +x .git/hooks/pre-commit
+
+# Configure Git aliases
+git config --global alias.st status
+git config --global alias.co checkout
+git config --global alias.br branch
+git config --global alias.cm commit
+```
+
+### 2. Code Quality Tools
+```bash
+# Flutter
+flutter analyze
+dart format --set-exit-if-changed .
+
+# Node.js
+npm run lint
+npm run format
+
+# Python
+black src/
+flake8 src/
+mypy src/
+```
+
+### 3. Development Scripts
+```bash
+# Make scripts executable
+chmod +x scripts/*.sh
+
+# Run setup script
+./scripts/setup.sh
+
+# Run development server
+./scripts/dev.sh
+
+# Run tests
+./scripts/test.sh
+```
+
+---
+
+## 📱 DEVICE SETUP
+
+### 1. Android Setup
+```bash
+# Enable USB debugging
+# Settings > About phone > Tap "Build number" 7 times
+# Settings > Developer options > Enable USB debugging
+
+# Verify device connection
+flutter devices
+
+# Run on device
+flutter run -d <device_id>
+```
+
+### 2. iOS Setup (macOS only)
+```bash
+# Install Xcode
+xcode-select --install
+
+# Setup iOS simulator
+open -a Simulator
+
+# Verify iOS setup
+flutter devices
+
+# Run on simulator
+flutter run -d ios
+```
+
+### 3. Web Setup
+```bash
+# Enable web platform
+flutter config --enable-web
+
+# Run on Chrome
+flutter run -d chrome
+
+# Run with specific renderer
+flutter run -d chrome --web-renderer canvaskit
+```
+
+---
+
+## 🔍 DEBUGGING SETUP
+
+### 1. Flutter Debugging
+```bash
+# Debug with breakpoints
+flutter run --debug
+
+# Profile app
+flutter run --profile
+
+# Debug specific file
+flutter run --debug --target=test/debug_test.dart
+
+# Hot reload
+flutter run --hot
+```
+
+### 2. Backend Debugging
+```bash
+# Debug functions
+firebase functions:shell
+
+# Debug with VS Code
+# Launch configuration in .vscode/launch.json
+
+# Console logging
+firebase functions:log
+```
+
+### 3. Network Debugging
+```bash
+# Monitor network requests
+# Use Chrome DevTools
+# Use Flutter Inspector
+
+# Debug API calls
+curl -H "Authorization: Bearer <token>" https://api.teachit.app/health
+```
+
+---
+
+## 📊 MONITORING SETUP
+
+### 1. Local Monitoring
+```bash
+# Start monitoring dashboard
+npm run monitor
+
+# View logs
+firebase functions:log
+
+# Monitor Firestore
+firebase firestore:databases:list
+```
+
+### 2. Performance Monitoring
+```bash
+# Flutter performance
+flutter run --profile --trace-startup
+
+# Backend performance
+npm run benchmark
+
+# RAG engine performance
+python scripts/benchmark.py
+```
+
+---
+
+## 🔄 WORKFLOW SETUP
+
+### 1. Git Workflow
+```bash
+# Create feature branch
+git checkout -b feature/new-feature
+
+# Commit changes
+git add .
+git commit -m "feat: add new feature"
+
+# Push branch
+git push origin feature/new-feature
+
+# Create pull request
+# Use GitHub UI or CLI
+```
+
+### 2. Development Workflow
+```bash
+# Start development
+./scripts/dev.sh
+
+# Run tests
+./scripts/test.sh
+
+# Format code
+./scripts/format.sh
+
+# Deploy to staging
+./scripts/deploy-staging.sh
+```
+
+### 3. Code Review Process
+```bash
+# Run pre-commit checks
+./scripts/pre-commit.sh
+
+# Create pull request
+gh pr create --title "Add new feature" --body "Description"
+
+# Request review
+gh pr request-review @reviewer
+
+# Merge after approval
+gh pr merge --squash
+```
+
+---
+
+## 🛠️ TROUBLESHOOTING
+
+### Common Issues
+
+#### Flutter Issues
+```bash
+# Flutter doctor issues
+flutter doctor -v
+
+# Clean build
+flutter clean
+flutter pub get
+
+# Reset Flutter
+git clean -xfd
+flutter pub get
+```
+
+#### Firebase Issues
+```bash
+# Firebase login issues
+firebase logout
+firebase login
+
+# Project access issues
+firebase projects:list
+firebase use <project-id>
+
+# Emulator issues
+firebase emulators:start --clean
+```
+
+#### Node.js Issues
+```bash
+# Node version issues
+nvm use 18
+nvm install 18
+
+# Dependency issues
+rm -rf node_modules package-lock.json
+npm install
+
+# Build issues
+npm run build
+npm run clean
+```
+
+#### Python Issues
+```bash
+# Virtual environment issues
+deactivate
+python -m venv rag_env
+source rag_env/bin/activate
+
+# Dependency issues
+pip install --upgrade pip
+pip install -r requirements.txt
+```
+
+### Performance Issues
+```bash
+# Flutter performance
+flutter run --profile
+flutter analyze
+
+# Backend performance
+npm run benchmark
+firebase functions:log
+
+# RAG engine performance
+python -m cProfile src/main.py
+```
+
+---
+
+## 📚 LEARNING RESOURCES
+
+### Documentation
+- [Flutter Documentation](https://flutter.dev/docs)
+- [Firebase Documentation](https://firebase.google.com/docs)
+- [Node.js Documentation](https://nodejs.org/docs)
+- [Python Documentation](https://docs.python.org/3/)
+
+### Tutorials
+- [Flutter Codelabs](https://flutter.dev/codelabs)
+- [Firebase Codelabs](https://firebase.google.com/codelabs)
+- [Node.js Best Practices](https://github.com/goldbergyoni/nodebestpractices)
+
+### Community
+- [Flutter Community](https://flutter.dev/community)
+- [Firebase Community](https://firebase.google.com/community)
+- [Stack Overflow](https://stackoverflow.com/questions/tagged/flutter)
+
+---
+
+## 📞 SUPPORT
+
+### Getting Help
+- **Team Chat**: [Slack Channel]
+- **Issue Tracker**: [GitHub Issues]
+- **Documentation**: [Project Wiki]
+- **Email**: dev-team@teachit.app
+
+### Contributing
+- Read [CONTRIBUTING.md](CONTRIBUTING.md)
+- Follow [Code of Conduct](CODE_OF_CONDUCT.md)
+- Submit [Pull Requests](https://github.com/your-org/teachit/pulls)
+
+---
+
+## ✅ VALIDATION CHECKLIST
+
+### Setup Validation
+- [ ] Flutter installed and configured
+- [ ] Firebase CLI configured
+- [ ] Node.js environment ready
+- [ ] Python environment ready
+- [ ] Database schema created
+- [ ] Emulators running
+- [ ] Tests passing
+- [ ] Code quality tools working
+- [ ] IDE configured
+- [ ] Git workflow set up
+
+### Development Validation
+- [ ] Can run Flutter app locally
+- [ ] Can run backend functions locally
+- [ ] Can run RAG engine locally
+- [ ] Can connect to Firebase emulators
+- [ ] Can run tests successfully
+- [ ] Can deploy to staging
+- [ ] Can debug issues
+- [ ] Can monitor performance
+
+---
+
+*Last Updated: 2026-05-06*
+*Version: 1.0.0*
+*DevOps Team: Infrastructure & Tools*