Development

Development Guide

This page provides guidelines and information for developers working on the Cloud-Native E-commerce Platform.

Development Environment Setup

Prerequisites

• .NET 8 SDK
• Docker Desktop
• Node.js 18+ (React microfrontends via Nx)
• Git
• IDE (VS Code or Visual Studio)

Getting Started

1. Clone the repository

   git clone https://github.com/sloweyyy/cloud-native-ecommerce-platform.git
   cd cloud-native-ecommerce-platform

2. Start infrastructure services

   docker-compose up -d mongodb redis postgres sqlserver rabbitmq elasticsearch kibana

3. Build the solution

   dotnet build Ecommerce.sln

4. Run individual services

   Each service can be run independently. Open separate terminal windows for each service:

   # Catalog API
   cd Services/Catalog/Catalog.API
   dotnet run
   
   # Basket API
   cd Services/Basket/Basket.API
   dotnet run
   
   # Discount API
   cd Services/Discount/Discount.API
   dotnet run
   
   # Ordering API
   cd Services/Ordering/Ordering.API
   dotnet run
   
   # API Gateway
   cd ApiGateways/Ocelot.ApiGateway
   dotnet run

5. Run the frontend (legacy Angular)

cd client
npm install --legacy-peer-deps
npm start

6. Run the microfrontend workspace (React + Nx)

cd ecommerce-micro-frontend
npm install
npm start  # starts host and remotes via Nx

Project Structure

The project spans microservices, legacy Angular, and a React + Nx microfrontend workspace:

├── ApiGateways/                 # API gateway layer (Ocelot)
├── Infrastructure/              # Shared infrastructure components
├── Services/                    # Microservices (Basket, Catalog, Discount, Ordering)
├── client/                      # Legacy Angular SPA
├── ecommerce-micro-frontend/    # React + Nx microfrontends (host + remotes)
├── Deployments/                 # Kubernetes/Helm manifests, monitoring assets
├── docker-compose.yml           # Local compose for APIs/dbs
├── PostmanCollection/           # API testing collections
└── images/                      # Documentation images

Each microservice follows Clean Architecture with these layers:

• API Layer: Controllers and external interfaces
• Application Layer: Business workflows and application logic
• Core/Domain Layer: Business entities and rules
• Infrastructure Layer: Technical implementations and external concerns

Each microservice follows Clean Architecture with these layers:

• API Layer: Controllers and external interfaces
• Application Layer: Business workflows and application logic
• Core/Domain Layer: Business entities and rules
• Infrastructure Layer: Technical implementations and external concerns

Coding Standards

.NET Guidelines

• Follow Microsoft's C# Coding Conventions
• Use meaningful variable and method names
• Write XML documentation for public APIs
• Follow SOLID principles
• Use dependency injection appropriately

Angular Guidelines (Legacy Client)

• Follow Angular Style Guide
• Use TypeScript strictly
• Write unit tests for components and services
• Follow reactive patterns with RxJS

React + Nx Guidelines (Microfrontends)

• Use TypeScript and Nx project conventions
• Shared packages: @ecommerce-platform/auth-provider, @ecommerce-platform/app-injector, @ecommerce-platform/shared-layout
• Routing via TanStack Router; keep route definitions in host/remotes aligned
• Ensure remotes expose correct module federation entries and versions
• Prefer React Query for data fetching; maintain cache keys per domain
• Keep env injection/build steps consistent with workspace scripts

General Principles

• Clean Architecture: Maintain separation of concerns
• SOLID Principles: Write maintainable, extensible code
• DRY: Don't repeat yourself
• YAGNI: You ain't gonna need it
• Testing: Write tests for new functionality

Testing

Unit Testing

# Run all tests
dotnet test

# Run tests with coverage
dotnet test --collect:"XPlat Code Coverage"

# Frontend tests
cd client
npm test

Integration Testing

Integration tests are located in each service's test project.

# Run integration tests
dotnet test --filter "Category=Integration"

API Testing

Use the Postman collections in the PostmanCollection/ directory for testing APIs.

Debugging

Backend Services

1. Visual Studio:

   • Open Ecommerce.sln
   • Set startup project to the service you want to debug
   • Press F5 to start debugging

2. VS Code:

   • Open the service folder
   • Use the .vscode/launch.json configuration
   • Press F5 to start debugging

Frontend

1. Angular DevTools:

   • Install the Angular DevTools browser extension
   • Use Chrome DevTools for debugging

2. VS Code:

   • Use the Debugger for Chrome extension
   • Configure launch.json for Angular debugging

Working with Docker

Building Images

# Build all images
docker-compose build

# Build specific service
docker-compose build catalog.api

Running with Docker

# Run all services
docker-compose up -d

# Run specific service
docker-compose up -d catalog.api

# View logs
docker-compose logs -f

Working with Kubernetes/Helm

• One-command local deploy: ./deploy.sh
• Start existing deployment (ports + frontend): ./start.sh
• Cleanup: ./cleanup.sh
• Helm charts: Deployments/helm/
• Raw manifests: Deployments/k8s/
• Service access helper: ./access-services.sh (auto-detects namespaces/services; updated port mappings for Grafana/Jaeger/Kiali)
• Grafana/Prometheus fixes and validators: Deployments/monitoring/grafana/*, ./validate-grafana-fix.sh, ./monitor-grafana-health.sh

Microfrontends (React + Nx)

• Workspace: ecommerce-micro-frontend/
• Ports: host (4200), store (4201), checkout (4202), account (4203), admin (4204)
• Shared packages: @ecommerce-platform/auth-provider, @ecommerce-platform/app-injector, @ecommerce-platform/shared-layout
• Routing: TanStack Router across host/remotes
• Build/test: npm run build, npm test

Load Testing

• k6 suite: tests/k6
• Grafana dashboard JSON: Deployments/monitoring/grafana/grafana-dashboard-k6.json
• Prometheus scrape config aligned for k6 outputs

Common Development Tasks

Adding a New API Endpoint

1. Define the request/response models in the Application layer
2. Create a command/query in the Application layer
3. Implement the handler in the Application layer
4. Add the controller endpoint in the API layer
5. Update the API Gateway configuration if needed

Adding a New Entity

1. Define the entity in the Core layer
2. Add repository interface in the Core layer
3. Implement repository in the Infrastructure layer
4. Configure entity mapping in the Infrastructure layer
5. Create DTOs and mappers in the Application layer
6. Add API endpoints in the API layer

Adding a New Event

1. Define the event in the EventBus.Messages project
2. Implement the publisher in the source service
3. Implement the consumer in the target service
4. Register the consumer in the target service's Program.cs

Branching Strategy

We follow the GitFlow branching model:

• main: Production-ready code
• develop: Latest development changes
• feature/*: New features
• bugfix/*: Bug fixes
• release/*: Release preparation
• hotfix/*: Production hotfixes

Pull Request Process

1. Create a branch from develop for your feature/fix
2. Make your changes following the coding standards
3. Write tests for your changes
4. Update documentation as needed
5. Submit a pull request to develop
6. Ensure CI passes
7. Get approval from at least one reviewer

Continuous Integration

Our GitHub Actions workflows automate:

• Building the solution
• Running tests
• Linting code
• Building Docker images
• Validating Kubernetes manifests and Helm charts

See .github/workflows/ for the CI configuration.