799 lines
14 KiB
Markdown
799 lines
14 KiB
Markdown
# 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*
|