# 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://gitea.epvc.pt/240405/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*