240405/LearnIT
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c1d1a0fce131e89991bc726e3871734ec8f45482
LearnIT/docs/DEVELOPMENT_SETUP.md

14 KiB
Raw Blame History

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

git clone https://gitea.epvc.pt/240405/TeachIT.git
cd teachit

2. Install Development Tools

# 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

# 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

# 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

# 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

// .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

# 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

# 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

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

# Initialize Firebase functions
firebase init functions

# Select TypeScript
# Select ESLint
# Configure npm
# Install dependencies

3. Environment Variables

# 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

# 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

# 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

# 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

# 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

# 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

# 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

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

# 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

# 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

# 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

# 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

# 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

# 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

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

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

# 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

# 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

# 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

# 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)

# 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

# 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

# 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

# Debug functions
firebase functions:shell

# Debug with VS Code
# Launch configuration in .vscode/launch.json

# Console logging
firebase functions:log

3. Network Debugging

# 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

# Start monitoring dashboard
npm run monitor

# View logs
firebase functions:log

# Monitor Firestore
firebase firestore:databases:list

2. Performance Monitoring

# Flutter performance
flutter run --profile --trace-startup

# Backend performance
npm run benchmark

# RAG engine performance
python scripts/benchmark.py

🔄 WORKFLOW SETUP

1. Git Workflow

# 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

# 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

# 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

# Flutter doctor issues
flutter doctor -v

# Clean build
flutter clean
flutter pub get

# Reset Flutter
git clean -xfd
flutter pub get

Firebase Issues

# 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

# 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

# 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

# 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

Tutorials

Community

📞 SUPPORT

Getting Help

  • Team Chat: [Slack Channel]
  • Issue Tracker: [GitHub Issues]
  • Documentation: [Project Wiki]
  • Email: dev-team@teachit.app

Contributing

✅ 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

Reference in New Issue View Git Blame Copy Permalink