LeadSheet E-commerce Platform

A modern microservices-based e-commerce platform built with .NET 9, Angular, and Docker.

QuickStart

For Development (Recommended)

# Start infrastructure services only
.\devops\scripts\start-infrastructure.ps1

# Run services locally for debugging
# Services will automatically detect hybrid environment

For Full Docker Deployment

# Start all services in Docker
.\devops\scripts\start-docker.ps1

Stop All Services

.\devops\scripts\stop-services.ps1

Documentation

Complete documentation is available in the docs/ directory:

Essential Reading

• Documentation Index - Complete documentation navigation
• Environment Guide - Development environment setup (start here)
• Architecture Overview - System architecture, decisions, and constraints
• System Design Overview - Service interactions and execution flows

Development And Operations

• Development Guide - Development workflows and patterns
• Deployment Guide - Deployment strategies and environments
• Monitoring And Logging - Observability and alerting

Integration And APIs

• Cross-Service Communication - HTTP communication patterns
• Event-Driven Architecture - RabbitMQ messaging
• API Endpoints - Complete API reference

Architecture

Microservices (6 Services)

Service	Port (Dev/Docker)	Purpose
API Gateway	5041 / 8000	Ocelot-based routing and auth forwarding
UserService	5134 / 5000	OpenIddict OAuth2/OIDC, user identity, profiles
FileStorageService	5240 / 5240	MinIO file operations, metadata management
LeadService	5094 / 5003	Leadsheet catalog, pricing, metadata
PaymentService	5085 / 5002	Stripe integration, payment processing
OrderService	5141 / 5001	Order management, delivery coordination

Frontend

• Angular Application - Modern SPA with Material Design

Infrastructure

• PostgreSQL 15 - 6 logical databases (one per service)
• Redis 7.2 - Distributed cache and session storage
• RabbitMQ 3 - Event-driven messaging (exchanges: filestorage.events, payment.events, etc.)
• MinIO - S3-compatible object storage (buckets: leadsheet-files, leadsheet-user-files)
• Prometheus/Grafana - Metrics and monitoring
• Jaeger - Distributed tracing
• Loki - Centralized logging

TechnologyStack

Backend:

• .NET 9 - Microservices with Clean Architecture + CQRS
• OpenIddict 7.0 - OAuth2/OIDC authentication server
• Ocelot - API Gateway with route configuration
• Entity Framework Core 9 - Data access with code-first migrations
• MediatR - CQRS command/query handling
• FluentValidation - Request validation
• Serilog - Structured logging

Frontend:

• Angular 18+ - TypeScript SPA with reactive patterns
• Angular Material - UI component library

Infrastructure:

• Docker & Docker Compose - Containerization and orchestration
• PostgreSQL 15 - Relational database (6 logical databases)
• Redis 7.2 - Cache and session store
• RabbitMQ 3 - Message broker with management UI
• MinIO - S3-compatible object storage
• Prometheus - Metrics collection
• Grafana - Monitoring dashboards
• Jaeger - Distributed tracing
• Loki - Log aggregation

EnvironmentSupport

The platform supports multiple development environments with automatic detection:

• Hybrid (Recommended): Infrastructure in Docker + Services running locally for debugging
• Docker: Full containerized deployment for production-like testing
• Local: Traditional local development (all components on host)

Environment detection is automatic via:

• DOTNET_RUNNING_IN_CONTAINER environment variable
• ASPNETCORE_ENVIRONMENT setting
• IServiceUriProvider for dynamic service URL resolution

Configuration Pattern: Double-indirection (appsettings.json stores keys → .env provides values)

Prerequisites

• .NET 9 SDK
• Node.js 18+
• Docker Desktop
• PowerShell 7+ (for scripts)

Contributing

Getting Started

1. Read the Environment Guide for setup
2. Review Architecture Overview for system understanding
3. Check System Design Overview for service interactions
4. Start with hybrid development (infrastructure in Docker, services local) for best debugging experience

Development Workflow

• Use Clean Architecture layering: Api → Application → Domain → Infrastructure
• Follow CQRS pattern with MediatR for commands and queries
• Write integration events for cross-service communication via RabbitMQ
• Use double-indirection configuration pattern (appsettings.json → .env)
• Maintain service boundaries (database-per-service pattern)

Code Standards

• FluentValidation for request validation
• Structured logging with Serilog
• Health checks for all services (/health, /health/ready)
• OpenAPI/Swagger documentation for APIs

License

This project is licensed under the MIT License.

---

For detailed setup instructions and architecture documentation, visit the docs/ directory.