reference/components/component-reference.md

Component Reference Guide

This guide provides an overview of all components in the Acsis Core Polylith architecture, their responsibilities, dependencies, and key APIs.

📋 Component Overview

Component	Purpose	Type	Dependencies
analyzers	Code quality and architectural rules	Development Tool	None
assettrak-ui	Next.js frontend application	User Interface	Foundation API
clemens	Custom business process integration	Business Logic	core-data
core-data	Database access and core models	Data Access	None
database	SQL Server database project	Database	None
events	Event publishing and notifications	Infrastructure	core-data
file-service	File upload/download management	Infrastructure	core-data
http	HTTP utilities and API helpers	Infrastructure	None
identity	Authentication and authorization	Security	core-data
importer	Data import and processing	Utility	core-data
intelligence	Reporting and analytics	Business Logic	core-data
items	Asset and item type management	Business Logic	core-data
location	Location hierarchies and management	Business Logic	core-data
logging	Centralized logging and tracing	Infrastructure	None
printing	Label and document printing	Utility	core-data
sap	SAP ERP system integration	Integration	core-data
serialization	Data serialization utilities	Utility	None
shipping	Asset shipping and logistics	Business Logic	core-data, location
system-environment	System configuration and environment	Infrastructure	core-data
workflow	Business process and workflow management	Business Logic	core-data

🏗️ Core Infrastructure Components

analyzers

Purpose: Roslyn analyzers for code quality and architectural rule enforcement

Key Features:

ACSIS0001: Prevents direct references to component implementations
Enforces Polylith architectural boundaries
Compile-time validation of interface/implementation separation

API: N/A (Build-time tool)

Usage:

<!-- Automatically included in all projects via Directory.Build.props -->
<ProjectReference Include="$(Analyzers)" OutputItemType="Analyzer" ReferenceOutputAssembly="false"/>

Dependencies: None

core-data

Purpose: Central data access layer and core business models

Key Features:

Database connection management
Core entity models (Asset, Location, User, etc.)
Data access patterns and utilities
Payload building and schema management
Common data operations

Main API: ICoreDataApi

Key Models:

Asset - Core asset entity
AssetType - Asset type definitions
Location - Location entities
User - User management
ProcessRecord - Business process records

Example Usage:

public class AssetController : ControllerBase {
    private readonly ICoreDataApi _coreData;
    
    public AssetController(ICoreDataApi coreData) {
        _coreData = coreData;
    }
    
    [HttpGet("{id}")]
    public async Task<Asset> GetAsset(int id) {
        return await _coreData.GetAssetByIdAsync(id);
    }
}

Dependencies: None (foundational component)

events

Purpose: Event publishing, notifications, and background job management

Key Features:

Event publishing to Azure Event Grid
Email and SMS notifications
Background job scheduling
Event-driven architecture support

Main API: IEventsApi

Key Models:

EventData - Event payload structure
NotificationParameters - Notification configuration
NotificationRecipient - Recipient information

Example Usage:

public class AssetService {
    private readonly IEventsApi _events;
    
    public async Task CreateAssetAsync(CreateAssetRequest request) {
        var asset = await CreateAsset(request);
        
        // Publish event for other components
        await _events.PublishAsync(new AssetCreatedEvent {
            AssetId = asset.Id,
            AssetTypeId = asset.AssetTypeId,
            CreatedBy = asset.CreatedBy
        });
    }
}

Dependencies: core-data (for event storage and user management)

http

Purpose: HTTP utilities, pagination, and API helper functions

Key Features:

HTTP client abstractions
Pagination utilities
API response models
Request/response validation
Common HTTP patterns

Main API: IHttpApi

Key Models:

PagedResponse<T> - Paginated response wrapper
PaginationOptions - Pagination configuration
OperationRequest - Standard request wrapper
OperationResponse - Standard response wrapper

Example Usage:

public class ApiController : ControllerBase {
    private readonly IHttpApi _http;
    
    [HttpGet]
    public async Task<PagedResponse<Asset>> GetAssets([FromQuery] PaginationOptions pagination) {
        return await _http.GetPagedAsync<Asset>("assets", pagination);
    }
}

Dependencies: None

identity

Purpose: User authentication, authorization, and security management

Key Features:

JWT token management
User authentication
Role-based authorization
Password management
Session management

Main API: IIdentityApi

Key Models:

User - User entity
UserAuthDetail - Authentication information
BearerTokenResponse - JWT token response
UserPermissionView - User permissions

Example Usage:

[Authorize]
public class SecureController : ControllerBase {
    private readonly IIdentityApi _identity;
    
    [HttpPost("login")]
    public async Task<BearerTokenResponse> Login(LoginRequest request) {
        return await _identity.AuthenticateAsync(request.Username, request.Password);
    }
}

Dependencies: core-data (for user storage)

🔧 Business Logic Components

items

Purpose: Asset and item type management

Key Features:

Asset lifecycle management
Item type definitions
Asset attribute management
Serial number tracking
Asset relationships

Main API: IItemsApi, IItemTypeApi

Key Models:

Asset - Asset entity
AssetType - Asset type definitions
AssetAttribute - Asset attributes
AssetTag - Asset tagging

Example Usage:

public class AssetController : ControllerBase {
    private readonly IItemsApi _items;
    
    [HttpPost]
    public async Task<Asset> CreateAsset(CreateAssetRequest request) {
        return await _items.CreateAssetAsync(request);
    }
    
    [HttpGet("{id}/attributes")]
    public async Task<List<AssetAttribute>> GetAssetAttributes(int id) {
        return await _items.GetAssetAttributesAsync(id);
    }
}

Dependencies: core-data

location

Purpose: Location hierarchies and spatial management

Key Features:

Hierarchical location structures
Location relationships
Spatial queries
Location-based asset tracking

Main API: ILocationApi

Key Models:

Location - Location entity
LocationHierarchy - Location relationships
LocationCategory - Location categorization

Example Usage:

public class LocationController : ControllerBase {
    private readonly ILocationApi _location;
    
    [HttpGet("{id}/children")]
    public async Task<List<Location>> GetChildLocations(int id) {
        return await _location.GetChildLocationsAsync(id);
    }
    
    [HttpGet("{id}/assets")]
    public async Task<List<Asset>> GetAssetsAtLocation(int id) {
        return await _location.GetAssetsAtLocationAsync(id);
    }
}

Dependencies: core-data

shipping

Purpose: Asset shipping, receiving, and logistics management

Key Features:

Shipment creation and tracking
Asset receiving workflows
Location-to-location transfers
Shipping notifications

Main API: IShippingApi

Key Models:

Shipment - Shipment entity
ShipmentToAsset - Asset-shipment relationships
ShipmentToLocation - Location-shipment relationships

Example Usage:

public class ShippingController : ControllerBase {
    private readonly IShippingApi _shipping;
    
    [HttpPost("shipments")]
    public async Task<Shipment> CreateShipment(CreateShipmentRequest request) {
        return await _shipping.CreateShipmentAsync(request);
    }
    
    [HttpPost("shipments/{id}/receive")]
    public async Task ReceiveShipment(int id) {
        await _shipping.ReceiveShipmentAsync(id);
    }
}

Dependencies: core-data, location

workflow

Purpose: Business process and workflow management

Key Features:

Process type definitions
Workflow execution
Process state management
Business rule enforcement

Main API: IWorkflowApi

Key Models:

ProcessType - Process definitions
ProcessRecord - Process instances
ProcessState - Process state tracking

Example Usage:

public class ProcessController : ControllerBase {
    private readonly IWorkflowApi _workflow;
    
    [HttpPost("processes")]
    public async Task<ProcessRecord> StartProcess(StartProcessRequest request) {
        return await _workflow.StartProcessAsync(request);
    }
    
    [HttpPost("processes/{id}/complete")]
    public async Task CompleteProcess(int id) {
        await _workflow.CompleteProcessAsync(id);
    }
}

Dependencies: core-data

🔌 Integration Components

sap

Purpose: SAP ERP system integration

Key Features:

SAP RFC connectivity
Data synchronization
Business object mapping
Transaction processing

Main API: ISapIntegrationApi

Key Models:

SapConfiguration - SAP connection settings
SapTransaction - SAP transaction data
SapBusinessObject - SAP entity mapping

Example Usage:

public class SapController : ControllerBase {
    private readonly ISapIntegrationApi _sap;
    
    [HttpPost("sync-assets")]
    public async Task SyncAssetsFromSap() {
        await _sap.SyncAssetsAsync();
    }
}

Dependencies: core-data

clemens

Purpose: Custom business process integration for Clemens workflows

Key Features:

Clemens-specific business logic
Material asset processing
Work center management
Process order handling

Main API: IClemensApi

Key Models:

ClemensProcessOrder - Process order entity
ClemensMaterialAsset - Material asset data
ClemensWorkCenter - Work center information

Example Usage:

public class ClemensController : ControllerBase {
    private readonly IClemensApi _clemens;
    
    [HttpGet("process-orders")]
    public async Task<List<ClemensProcessOrder>> GetProcessOrders() {
        return await _clemens.GetProcessOrdersAsync();
    }
}

Dependencies: core-data

🛠️ Utility Components

file-service

Purpose: File upload, download, and storage management

Key Features:

File upload/download
Blob storage integration
File metadata management
Security and validation

Main API: IUploaderApi, IDownloaderApi

Key Models:

File - File entity
FileUploadRequest - Upload request
FileDownloadResponse - Download response

Example Usage:

public class FilesController : ControllerBase {
    private readonly IUploaderApi _uploader;
    private readonly IDownloaderApi _downloader;
    
    [HttpPost("upload")]
    public async Task<File> UploadFile(IFormFile file) {
        return await _uploader.UploadFileAsync(file);
    }
    
    [HttpGet("{id}/download")]
    public async Task<FileResult> DownloadFile(int id) {
        var fileData = await _downloader.DownloadFileAsync(id);
        return File(fileData.Content, fileData.ContentType, fileData.FileName);
    }
}

Dependencies: core-data

printing

Purpose: Label and document printing services

Key Features:

Label template management
Print queue management
Printer configuration
Barcode/QR code generation

Main API: IPrintingApi

Key Models:

PrintRequest - Print job request
PrintTemplate - Print template definition
Printer - Printer configuration

Example Usage:

public class PrintController : ControllerBase {
    private readonly IPrintingApi _printing;
    
    [HttpPost("print-asset-label")]
    public async Task PrintAssetLabel(int assetId) {
        await _printing.PrintAssetLabelAsync(assetId);
    }
}

Dependencies: core-data

intelligence

Purpose: Reporting, analytics, and business intelligence

Key Features:

Dashboard statistics
Report generation
Data visualization
Analytics queries

Main API: IStatisticsApi, IReportApi

Key Models:

DashboardStatistics - Dashboard data
ReportDefinition - Report configuration
AnalyticsQuery - Analytics query structure

Example Usage:

public class ReportsController : ControllerBase {
    private readonly IStatisticsApi _statistics;
    
    [HttpGet("dashboard")]
    public async Task<DashboardStatistics> GetDashboardStats() {
        return await _statistics.GetDashboardStatisticsAsync();
    }
}

Dependencies: core-data

importer

Purpose: Data import and processing utilities

Key Features:

Excel/CSV import
Data validation
Bulk operations
Import templates

Main API: IImporterApi

Key Models:

ImportRequest - Import job request
ImportResult - Import results
ImportTemplate - Import template definition

Example Usage:

public class ImportController : ControllerBase {
    private readonly IImporterApi _importer;
    
    [HttpPost("import-assets")]
    public async Task<ImportResult> ImportAssets(IFormFile file) {
        return await _importer.ImportAssetsAsync(file);
    }
}

Dependencies: core-data

serialization

Purpose: Data serialization and transformation utilities

Key Features:

JSON serialization
XML transformation
Data format conversion
Serialization configuration

Main API: ISerializationApi

Example Usage:

public class DataController : ControllerBase {
    private readonly ISerializationApi _serialization;
    
    [HttpGet("export/{format}")]
    public async Task<string> ExportData(string format, object data) {
        return await _serialization.SerializeAsync(data, format);
    }
}

Dependencies: None

logging

Purpose: Centralized logging, tracing, and monitoring

Key Features:

Structured logging
Log aggregation
Performance tracing
Error tracking

Main API: IMessageLogger

Example Usage:

public class MyService {
    private readonly IMessageLogger _logger;
    
    public MyService(IMessageLogger logger) {
        _logger = logger;
    }
    
    public async Task DoSomething() {
        _logger.LogInformation("Starting operation");
        try {
            // Business logic
            _logger.LogInformation("Operation completed successfully");
        } catch (Exception ex) {
            _logger.LogError(ex, "Operation failed");
            throw;
        }
    }
}

Dependencies: None

system-environment

Purpose: System configuration, environment management, and application settings

Key Features:

Configuration management
Environment detection
System health monitoring
Application metadata

Main API: ISystemEnvironmentApi

Key Models:

SystemConfiguration - System settings
EnvironmentInfo - Environment details
ApplicationMetadata - App information

Example Usage:

public class SystemController : ControllerBase {
    private readonly ISystemEnvironmentApi _system;
    
    [HttpGet("health")]
    public async Task<HealthStatus> GetSystemHealth() {
        return await _system.GetHealthStatusAsync();
    }
    
    [HttpGet("config")]
    public async Task<SystemConfiguration> GetConfiguration() {
        return await _system.GetConfigurationAsync();
    }
}

Dependencies: core-data

🎨 User Interface Components

assettrak-ui

Purpose: Next.js-based frontend application

Key Features:

React-based user interface
Asset management screens
Location management
User authentication
Responsive design
Internationalization

Technology Stack:

Next.js 13+
React 18
TypeScript
Tailwind CSS
Axios for API calls

Key Components:

MainShell.tsx - Application shell
AssetGrid.jsx - Asset listing
LocationHierarchy.jsx - Location tree
SearchBar.jsx - Search functionality

Development:

cd engines/assettrak-ui/src/assettrak-ui/
npm install
npm run dev

Build:

npm run build
npm start

Dependencies: Foundation API (HTTP endpoints)

📊 Component Dependency Graph

graph TD
    Foundation[Foundation Base] --> CoreData[core-data]
    Foundation --> Identity[identity]
    Foundation --> Events[events]
    Foundation --> Items[items]
    Foundation --> Location[location]
    Foundation --> Shipping[shipping]
    Foundation --> Workflow[workflow]
    Foundation --> Intelligence[intelligence]
    Foundation --> FileService[file-service]
    Foundation --> Printing[printing]
    Foundation --> SystemEnv[system-environment]
    Foundation --> Serialization[serialization]
    Foundation --> SAP[sap]
    Foundation --> Clemens[clemens]
    Foundation --> Importer[importer]
    Foundation --> HTTP[http]
    Foundation --> Logging[logging]
    
    Identity --> CoreData
    Events --> CoreData
    Items --> CoreData
    Location --> CoreData
    Shipping --> CoreData
    Shipping --> Location
    Workflow --> CoreData
    Intelligence --> CoreData
    FileService --> CoreData
    Printing --> CoreData
    SystemEnv --> CoreData
    SAP --> CoreData
    Clemens --> CoreData
    Importer --> CoreData
    
    UI[assettrak-ui] --> Foundation
    
    Analyzers[analyzers] -.-> Foundation
    Analyzers -.-> Items
    Analyzers -.-> Location
    Analyzers -.-> AllComponents[All Components]

🔑 Key Patterns

Dependency Injection Registration

All components are automatically registered with the DI container:

// In Program.cs
services.LoadComponents(
    typeof(ICoreDataApi),
    typeof(IIdentityApi),
    typeof(IEventsApi),
    typeof(IItemsApi),
    typeof(ILocationApi)
    // ... other components
);

Error Handling Pattern

public async Task<Result<T>> DoSomethingAsync() {
    try {
        _logger.LogInformation("Starting operation");
        var result = await PerformOperation();
        _logger.LogInformation("Operation completed successfully");
        return Result.Success(result);
    } catch (Exception ex) {
        _logger.LogError(ex, "Operation failed");
        return Result.Failure(ex.Message);
    }
}

Validation Pattern

public async Task<Asset> CreateAssetAsync(CreateAssetRequest request) {
    if (request == null) throw new ArgumentNullException(nameof(request));
    
    var validationResult = await _validator.ValidateAsync(request);
    if (!validationResult.IsValid) {
        throw new ValidationException(validationResult.Errors);
    }
    
    // Proceed with creation
}

📝 Component Development Guidelines

Interface First: Always define the interface in the .Spec project before implementation
Dependency Direction: Only reference other components' .Spec projects
Logging: Use structured logging with meaningful context
Error Handling: Implement consistent error handling patterns
Validation: Validate inputs at component boundaries
Documentation: Document interfaces with XML comments
Testing: Write unit tests for component interfaces

This reference guide provides a comprehensive overview of all components in the Acsis Core architecture. Each component follows the Polylith principles while serving specific business or technical functions within the overall system.

Documentation

Component Reference Guide

📋 Component Overview

🏗️ Core Infrastructure Components

analyzers

core-data

events

http

identity

🔧 Business Logic Components

items

location

shipping

workflow

🔌 Integration Components

sap

clemens

🛠️ Utility Components

file-service

printing

intelligence

importer

serialization

logging

system-environment

🎨 User Interface Components

assettrak-ui

📊 Component Dependency Graph

🔑 Key Patterns

Dependency Injection Registration

Error Handling Pattern

Validation Pattern

📝 Component Development Guidelines