Quick Start Guide

This guide will help you set up and run the SGRH system on your local development environment.

Prerequisites

Before you begin, ensure you have the following installed:

.NET SDK 8

Download and install the .NET 8 SDKVerify installation:

dotnet --version

You should see version 8.0.x or higher.

MySQL Server

Install MySQL Server 8.0 or higher

The current code references SQL Server in Program.cs, but the README specifies MySQL. You may need to adjust the connection configuration.

Visual Studio 2022 or VS Code

Install one of the following:

Visual Studio 2022 (Community, Professional, or Enterprise)
Visual Studio Code with C# extension

If you plan to run the Desktop client, you must install Visual Studio 2022 with the .NET MAUI workload.

Git (Optional)

Install Git for version control

Installation

1. Clone or Download the Repository

git clone <repository-url>
cd SGRH

2. Restore Dependencies

Restore NuGet packages for all projects:

dotnet restore

3. Configure the Database

Update Connection String

Edit the appsettings.json file in the SGRH.Api project:

SGRH.Api/appsettings.json

{
  "ConnectionStrings": {
    "Default": "Server=localhost;Database=SGRH;User Id=your_user;Password=your_password;TrustServerCertificate=True;"
  },
  "AWS": {
    "Region": "us-east-1",
    "S3": {
      "BucketName": "your-bucket-name"
    },
    "SES": {
      "SenderEmail": "[email protected]"
    }
  },
  "Jwt": {
    "Issuer": "SGRH-DEV",
    "Audience": "SGRH-DEV",
    "Key": "YOUR_SECRET_KEY_HERE_MINIMUM_32_CHARS",
    "ExpireMinutes": 120
  },
  "AllowedHosts": "*"
}

Security Note: Never commit real credentials to version control. Use User Secrets or environment variables in production.

Configure for MySQL

If using MySQL (as per README), update Program.cs:

SGRH.Api/Program.cs

// Change from UseSqlServer to UseMySql
builder.Services.AddDbContext<SGRHDbContext>(options =>
    options.UseMySql(
        builder.Configuration.GetConnectionString("Default"),
        ServerVersion.AutoDetect(builder.Configuration.GetConnectionString("Default"))
    ));

And add the MySQL package:

dotnet add SGRH.Api package Pomelo.EntityFrameworkCore.MySql

4. Create the Database

Apply Entity Framework migrations to create the database schema:

cd SGRH.Api
dotnet ef database update

If you encounter errors, ensure your database server is running and the connection string is correct.

Running the Application

Running the API

Navigate to API Project

cd SGRH.Api

Run the Application

dotnet run

You should see output similar to:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7001
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5000

Access Swagger UI

Open your browser and navigate to:

https://localhost:7001/swagger

You should see the Swagger API documentation interface.

Running with Visual Studio

Open Solution

Open SGRH.sln in Visual Studio 2022

Set Startup Project

Right-click on SGRH.Api and select Set as Startup Project

Run the Application

Press F5 or click the Run buttonThe API will start and your browser will open to the Swagger UI automatically.

Exploring the API

Current API Status

The API controllers are currently under development. The project has a complete domain layer with rich business logic, but the HTTP endpoints are not yet implemented.

Available Endpoint

The only currently implemented endpoint is for database connectivity testing:

curl http://localhost:5000/api/test-db/ping

Response:

{
  "connected": true
}

What’s Implemented

While the API endpoints aren’t built yet, the following layers are complete:

Domain Models

All business entities with full logic

Cliente, Reserva, Habitacion
State machines and business rules
Domain policies and validation

Persistence

Complete EF Core configuration

Entity configurations
Database context
Migration support

CQRS Structure

Application layer organized

Command/Query folders
DTO structures
Ready for implementation

Clean Architecture

Proper layer separation

Domain independence
Dependency inversion
Testable design

Exploring with Swagger

The Swagger UI is available and shows the current API surface:

curl http://localhost:5000/api/test-db/ping

The Swagger UI will show the TestDbController with the /api/test-db/ping endpoint.

Running the Web Client

The Blazor web client consumes the API:

Ensure API is Running

Keep the API running in one terminal/instance

Navigate to Web Project

cd SGRH.Web/SGRH.Web

Run the Web Application

dotnet run

Access the Web Interface

Open your browser to the URL shown in the console (typically https://localhost:7002)

Running the Desktop Client

The desktop client requires Visual Studio 2022 with the .NET MAUI workload installed.

Open Solution in Visual Studio

Open SGRH.sln in Visual Studio 2022

Set Desktop as Startup Project

Right-click on SGRH.Desktop and select Set as Startup Project

Select Target Framework

Choose your target platform from the dropdown:

Windows Machine
Android Emulator
iOS Simulator (macOS only)

Run the Application

Press F5 to build and run the desktop application

Configuration

Environment-Specific Settings

SGRH supports multiple environments:

appsettings.json - Base configuration
appsettings.Development.json - Development overrides
appsettings.Production.json - Production settings

AWS Configuration

If you want to use AWS services (S3, SES):

Configure AWS Credentials

Set up AWS credentials using one of these methods:Option 1: AWS CLI

aws configure

Option 2: Environment Variables

export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_REGION=us-east-1

Update appsettings.json

"AWS": {
  "Region": "us-east-1",
  "S3": {
    "BucketName": "your-actual-bucket-name"
  },
  "SES": {
    "SenderEmail": "[email protected]"
  }
}

AWS integration is optional. The system can run without it, but file storage and email features will not be available.

JWT Authentication

Configure JWT settings in appsettings.json:

"Jwt": {
  "Issuer": "SGRH-API",
  "Audience": "SGRH-Clients",
  "Key": "your-secret-key-min-32-characters-long",
  "ExpireMinutes": 120
}

The JWT secret key must be at least 32 characters long and should be cryptographically random in production.

Troubleshooting

Database Connection Issues

Problem: Cannot connect to database Solutions:

Verify MySQL/SQL Server is running:

# MySQL
sudo systemctl status mysql

# Windows SQL Server
# Check SQL Server Configuration Manager

Test connection string:
```
dotnet ef database update --verbose
```
Check firewall settings allowing database port access

Migration Errors

Problem: dotnet ef database update fails Solutions:

Install EF Core tools globally:
```
dotnet tool install --global dotnet-ef
```
Ensure you’re in the correct directory:
```
cd SGRH.Api
```
Rebuild the solution:
```
dotnet build
```

Port Already in Use

Problem: Port 5000 or 7001 is already in use Solution: Modify launchSettings.json:

SGRH.Api/Properties/launchSettings.json

"applicationUrl": "https://localhost:7002;http://localhost:5001"

Swagger Not Loading

Problem: Swagger UI shows 404 error Solution: Ensure you’re running in Development mode:

export ASPNETCORE_ENVIRONMENT=Development  # Linux/macOS
set ASPNETCORE_ENVIRONMENT=Development     # Windows CMD
$env:ASPNETCORE_ENVIRONMENT="Development"  # Windows PowerShell

Next Steps

Architecture Deep Dive

Understand the layered architecture and design patterns

API Reference

Explore detailed API endpoint documentation

Domain Models

Learn about the core domain entities and business logic

Configuration

Configure database, authentication, and AWS services

Development Workflow

Recommended Development Setup

API First: Always start the API before client applications
Hot Reload: Use dotnet watch run for automatic recompilation
Swagger: Use Swagger UI for API testing during development
Logging: Check console output for detailed logs

Making Changes

Domain Changes

Start with domain entities and business logic in SGRH.Domain

Application Use Cases

Implement use cases in SGRH.Application

API Endpoints

Add controllers in SGRH.Api

Client Integration

Update Web/Desktop clients to consume new endpoints

Database Migrations

When you modify entities:

# Create a new migration
cd SGRH.Api
dotnet ef migrations add YourMigrationName

# Apply to database
dotnet ef database update

# Revert last migration
dotnet ef migrations remove

Support

If you encounter issues not covered in this guide:

Check the project README for updates
Review the source code comments
Consult the Architecture documentation
Verify all prerequisites are correctly installed

This system is designed for educational and development purposes. Additional configuration may be required for production deployment.

Getting Started

Architecture

Core Concepts

Configuration

​Quick Start Guide

​Prerequisites

​Installation

​1. Clone or Download the Repository

​2. Restore Dependencies

​3. Configure the Database

​Update Connection String

​Configure for MySQL

​4. Create the Database

​Running the Application

​Running the API

​Running with Visual Studio

​Exploring the API

​Current API Status

​Available Endpoint

​What’s Implemented

Domain Models

Persistence

CQRS Structure

Clean Architecture

​Exploring with Swagger

​Running the Web Client

​Running the Desktop Client

​Configuration

​Environment-Specific Settings

​AWS Configuration

​JWT Authentication

​Troubleshooting

​Database Connection Issues

​Migration Errors

​Port Already in Use

​Swagger Not Loading

​Next Steps

Architecture Deep Dive

API Reference

Domain Models

Configuration

​Development Workflow

​Recommended Development Setup

​Making Changes

​Database Migrations

​Support

Build docs developers (and LLMs) love

Quick Start Guide

Prerequisites

Installation

1. Clone or Download the Repository

2. Restore Dependencies

3. Configure the Database

Update Connection String

Configure for MySQL

4. Create the Database

Running the Application

Running the API

Running with Visual Studio

Exploring the API

Current API Status

Available Endpoint

What’s Implemented

Exploring with Swagger

Running the Web Client

Running the Desktop Client

Configuration

Environment-Specific Settings

AWS Configuration

JWT Authentication

Troubleshooting

Database Connection Issues

Migration Errors

Port Already in Use

Swagger Not Loading

Next Steps

Development Workflow

Recommended Development Setup

Making Changes

Database Migrations

Support