👨‍💻 Development Guide

Complete guide for developers working on SYMS OS Edge. Learn how to set up your development environment, understand the codebase, and contribute effectively.

🔧 Development Environment Setup

Prerequisites

Clone and Setup

# Clone the repository
git clone https://github.com/lvmre/syms-os-edge.git
cd syms-os-edge

# Copy environment template
cp .env.example docker/.env

# Install dependencies
npm install

# Start development environment
cd docker
docker compose up -d

VS Code Extensions (Recommended)

• ESLint - Code linting for JavaScript
• Prettier - Code formatting
• Docker - Container management
• GitLens - Enhanced Git integration
• Thunder Client - API testing

Local Testing

Start all services locally for development:

# Start all services
cd docker
docker compose up -d

# View logs
docker compose logs -f

# Check service status
docker compose ps

# Stop all services
docker compose down

Access Points:

• Portal: http://localhost:80
• Admin Dashboard: http://localhost:3000
• API Gateway: http://localhost:8080
• Grafana: http://localhost:3001

📁 Project Structure

🔄 Development Workflow

Standard Git Workflow

1. Create feature branch

   git checkout -b feature/my-new-feature

2. Make changes - Edit code, add features, fix bugs
3. Test locally

   npm test
   docker compose up -d
   # Manual testing in browser

4. Commit changes

   git add .
   git commit -m "feat: add user authentication"

5. Push to GitHub

   git push origin feature/my-new-feature

6. Create Pull Request - Via GitHub web interface
7. Code Review - Address feedback, make updates
8. Merge to main - After approval
9. Deploy to test environment - Automated or manual

Commit Message Convention

Follow Conventional Commits specification:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting)
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Maintenance tasks

Examples:

feat: add offline content search
fix: resolve database connection timeout
docs: update API endpoint documentation
refactor: extract auth logic into middleware

🧪 Testing

Running Tests

# Run all tests
npm test

# Run specific test suite
npm test -- api-gateway

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

Test Types

Writing Tests

Example unit test:

// tests/unit/auth.test.js
const { validatePassword } = require('../../shared/validators');

describe('Password Validation', () => {
  test('should accept strong password', () => {
    const result = validatePassword('SecurePass123!');
    expect(result.valid).toBe(true);
  });

  test('should reject weak password', () => {
    const result = validatePassword('weak');
    expect(result.valid).toBe(false);
    expect(result.error).toBe('Password too short');
  });
});

🚀 Deployment

Production Deployment

# 1. Build production images
docker compose -f docker-compose.prod.yml build

# 2. Push to registry (if using)
docker compose -f docker-compose.prod.yml push

# 3. Deploy to Pi
ssh pi@syms-edge-01
cd syms-os-edge
git pull origin main
docker compose -f docker-compose.prod.yml up -d

OTA Updates

Push updates to deployed devices via admin dashboard:

1. Navigate to Fleet Management
2. Select device group
3. Click Deploy Update
4. Choose update type (full / incremental)
5. Monitor progress in real-time

Monitoring Deployment

Track deployment health:

• Grafana Dashboards: Real-time metrics
• Prometheus Alerts: Automated notifications
• Device Logs: Centralized logging via Loki
• Health Checks: API endpoint monitoring

🤝 Contributing

Code Style

• Use ESLint for JavaScript linting
• Use Prettier for code formatting
• Follow Airbnb JavaScript Style Guide
• Write descriptive variable and function names
• Add JSDoc comments for public APIs

Pull Request Guidelines

1. One feature per PR - Keep changes focused
2. Add tests - New features must include tests
3. Update documentation - If API changes
4. Follow commit conventions - Use Conventional Commits
5. Request review - From at least one maintainer

Code Review Checklist

• ✅ Code follows style guidelines
• ✅ Tests pass and cover new code
• ✅ Documentation is updated
• ✅ No security vulnerabilities introduced
• ✅ Performance impact is acceptable
• ✅ Changes are backwards compatible (if possible)

Getting Help

• GitHub Discussions: Ask questions, share ideas
• GitHub Issues: Report bugs, request features
• Email: [email protected]
• Slack: Join our developer community (link in repo)