Documentation

tutorials/getting-started.md

Getting Started with Dynaplex

Welcome to Acsis Core! This guide will get you up and running with Dynaplex - our modern microservices architecture powered by .NET Aspire.

What is Dynaplex?

Dynaplex is a microservices architecture that combines:

  • Modular components with clear boundaries (.Abstractions pattern)
  • .NET Aspire orchestration for service management
  • Auto-generated API clients for type-safe communication
  • Database-per-service isolation
  • Monorepo organization for easy development

Think of it as: Microservices with monorepo convenience and compile-time safety.

Prerequisites

Required Tools

  1. .NET 9.0 SDK

    # Check your version
dotnet --version  # Should be 9.0.x or later

# Download from: https://dot.net/download

  2. IDE (choose one)

    • Visual Studio 2022 (17.12+)
    • JetBrains Rider 2024.3+
    • VS Code with C# Dev Kit

  3. Git

    git --version
  • Docker Desktop - For running PostgreSQL locally
  • Azure CLI - For deployment (az)
  • Node.js 18+ - If working on the UI component

Setup

1. Clone the Repository

git clone <repository-url>
cd acsis-core

2. Install .NET Aspire Workload

dotnet workload install aspire

This installs .NET Aspire tools for orchestration and deployment.

3. Build the Solution

# Build all components and services
dotnet build acsis-core.slnx

First build takes 2-3 minutes as it downloads NuGet packages.

Success looks like:

Build succeeded.
    0 Warning(s)
    0 Error(s)

4. Start the Application

# Run via Aspire AppHost
dotnet run --project projects/bbu-rfid/src/Acsis.Dynaplex.Projects.BbuRfid/

You'll see:

info: Aspire.Hosting.DistributedApplication[0]
      Aspire version: 9.0.0
      Distributed application starting...
      Dashboard: https://localhost:15045

5. Open the Aspire Dashboard

open https://localhost:15045

The dashboard shows:

  • All running services
  • Service health status
  • Logs from all services
  • Distributed traces
  • Resource usage

Verify Everything Works

Check Service Health

In the Aspire Dashboard:

  1. Resources tab - All services should show "Running"
  2. Console Logs - No error messages
  3. Structured Logs - Services logging startup

Test an API

Each service has a Swagger UI:

# CoreData service (example)
open https://localhost:40443/swagger

Try an API endpoint:

  • Click "GET /api/assets"
  • Click "Try it out"
  • Click "Execute"

You should get a 200 OK response.

Understanding the Structure

Repository Layout

acsis-core/
├── engines/                     # 20+ independent microservices
│   ├── core-data/               # Central data service
│   ├── identity/                # Authentication service
│   ├── workflow/                # Business process service
│   └── [17 more services]
│
├── strata/                      # Foundation libraries and tooling
│
├── cortex/                      # Agent coordination and dev tooling
│
├── projects/
│   └── bbu-rfid/                # Aspire AppHost orchestrator
│
├── acsis-core.slnx              # Solution file
│
└── docs/                        # Documentation (you are here!)

Component Structure

Each component is a complete microservice:

engines/core-data/
├── src/
│   ├── Acsis.Dynaplex.Engines.CoreData.Abstractions/   # Contract (interfaces, models)
│   ├── Acsis.Dynaplex.Engines.CoreData.Database/       # DbContext, entities, migrations
│   ├── Acsis.Dynaplex.Engines.CoreData/                # Service implementation
│   └── Acsis.Dynaplex.Engines.CoreData.ApiClient/      # HTTP client
└── test/                                         # Tests

Why this structure?

  • .Abstractions - Defines what the service does (interfaces, models)
  • .Database - Entity models and EF Core migrations
  • Main project - Implements how it's done (ASP.NET Core service)
  • .ApiClient - Auto-generated HTTP client for other services

Note: Database migrations are run by the centralized db-manager component.

How Services Communicate

Services talk to each other via HTTP using generated clients:

// In Workflow service
public class WorkflowApi
{
    private readonly ICoreDataApiClient _coreData;  // HTTP client

    public async Task ProcessAssetAsync(int id)
    {
        // Type-safe HTTP call to CoreData service
        var asset = await _coreData.GetAssetByIdAsync(id);
        // ... process asset
    }
}

Type-safe communication across services!

Development Workflow

1. Make Changes

Edit code in any component:

# Example: Edit CoreData service
code engines/core-data/src/Acsis.Dynaplex.Engines.CoreData/CoreDataApi.cs

2. Build

# Build just that component
dotnet build engines/core-data/

# Or build everything
dotnet build acsis-core.slnx

3. Run

# Restart Aspire (Ctrl+C previous run, then):
dotnet run --project projects/bbu-rfid/src/Acsis.Dynaplex.Projects.BbuRfid/

Aspire automatically rebuilds and restarts changed services.

4. Test

  • Use Swagger UI for manual testing
  • Write unit tests in test/ folders
  • Check logs in Aspire Dashboard

Common Tasks

Run Tests

# Run all tests
dotnet test acsis-core.slnx

# Run tests for one component
dotnet test engines/core-data/test/

View Logs

Option 1: Aspire Dashboard

  • Go to https://localhost:15045
  • Click "Console Logs" or "Structured Logs"

Option 2: Console output

  • Logs appear in the terminal where you ran dotnet run

Add a Component

See the detailed guide: Create a Component

Quick version:

  1. Create projects (.Abstractions, .Database, service, .ApiClient)
  2. Define interface in .Abstractions
  3. Implement in service project
  4. Register with Aspire AppHost
  5. Register Database project with db-manager (if using database)

Debug

VS Code / Visual Studio:

  1. Set breakpoints in your code
  2. Press F5 to start debugging
  3. Aspire launches with debugger attached

Rider:

  1. Right-click on Aspire AppHost project
  2. Select "Debug"
  3. Set breakpoints as needed

Troubleshooting

Build Fails

Error: "Project reference could not be found"

# Clean and rebuild
dotnet clean
dotnet build acsis-core.slnx

Error: "ACSIS0001: Cannot reference implementation project"

  • Only reference .Abstractions projects
  • Check your <ProjectReference> elements

Services Won't Start

Port already in use:

# Kill existing dotnet processes
pkill -f dotnet
# or on Windows: taskkill /F /IM dotnet.exe

Database connection failed:

# Start PostgreSQL via Docker
docker run -d --name postgres -p 5432:5432 \
  -e POSTGRES_PASSWORD=dev postgres:16

Aspire Dashboard Won't Load

# Check if it's running
curl https://localhost:15045

# Try a different port in launchSettings.json if needed

Next Steps

Now that you're set up:

  1. Build Your First Component - Learn by doing
  2. Understand Dynaplex Architecture - Deep dive
  3. Component Patterns - Best practices

Quick Reference

Task Command
Build dotnet build acsis-core.slnx
Run dotnet run --project projects/bbu-rfid/src/Acsis.Dynaplex.Projects.BbuRfid/
Test dotnet test acsis-core.slnx
Dashboard https://localhost:15045
CoreData API https://localhost:40443/swagger
Identity API https://localhost:41443/swagger

Getting Help

Welcome to Dynaplex! 🚀