Vertical.Slices.Coaches 1.0.0

Coaches Platform

A modern coaching platform built with .NET 9, featuring vertical slice architecture, microservices patterns, and event-driven messaging.

🏗️ Repository Overview

This is a .NET repository implementing Vertical Slice Architecture with two main applications:

🎯 Main Applications

1. API (src/Api/) - RESTful API backend

   • Built with ASP.NET Core and .NET 9
   • Handles authentication, business logic, and data management
   • Serves endpoints for the coaching platform
   • Includes background job processing with Hangfire

2. Dashboard (src/Dashboard/) - Admin interface

   • React + TypeScript frontend with .NET host
   • Administrative interface for managing the API
   • Real-time monitoring and management capabilities
   • Built with Vite and Tailwind CSS

🧩 Architecture Highlights

• Vertical Slice Architecture: Features organized as self-contained slices
• Event-Driven Messaging: Using Wolverine and RabbitMQ
• Modern .NET Patterns: CQRS, Clean Architecture, Domain Events
• Comprehensive Testing: Unit, Integration, and Functional tests
• Containerized Development: Docker Compose for local development
• Observability: OpenTelemetry, Serilog, and .NET Aspire dashboard

🚀 Quick Start

Prerequisites

• .NET 9 SDK - Download here
• Docker & Docker Compose - Install Docker
• Node.js 20+ - Download here (for Dashboard frontend)
• Git - Install Git

Optional (Docker provides these):

• PostgreSQL
• RabbitMQ

🐳 Docker Compose Command Note

This project uses Docker Compose V2 syntax (docker compose with a space). If you're using an older Docker installation, you may need to use the legacy format (docker-compose with a hyphen).

Modern Docker installations (recommended):

docker compose up -d

Legacy Docker installations:

docker-compose up -d

The setup script automatically detects which format your system supports.

Build

# Build the entire solution
dotnet build -tl

# Or use the VS Code task
# Ctrl+Shift+P → "Tasks: Run Task" → "build"

🔧 Initial Setup

Option 1: One-Command Setup (Recommended)

# Clone and setup everything automatically
git clone https://github.com/Eftiand/vertical-slices.coaches.git
cd coaches
./scripts/setup.sh

The setup script will:

• ✅ Check all prerequisites
• 📄 Create config-overrides.json with generated JWT secret
• 🐳 Start PostgreSQL and RabbitMQ containers
• 📦 Install .NET and npm dependencies
• 🗄️ Set up the database
• 🔨 Build the solution

Option 2: Manual Setup

1. Clone the repository

   git clone https://github.com/Eftiand/vertical-slices.coaches.git
   cd coaches
   

2. Set up configuration

   # Create local configuration file (not tracked by git)
   touch config-overrides.json
   

   Add your settings to config-overrides.json:

   {
     "Jwt:SecretKey": "your-super-secret-jwt-key-at-least-32-characters-long",
     "Google:ClientId": "your-google-client-id",
     "Google:ClientSecret": "your-google-client-secret",
     "ConnectionStrings:Postgres": "Host=localhost;Database=coaches-db;Username=postgres;Password=postgres"
   }
   

3. Start infrastructure services

   # Start PostgreSQL and RabbitMQ
   docker compose up postgres rabbitmq -d
   

4. Install dependencies and build

   # Restore NuGet packages
   dotnet restore
   
   # Build the solution
   dotnet build -tl
   

5. Set up database

   # Apply database migrations
   dotnet ef database update --project src/Application --startup-project src/Api
   

6. Install dashboard dependencies

   # Navigate to dashboard app
   cd src/Dashboard/dashboard-app
   
   # Install npm packages
   npm install
   
   # Return to root
   cd ../../../
   

🚀 Run the Application

Run with Docker Compose

# Start all services (recommended for development)
docker compose up -d

# Or run individual services
docker compose up postgres rabbitmq -d

Run with .NET Aspire (Recommended)

# Navigate to Aspire host
cd src/AppHost/Aspire

# Run with hot reload
dotnet watch run

# Opens Aspire dashboard at http://localhost:17237
# API available at http://localhost:5001
# Dashboard UI at http://localhost:5002

Run Individual Services

# API only
cd src/Api
dotnet watch run

# Dashboard only
cd src/Dashboard
dotnet watch run

🏗️ Architecture

This solution implements Vertical Slice Architecture with modern .NET patterns:

Project Structure

src/
├── Api/                    # HTTP API & endpoints
├── Application/            # Business logic & domain
│   ├── Common/            # Shared utilities & base classes
│   ├── Infrastructure/    # Data access & external services
│   └── Modules/           # Feature modules (vertical slices)
├── AppHost/               # .NET Aspire orchestration
│   ├── Aspire/           # Main host application
│   └── Aspire.ServiceDefaults/  # Shared configurations
└── Dashboard/             # React frontend with .NET host
    └── dashboard-app/     # React + TypeScript + Vite

Core Technologies

• .NET 9 - Latest .NET with native AOT support
• ASP.NET Core - Web API framework
• Entity Framework Core - Data access with PostgreSQL
• Wolverine - Messaging framework (successor to MassTransit)
• RabbitMQ - Message broker for event-driven architecture
• Hangfire - Background job processing
• FluentValidation - Request validation
• Mapster - Object mapping
• React + TypeScript - Modern frontend stack
• Vite - Fast frontend build tool
• Tailwind CSS - Utility-first CSS framework

Key Patterns

• Vertical Slice Architecture - Features organized as self-contained slices
• CQRS - Command Query Responsibility Segregation
• Event-Driven Architecture - Domain events and integration events
• Repository Pattern - Data access abstraction
• Mediator Pattern - Decoupled request/response handling
• Clean Architecture - Dependency inversion and separation of concerns

⚙️ Configuration

Environment Setup

Create a config-overrides.json file in the root directory:

touch config-overrides.json

This file overrides settings in appsettings.json and is not tracked by git. Example:

{
  "Google:ClientId": "your-google-client-id",
  "Google:ClientSecret": "your-google-client-secret",
  "Jwt:SecretKey": "your-jwt-secret-key",
  "ConnectionStrings:Postgres": "Host=localhost;Database=coaches-db;Username=postgres;Password=postgres"
}

Required Configuration

The following settings are required for full functionality:

• Google OAuth - For social login
• JWT Secret - For token generation
• PostgreSQL - Database connection
• RabbitMQ - Message broker connection
• Hangfire - Background job processing

Docker Configuration

The docker-compose.yml includes:

• PostgreSQL database with pgAdmin
• RabbitMQ with management UI
• Automatic network configuration
• Volume persistence

🚀 Development

Feature Development

This project uses Vertical Slice Architecture. Each feature is a self-contained slice with:

src/Application/Modules/{Domain}/Features/{FeatureName}/
├── {FeatureName}Command.cs     # Command, handler, and validator
├── {FeatureName}Endpoint.cs    # HTTP endpoint
├── {FeatureName}Event.cs       # Domain events (optional)
└── {FeatureName}Tests.cs       # Tests

Creating New Features

Use the interactive script (recommended):

./scripts/new-feature.sh

Or create features directly:

# Create a command feature
./scripts/new-feature.sh CreateUser Users command

# Create an event feature
./scripts/new-feature.sh UserCreated Users event

Using Templates Directly

# Create a command feature
dotnet new coaches-feature --feature CreateUser --group Users

# Create an event feature
dotnet new coaches-feature --feature UserCreated --group Users --featureType event

Development Commands

# Format code (required before commits)
dotnet csharpier .

# Run tests
dotnet test

# Generate database migration
./scripts/migration.sh AddNewTable

# Update database schema
dotnet ef database update --project src/Application --startup-project src/Api

🧪 Testing

The solution includes comprehensive testing strategies:

Test Projects

• Application.FunctionalTests - End-to-end workflow testing
• Domain.UnitTests - Unit tests for domain logic
• Infrastructure.IntegrationTests - Infrastructure and external service testing

Test Patterns

• Integration Tests - Use IntegrationTest base class with test containers
• Functional Tests - Test complete workflows using Wolverine tracking
• Architecture Tests - Enforce architectural constraints with NetArchTest

Running Tests

# Run all tests
dotnet test

# Run specific test project
dotnet test tests/Application.FunctionalTests

# Run tests with coverage (if configured)
dotnet test --collect:"XPlat Code Coverage"

Test Database

Tests use Testcontainers for isolated PostgreSQL instances:

• Automatic container lifecycle management
• Database reset between tests
• Parallel test execution support

📚 Documentation

API Documentation

• OpenAPI/Swagger - Available at /openapi/v1.json
• Scalar UI - Interactive API docs in the dashboard
• Type-safe Client - Auto-generated TypeScript types for frontend

Access Points

• API Base - http://localhost:5001
• Dashboard - http://localhost:5002
• Aspire Dashboard - http://localhost:17237
• Hangfire Dashboard - http://localhost:5001/hangfire
• RabbitMQ Management - http://localhost:15672 (guest/guest)
• pgAdmin - http://localhost:5433

Monitoring & Observability

• OpenTelemetry - Distributed tracing and metrics
• Serilog - Structured logging with file and console outputs
• Health Checks - Available at /health
• Aspire Dashboard - Real-time service monitoring

Logging

The application uses Serilog for structured logging with multiple outputs:

Log Outputs

• Console - Real-time log output for development
• Files - Persistent log files with daily rotation
• OpenTelemetry - Integration with observability platforms

Log File Locations

Development (Local)

# API logs
logs/coaches-api-{date}.log

# Create logs directory if it doesn't exist
mkdir -p logs

Production (Docker)

# View logs in Docker volumes
docker volume inspect coaches_api_logs
docker volume inspect coaches_dashboard_logs

# Access logs from running containers
docker exec -it coaches-api ls -la /app/logs
docker exec -it coaches-dashboard ls -la /app/logs

# Copy logs from container to host
docker cp coaches-api:/app/logs ./api-logs
docker cp coaches-dashboard:/app/logs ./dashboard-logs

Log Format

Logs are stored in Compact JSON format for easy parsing and analysis:

{
  "@t": "2024-01-15T10:30:00.000Z",
  "@l": "Information",
  "@mt": "User {UserId} logged in at {LoggedInAt}",
  "UserId": "123e4567-e89b-12d3-a456-426614174000",
  "LoggedInAt": "2024-01-15T10:30:00.000Z",
  "Application": "coaches.api"
}

Log Retention

• File Size Limit - 10MB per file
• Retention - 7 days of rolling files
• Rolling Interval - Daily rotation

🎨 Code Style & Quality

Formatting

This project uses CSharpier for consistent code formatting:

# Install globally
dotnet tool install -g csharpier

# Format all files
dotnet csharpier .

Code Standards

• EditorConfig - Consistent coding styles across editors
• Modern C# Features - Primary constructors, records, file-scoped namespaces
• Conventional Commits - Standardized commit message format
• Architecture Tests - Automated enforcement of architectural rules

Pre-commit Requirements

Before committing code:

1. Format with CSharpier: dotnet csharpier .
2. Build successfully: dotnet build -tl
3. Pass all tests: dotnet test
4. Follow conventional commit format

🛠️ Infrastructure

Message Processing

• Wolverine - Modern messaging framework
• RabbitMQ - Reliable message broker
• Durable Messaging - Outbox/Inbox pattern for reliability
• Error Handling - Automatic retry policies and dead letter queues

Data Access

• Entity Framework Core - ORM with PostgreSQL
• Interceptors - Automatic auditing, soft delete, domain events
• Migrations - Version-controlled database schema
• Connection Resilience - Automatic retry and circuit breaker patterns

Authentication & Authorization

• ASP.NET Core Identity - User management
• JWT Bearer Tokens - API authentication
• Google OAuth - Social login
• Policy-based Authorization - Role and claim-based access control

Background Processing

• Hangfire - Reliable background job processing
• Persistent Storage - PostgreSQL-backed job storage
• Dashboard - Web-based job monitoring
• Recurring Jobs - Scheduled task support

🚢 Deployment

Docker Production

# Build production images
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

# Or build individual services
docker build -t coaches-api -f src/Api/Dockerfile .
docker build -t coaches-dashboard -f src/Dashboard/Dockerfile .

Environment Variables

Required for production deployment:

# Database
ConnectionStrings__Postgres=Host=prod-db;Database=coaches;Username=app;Password=***

# Message Broker  
ConnectionStrings__RabbitMQ=amqp://user:pass@prod-rabbitmq:5672

# Authentication
Jwt__SecretKey=***
Google__ClientId=***
Google__ClientSecret=***

# Infrastructure
ASPNETCORE_ENVIRONMENT=Production
ASPNETCORE_URLS=http://+:5000

Health Checks

Monitor application health at:

• /health - Overall application health
• /health/ready - Readiness probe
• /health/live - Liveness probe

🔧 Troubleshooting

Common Issues

Docker Compose Command Issues

# Check which Docker Compose format is available
docker compose version    # Modern format (preferred)
docker-compose version   # Legacy format

# If neither works, install Docker Compose:
# For macOS: Docker Desktop includes Docker Compose
# For Linux: Follow https://docs.docker.com/compose/install/

Build Errors

# Clear NuGet cache
dotnet nuget locals all --clear

# Restore packages
dotnet restore

# Clean and rebuild
dotnet clean && dotnet build

Database Issues

# Reset database
dotnet ef database drop --project src/Application --startup-project src/Api
dotnet ef database update --project src/Application --startup-project src/Api

# Check connection
dotnet ef dbcontext info --project src/Application --startup-project src/Api

Message Queue Issues

# Check RabbitMQ status
docker logs rabbitmq

# Reset RabbitMQ
docker compose restart rabbitmq

Logging Issues

# Check if logs directory exists and has proper permissions
ls -la logs/

# View recent API logs (development)
tail -f logs/coaches-api-$(date +%Y%m%d).log

# View logs in Docker containers
docker logs coaches-api
docker logs coaches-dashboard

# Access log files from Docker volumes
docker run --rm -v coaches_api_logs:/logs alpine ls -la /logs
docker run --rm -v coaches_api_logs:/logs alpine cat /logs/coaches-api-$(date +%Y%m%d).log

# Check disk space for log volumes
docker system df -v

Development Tips

• Use Aspire dashboard for real-time service monitoring
• Check Hangfire dashboard for background job status
• Monitor application logs through Serilog structured logging
• Use test containers for isolated testing environments

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Start for Contributors

1. Fork the repository
2. Run the setup script: ./setup.sh
3. Create a feature branch: git checkout -b feature/your-feature
4. Follow the coding guidelines and architectural patterns
5. Write tests for all new functionality
6. Format code with CSharpier: dotnet csharpier .
7. Submit a pull request with conventional commit format

Development Guidelines

• Follow Vertical Slice Architecture - Each feature is self-contained
• Use modern C# features - Primary constructors, records, file-scoped namespaces
• Write comprehensive tests - Unit, integration, and functional tests
• Follow conventional commits - Use semantic commit messages
• Format code before committing - dotnet csharpier .

For detailed guidelines, see CONTRIBUTING.md.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

For detailed implementation patterns and examples, see the coding style guide in .github/instructions/coding-style.instructions.md.