Development Guidelines¶

Overview¶

This document provides comprehensive development guidelines for the Dispatch Center Application, covering coding standards, architecture patterns, testing strategies, and deployment practices for both web and mobile applications.

Table of Contents¶

Code Standards
Architecture Guidelines
Mobile Development (React Native)
Web Development
API Development
Database Development
Testing Strategy
Git Workflow
Security Guidelines
Performance Guidelines
Deployment Guidelines

Code Standards¶

.NET Backend Standards¶

Follow Microsoft .NET coding conventions and C# style guidelines
Use dependency injection for service registration and resolution
Implement comprehensive logging with structured logging (Serilog)
Use async/await patterns for all I/O operations
Apply SOLID principles and clean architecture patterns
Implement proper error handling with global exception middleware
Use Entity Framework Core with Code First migrations
Follow naming conventions: PascalCase for classes, camelCase for variables

Frontend Standards (Vue.js 3)¶

Use Vue.js 3 Composition API exclusively
Implement TypeScript for type safety and better developer experience
Follow Vue.js style guide and naming conventions
Use Tailwind CSS utility classes for consistent styling
Implement proper component lifecycle management
Use Pinia for state management with proper store organization
Follow single responsibility principle for components

Mobile Standards (React Native)¶

Target iOS and Android platforms with shared business logic
Use functional components with React Hooks for state management
Implement platform-specific optimizations when necessary
Follow mobile UI/UX best practices for field technician workflows
Use React Navigation for navigation patterns and deep linking
Implement offline-first architecture with local storage and background sync

Shared Standards¶

Maintain minimum 80% unit test coverage across all projects
Use meaningful variable and method names that express intent
Write self-documenting code with minimal but effective comments
Implement proper null checking and defensive programming
Use consistent indentation (4 spaces for C#, 2 spaces for Vue.js/TypeScript)
Follow DRY (Don't Repeat Yourself) and KISS (Keep It Simple, Stupid) principles

Architecture Guidelines¶

Backend Architecture (.NET 10)¶

src/
├── DispatchCenter.Api/              # Web API layer
├── DispatchCenter.Application/      # Application business logic
├── DispatchCenter.Domain/           # Domain entities and business rules
├── DispatchCenter.Infrastructure/   # External concerns (database, external APIs)
├── DispatchCenter.Shared/           # Shared DTOs and contracts
└── DispatchCenter.Tests/            # Test projects

Clean Architecture Principles¶

Domain Layer: Contains business entities, domain services, and business rules
Application Layer: Contains use cases, application services, and interfaces
Infrastructure Layer: Contains data access, external service integrations
API Layer: Contains controllers, middleware, and API-specific concerns

Dependency Flow¶

API Layer → Application Layer → Domain Layer
     ↓            ↓                ↓
Infrastructure Layer (implements interfaces)

Mobile Development (React Native)¶

Project Structure¶

src/mobile/
├── android/                     # Android-specific code
├── ios/                         # iOS-specific code
├── src/
│   ├── components/              # Reusable UI components
│   ├── screens/                 # Screen components
│   ├── navigation/              # React Navigation configuration
│   ├── hooks/                   # Custom React hooks
│   ├── services/                # API and business services
│   ├── store/                   # State management (Redux/Zustand)
│   ├── utils/                   # Utility functions
│   ├── types/                   # TypeScript type definitions
│   └── assets/                  # Images, fonts, styles
├── App.tsx                      # App entry point
└── package.json                 # Dependencies

Offline-First Architecture¶

Local Storage: Use SQLite for offline data persistence
Synchronization: Implement background sync when connectivity is available
Conflict Resolution: Handle data conflicts with last-write-wins or user choice
Queue Management: Queue offline operations for later synchronization
Connection Monitoring: Monitor network connectivity and adjust behavior

Mobile-Specific Features¶

// GPS Location Services
import Geolocation from '@react-native-community/geolocation';

interface LocationService {
  getCurrentLocation(): Promise<GeolocationPosition>;
  startLocationTracking(callback: (position: GeolocationPosition) => void): number;
  stopLocationTracking(watchId: number): void;
}

// Camera and Media Services
import { launchCamera, launchImageLibrary } from 'react-native-image-picker';

interface MediaService {
  takePhoto(): Promise<MediaFile>;
  pickPhoto(): Promise<MediaFile>;
  scanBarcode(): Promise<string>;
}

// Local Database Service (AsyncStorage + SQLite)
import AsyncStorage from '@react-native-async-storage/async-storage';

interface LocalDatabaseService {
  getServiceRequests(): Promise<ServiceRequest[]>;
  saveServiceRequest(request: ServiceRequest): Promise<void>;
  syncData(): Promise<void>;
}

Platform-Specific Implementations¶

iOS: Follow Apple Human Interface Guidelines
Android: Follow Material Design principles
Permissions: Implement proper permission requests for location, camera, storage
Background Tasks: Use platform-appropriate background processing

Web Development¶

Vue.js 3 Component Structure¶

<template>
  <!-- Clean, semantic HTML with proper accessibility -->
</template>

<script setup lang="ts">
// Composition API with TypeScript
import { ref, computed, onMounted } from 'vue'

// Props and emits with proper typing
interface Props {
  // Define props interface
}

interface Emits {
  // Define emits interface
}

// Component logic with proper separation of concerns
</script>

<style scoped>
/* Component-specific styles with Tailwind CSS */
</style>

State Management with Pinia¶

// stores/serviceRequestStore.ts
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'

export const useServiceRequestStore = defineStore('serviceRequests', () => {
  // State
  const serviceRequests = ref<ServiceRequest[]>([])
  const loading = ref(false)

  // Getters
  const openRequests = computed(() => 
    serviceRequests.value.filter(sr => sr.status === 'Open')
  )

  // Actions
  const fetchServiceRequests = async () => {
    // Implementation
  }

  return {
    serviceRequests: readonly(serviceRequests),
    loading: readonly(loading),
    openRequests,
    fetchServiceRequests
  }
})

API Development¶

RESTful API Design¶

Use proper HTTP methods (GET, POST, PUT, PATCH, DELETE)
Implement consistent response formats and status codes
Use proper resource naming conventions (plural nouns)
Implement API versioning (e.g., /api/v1/servicerequests)
Follow OpenAPI specification for documentation

Controller Implementation¶

[ApiController]
[Route("api/v1/[controller]")]
[Authorize]
public class ServiceRequestsController : ControllerBase
{
    private readonly IServiceRequestService _serviceRequestService;
    private readonly ILogger<ServiceRequestsController> _logger;

    public ServiceRequestsController(
        IServiceRequestService serviceRequestService,
        ILogger<ServiceRequestsController> logger)
    {
        _serviceRequestService = serviceRequestService;
        _logger = logger;
    }

    [HttpGet]
    [ProducesResponseType(typeof(PaginatedResponse<ServiceRequestDto>), 200)]
    public async Task<ActionResult<PaginatedResponse<ServiceRequestDto>>> GetServiceRequests(
        [FromQuery] ServiceRequestQueryParameters parameters)
    {
        var result = await _serviceRequestService.GetServiceRequestsAsync(parameters);
        return Ok(result);
    }
}

Error Handling¶

// Global exception middleware
public class GlobalExceptionMiddleware
{
    public async Task InvokeAsync(HttpContext context, RequestDelegate next)
    {
        try
        {
            await next(context);
        }
        catch (Exception ex)
        {
            await HandleExceptionAsync(context, ex);
        }
    }

    private static async Task HandleExceptionAsync(HttpContext context, Exception exception)
    {
        // Log exception and return appropriate response
    }
}

Database Development¶

Entity Framework Core Guidelines¶

Use Code First approach with migrations
Implement proper entity configurations
Use appropriate data annotations and fluent API
Implement soft deletes where appropriate
Use proper indexing for performance

Entity Configuration¶

public class ServiceRequestConfiguration : IEntityTypeConfiguration<ServiceRequest>
{
    public void Configure(EntityTypeBuilder<ServiceRequest> builder)
    {
        builder.HasKey(sr => sr.Id);

        builder.Property(sr => sr.Description)
            .IsRequired()
            .HasMaxLength(2000);

        builder.HasOne(sr => sr.Customer)
            .WithMany(c => c.ServiceRequests)
            .HasForeignKey(sr => sr.CustomerId);

        builder.HasIndex(sr => sr.Status);
        builder.HasIndex(sr => sr.Priority);
    }
}

Testing Strategy¶

Unit Testing¶

Target minimum 80% code coverage
Use xUnit for .NET testing
Use Vitest for Vue.js testing
Mock external dependencies
Test business logic thoroughly
Use AAA pattern (Arrange, Act, Assert)

Integration Testing¶

Test API endpoints with TestServer
Use in-memory databases for testing
Test complete user workflows
Validate error scenarios and edge cases

End-to-End Testing¶

Use Playwright for web application testing
Test critical user journeys
Validate cross-browser compatibility
Test mobile app functionality on real devices

Testing Examples¶

// Unit test example
[Fact]
public async Task CreateServiceRequest_WithValidData_ReturnsServiceRequest()
{
    // Arrange
    var mockRepository = new Mock<IServiceRequestRepository>();
    var service = new ServiceRequestService(mockRepository.Object);
    var createDto = new CreateServiceRequestDto { /* test data */ };

    // Act
    var result = await service.CreateAsync(createDto);

    // Assert
    Assert.NotNull(result);
    Assert.Equal(createDto.Description, result.Description);
}

Git Workflow¶

Branch Strategy¶

main: Production-ready code
develop: Integration branch for features
feature/*: Individual feature development
hotfix/*: Critical production fixes
release/*: Release preparation

Commit Standards¶

Use conventional commit format: type(scope): description
Types: feat, fix, docs, style, refactor, test, chore
Keep commits atomic and focused
Write clear, descriptive commit messages

Pull Request Process¶

Create feature branch from develop
Implement feature with tests
Update documentation as needed
Create pull request with description
Code review by at least one team member
Automated CI/CD pipeline validation
Merge after approval and passing tests

Security Guidelines¶

For comprehensive security practices, see Security Documentation

Authentication and Authorization¶

Use Azure AD (Entra ID) for identity management
Implement JWT token-based authentication
Use managed identities for service-to-service communication
Apply role-based access control (RBAC)
Implement proper token validation and refresh

Data Protection¶

Encrypt sensitive data at rest and in transit
Use Azure Key Vault for secrets management
Implement proper input validation and sanitization
Follow OWASP security guidelines
Regular security audits and vulnerability assessments

Mobile Security¶

Implement certificate pinning for API communications
Use secure storage for sensitive data
Implement proper session management
Use biometric authentication where appropriate
Regular security updates and patches

Performance Guidelines¶

Backend Performance¶

Use async/await for all I/O operations
Implement proper caching strategies (Redis, in-memory)
Optimize database queries and use proper indexing
Use pagination for large datasets
Implement connection pooling
Monitor and optimize slow queries

Frontend Performance¶

Implement lazy loading for routes and components
Use virtual scrolling for large lists
Optimize images and assets
Implement proper caching strategies
Minimize bundle sizes with code splitting
Use CDN for static assets

Mobile Performance¶

Optimize for battery life and data usage
Implement efficient synchronization strategies
Use background tasks appropriately
Optimize image handling and caching
Monitor memory usage and prevent leaks

Deployment Guidelines¶

Environment Management¶

Development: Local development environment
Testing: Automated testing and QA validation
Staging: Production-like environment for final validation
Production: Live production environment

CI/CD Pipeline¶

# Azure DevOps Pipeline example
trigger:
  branches:
    include:
      - main
      - develop

stages:
- stage: Build
  jobs:
  - job: BuildBackend
    steps:
    - task: DotNetCoreCLI@2
      inputs:
        command: 'build'
        projects: '**/*.csproj'

  - job: BuildFrontend
    steps:
    - task: Npm@1
      inputs:
        command: 'install'
        workingDir: 'src/frontend'
    - task: Npm@1
      inputs:
        command: 'custom'
        customCommand: 'run build'
        workingDir: 'src/frontend'

- stage: Test
  jobs:
  - job: RunTests
    steps:
    - task: DotNetCoreCLI@2
      inputs:
        command: 'test'
        projects: '**/*Tests.csproj'
        arguments: '--collect:"XPlat Code Coverage"'

- stage: Deploy
  condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))
  jobs:
  - deployment: DeployToProduction
    environment: 'production'
    strategy:
      runOnce:
        deploy:
          steps:
          - task: AzureWebApp@1
            inputs:
              azureSubscription: 'Azure Service Connection'
              appType: 'webApp'
              appName: 'dispatch-center-app'

Infrastructure as Code¶

Use Terraform for infrastructure provisioning
Implement proper environment separation
Use Azure Resource Manager templates where appropriate
Version control all infrastructure code
Implement infrastructure testing and validation

Monitoring and Logging¶

For detailed monitoring guidelines, see Monitoring Documentation

Implement Application Insights for performance monitoring
Use structured logging with correlation IDs
Set up proper alerting and notification systems
Monitor business metrics and KPIs
Regular performance and security reviews

Document Version: 1.0
Last Updated: January 2026
Next Review: April 2026

🔒 Security Documentation - Comprehensive security guidelines
📊 Monitoring Documentation - Application and infrastructure monitoring
🚨 Alerting Documentation - Incident response and alerting
🔄 Integration Patterns - System integration guidelines
💻 C# Best Practices - Backend development best practices
🎨 Vue.js Best Practices - Frontend development best practices
📖 Data Modeling - Database design and modeling guidelines