# Development Workflow

Comprehensive guide to daily development processes, Git workflow, and team collaboration for the ThrillWiki monorepo.

## Overview

This document outlines the development workflow for the ThrillWiki Django + Vue.js monorepo. Following these practices ensures consistent code quality, smooth collaboration, and reliable deployments.

## 🏗️ Project Structure

```
thrillwiki-monorepo/
├── backend/                 # Django REST API
├── frontend/                # Vue.js SPA
├── shared/                  # Shared resources and scripts
├── architecture/            # Architecture documentation
└── profiles/                # Development profiles
```

## 🚀 Daily Development Workflow

### 1. Environment Setup

#### First Time Setup
```bash
# Clone the repository
git clone <repository-url>
cd thrillwiki-monorepo

# Run the automated setup script
./shared/scripts/dev/setup-dev.sh

# Or set up manually
cd backend && uv sync && cd ..
pnpm install
```

#### Daily Setup
```bash
# Start all development servers
./shared/scripts/dev/start-all.sh

# Or start individually
pnpm run dev:backend    # Django on :8000
pnpm run dev:frontend   # Vue.js on :5174
```

### 2. Development Process

#### Feature Development
1. **Create a feature branch**
   ```bash
   git checkout -b feature/your-feature-name
   ```

2. **Make your changes**
   - Follow the coding standards for your language
   - Write tests for new functionality
   - Update documentation as needed

3. **Test your changes**
   ```bash
   # Backend tests
   cd backend && uv run manage.py test

   # Frontend tests
   cd frontend && pnpm test:unit
   cd frontend && pnpm test:e2e

   # Full test suite
   pnpm run test
   ```

4. **Code quality checks**
   ```bash
   # Backend
   cd backend && uv run black . && uv run flake8 .

   # Frontend
   cd frontend && pnpm lint && pnpm type-check
   ```

#### Bug Fixes
1. **Create a bug fix branch**
   ```bash
   git checkout -b bugfix/issue-description
   ```

2. **Reproduce the issue**
   - Add test cases that reproduce the bug
   - Verify the fix resolves the issue

3. **Implement the fix**
   - Keep changes minimal and focused
   - Ensure no regressions

### 3. Code Review Process

#### Before Submitting
- [ ] All tests pass
- [ ] Code follows style guidelines
- [ ] Documentation updated
- [ ] No linting errors
- [ ] TypeScript types correct (frontend)
- [ ] Database migrations created (backend)

#### Pull Request Process
1. **Create Pull Request**
   - Use descriptive title
   - Fill out PR template
   - Link related issues
   - Add screenshots for UI changes

2. **Code Review**
   - At least one approval required
   - Address all review comments
   - Rebase and resolve conflicts

3. **Merge Process**
   - Use "Squash and merge" for feature branches
   - Use "Rebase and merge" for maintenance branches
   - Delete branch after merge

## 🔄 Git Workflow

### Branch Naming Convention

```
feature/feature-name          # New features
bugfix/issue-description      # Bug fixes
hotfix/critical-issue         # Critical production fixes
refactor/component-name       # Code refactoring
docs/update-documentation     # Documentation updates
test/add-test-coverage        # Test improvements
```

### Commit Message Format

```
type(scope): description

[optional body]

[optional footer]
```

**Types:**
- `feat` - New feature
- `fix` - Bug fix
- `docs` - Documentation
- `style` - Code style changes
- `refactor` - Code refactoring
- `test` - Adding tests
- `chore` - Maintenance tasks

**Examples:**
```
feat: add park search functionality
fix: resolve ride detail page crash
docs: update API documentation
refactor: simplify park service layer
```

### Git Workflow

#### Feature Development
```bash
# Start from main
git checkout main
git pull origin main

# Create feature branch
git checkout -b feature/new-park-search

# Make changes and commit
git add .
git commit -m "feat: implement park search with filters"

# Push and create PR
git push origin feature/new-park-search
```

#### Handling Conflicts
```bash
# Update your branch with latest main
git fetch origin
git rebase origin/main

# Resolve conflicts if any
# Test your changes
# Force push if needed
git push --force-with-lease origin feature/new-park-search
```

## 🧪 Testing Strategy

### Backend Testing

#### Unit Tests
```bash
cd backend

# Run all tests
uv run manage.py test

# Run specific app tests
uv run manage.py test apps.parks

# Run with coverage
uv run coverage run manage.py test
uv run coverage report
```

#### Test Structure
```
backend/tests/
├── test_models.py      # Model tests
├── test_views.py       # View tests
├── test_serializers.py # Serializer tests
└── test_services.py    # Service layer tests
```

### Frontend Testing

#### Unit Tests (Vitest)
```bash
cd frontend

# Run unit tests
pnpm test:unit

# Run with coverage
pnpm test:unit --coverage

# Watch mode for development
pnpm test:unit --watch
```

#### End-to-End Tests (Playwright)
```bash
cd frontend

# Run E2E tests
pnpm test:e2e

# Run specific test
pnpm test:e2e tests/park-search.spec.ts

# Debug mode
pnpm test:e2e --debug
```

#### Test Structure
```
frontend/src/__tests__/
├── components/         # Component tests
├── views/             # Page tests
├── services/          # Service tests
└── stores/            # Store tests
```

### Test Coverage Requirements

- **Backend:** Minimum 80% coverage
- **Frontend:** Minimum 70% coverage
- **Critical paths:** 90%+ coverage

## 🔧 Code Quality

### Backend Standards

#### Python Code Style
```bash
cd backend

# Format code
uv run black .

# Check style
uv run flake8 .

# Sort imports
uv run isort .
```

#### Django Best Practices
- Use Django REST Framework best practices
- Implement proper error handling
- Add database indexes for performance
- Use select_related and prefetch_related for optimization

### Frontend Standards

#### Vue.js Best Practices
```bash
cd frontend

# Lint code
pnpm lint

# Type checking
pnpm type-check

# Format code
pnpm format
```

#### Code Organization
- Use Composition API with `<script setup>`
- Implement proper component structure
- Follow Vue.js style guide
- Use TypeScript for type safety

## 🚀 Deployment Process

### Development Environment

#### Automated Deployment
```bash
# Deploy to development
./shared/scripts/deploy/deploy.sh dev

# Check deployment status
./shared/scripts/deploy/check-status.sh dev
```

#### Manual Deployment
1. **Build frontend**
   ```bash
   cd frontend
   pnpm build
   ```

2. **Run backend migrations**
   ```bash
   cd backend
   uv run manage.py migrate
   ```

3. **Collect static files**
   ```bash
   cd backend
   uv run manage.py collectstatic
   ```

### Staging Environment

#### Deployment Checklist
- [ ] All tests pass
- [ ] Code review completed
- [ ] Documentation updated
- [ ] Database migrations tested
- [ ] Environment variables configured

#### Deployment Steps
```bash
# Build for staging
pnpm run build:staging

# Deploy to staging
./shared/scripts/deploy/deploy.sh staging

# Run smoke tests
./shared/scripts/deploy/smoke-test.sh staging
```

### Production Environment

#### Pre-Deployment
1. **Create release branch**
   ```bash
   git checkout -b release/v1.2.3
   ```

2. **Update version numbers**
   - Update `package.json`
   - Update `pyproject.toml`
   - Tag the release

3. **Final testing**
   ```bash
   # Run full test suite
   pnpm run test

   # Performance testing
   ./shared/scripts/test/performance-test.sh
   ```

#### Production Deployment
```bash
# Build for production
pnpm run build:production

# Deploy to production
./shared/scripts/deploy/deploy.sh production

# Verify deployment
./shared/scripts/deploy/health-check.sh production

# Rollback if needed
./shared/scripts/deploy/rollback.sh production
```

## 🔍 Monitoring and Debugging

### Development Debugging

#### Backend Debugging
```bash
cd backend

# Django shell for debugging
uv run manage.py shell

# Django debug toolbar (development only)
# Access at http://localhost:8000/__debug__/

# Logging
tail -f logs/django.log
```

#### Frontend Debugging
```bash
cd frontend

# Vue DevTools browser extension
# Access at http://localhost:5174/__devtools__/

# Browser developer tools
# - Console for errors
# - Network tab for API calls
# - Vue tab for component inspection
```

### Production Monitoring

#### Health Checks
```bash
# API health check
curl http://localhost:8000/api/health/

# Database connectivity
./shared/scripts/monitor/db-check.sh

# Background job status
./shared/scripts/monitor/job-status.sh
```

#### Error Tracking
- Check application logs
- Monitor error rates
- Review performance metrics
- User feedback and bug reports

## 📚 Documentation

### Documentation Updates

#### When to Update Documentation
- New features implemented
- API changes
- Configuration changes
- Deployment process changes

#### Documentation Standards
- Use clear, concise language
- Include code examples
- Provide step-by-step instructions
- Update README files
- Maintain API documentation

### Documentation Files
- `README.md` - Main project documentation
- `backend/README.md` - Backend-specific documentation
- `frontend/README.md` - Frontend-specific documentation
- `shared/docs/api/README.md` - API documentation
- `shared/docs/development/workflow.md` - This file

## 🤝 Team Collaboration

### Communication

#### Daily Standup
- What did you work on yesterday?
- What are you working on today?
- Any blockers or issues?

#### Code Reviews
- Be constructive and respectful
- Focus on code quality and best practices
- Suggest improvements, don't demand changes
- Explain reasoning behind suggestions

### Knowledge Sharing

#### Documentation
- Update README files
- Document complex business logic
- Create troubleshooting guides

#### Pair Programming
- Share knowledge through pair programming
- Rotate team members on different parts of the system
- Cross-train on both backend and frontend

## 🛠️ Development Tools

### Essential Tools

#### Version Control
- **Git** - Version control system
- **GitHub** - Repository hosting and collaboration
- **GitHub Actions** - CI/CD pipeline

#### Code Quality
- **ESLint** - JavaScript/TypeScript linting
- **Prettier** - Code formatting
- **Black** - Python code formatting
- **Flake8** - Python linting

#### Testing
- **Vitest** - Frontend unit testing
- **Playwright** - E2E testing
- **pytest** - Backend testing

### Development Environment

#### IDE Configuration
- **VSCode** with recommended extensions
- **Vue Language Features** extension
- **Python** extension
- **Prettier** extension

#### Local Development
- **Docker** for consistent environments
- **direnv** for environment variables
- **nodenv** for Node.js version management

## 🚨 Emergency Procedures

### Critical Issues

#### Production Outage
1. **Assess the situation**
   - Identify the scope of the issue
   - Determine impact on users

2. **Communication**
   - Notify team members
   - Update status page if applicable

3. **Resolution**
   ```bash
   # Quick rollback if needed
   ./shared/scripts/deploy/rollback.sh production

   # Or hotfix
   git checkout -b hotfix/critical-issue
   # Implement fix
   ./shared/scripts/deploy/deploy.sh production
   ```

#### Security Issues
1. **Assess vulnerability**
   - Determine severity and impact
   - Check for exploitation

2. **Response**
   - Implement temporary mitigation
   - Develop permanent fix
   - Deploy security patch

3. **Post-mortem**
   - Document the incident
   - Update security procedures
   - Improve monitoring

## 📈 Performance Optimization

### Frontend Performance

#### Bundle Optimization
```bash
# Analyze bundle size
cd frontend
pnpm build --analyze

# Code splitting
const ParkDetail = () => import('./views/ParkDetail.vue')
```

#### Image Optimization
- Use WebP format for images
- Implement lazy loading
- Optimize image sizes

### Backend Performance

#### Database Optimization
```python
# Use select_related for foreign keys
parks = Park.objects.select_related('operator')

# Use prefetch_related for many-to-many
parks = Park.objects.prefetch_related('rides')
```

#### Caching Strategy
- Cache frequently accessed data
- Use Redis for session storage
- Implement database query caching

## 🔒 Security Best Practices

### Code Security
- Regular dependency updates
- Security scanning with tools like Snyk
- Code review security checklist
- Input validation and sanitization

### Infrastructure Security
- HTTPS everywhere
- Secure headers implementation
- Regular security audits
- Access control and authentication

## 📋 Checklist

### Before Committing Code
- [ ] Tests pass
- [ ] Code follows style guidelines
- [ ] No linting errors
- [ ] Documentation updated
- [ ] Commit message follows convention

### Before Creating Pull Request
- [ ] Feature branch up to date with main
- [ ] All tests pass
- [ ] Code review checklist completed
- [ ] Documentation updated
- [ ] No merge conflicts

### Before Merging to Main
- [ ] CI/CD pipeline passes
- [ ] Code review approved
- [ ] Tests pass in CI environment
- [ ] No critical security issues

This workflow ensures consistent, high-quality development across the ThrillWiki monorepo while maintaining excellent collaboration and deployment practices.