Documentation

adrs/README.md

Architectural Decision Records (ADRs)

This directory contains Architectural Decision Records for the Acsis Core repository, documenting the evolution and implementation of the Dynaplex architectural system.

What are ADRs?

Architectural Decision Records (ADRs) are short text documents that capture important architectural decisions made during the development of this project. Each ADR describes the context, decision, and consequences of a particular architectural choice.

ADR Format

Each ADR follows this template:

  • Title: Short, descriptive title
  • Status: Proposed, Accepted, Deprecated, or Superseded
  • Context: The situation that required a decision
  • Decision: The change being proposed or enacted
  • Consequences: The positive and negative outcomes of the decision

Current ADRs

ADR Title Status
001 Adoption of Polylith Architecture for .NET Accepted
002 Use .Spec Suffix for Interface Projects Superseded
003 Dynamic Component Loading with Assembly Load Context Superseded
004 Roslyn Analyzer for Architectural Rule Enforcement Accepted
005 Adoption of .slnx Solution Format Accepted
006 Centralized MSBuild Configuration with Directory.Build.props Accepted
007 Evolution of Dynaplex - From Dynamic Loading to Microservices Accepted
008 .NET 9.0 with Latest C# Features Superseded
009 Database Schema per Service Pattern Accepted
010 JWT Bearer Authentication Standard Accepted
011 Flexible API Versioning Strategy Accepted
012 Phasing Out Enterprise Library Data Accepted
013 Minimal APIs with Static Classes Accepted
014 TypedResults for Type-Safe Responses Accepted
015 Extension Methods for Endpoint Registration Accepted
016 Endpoint Grouping and Tagging Strategy Accepted
017 OpenAPI Metadata Enrichment Accepted
018 Removing MediatR and CQRS Patterns Accepted
019 OpenTelemetry Integration Accepted
020 Container-Aware Configuration Accepted
021 Microsoft Kiota for API Client Generation Accepted
022 Scalar API Documentation Accepted
023 Component Service Registration Pattern Accepted
024 FluentValidation Strategy Accepted
025 System.Text.Json Standardization Accepted
026 Structured Logging and Observability Accepted (In Progress)
027 Event-Driven Architecture Accepted
028 RBAC Migration Accepted (In Progress)
029 .NET 10 LTS Migration Accepted (Completed)
030 Distributed Caching Strategy Accepted
031 API Gateway Pattern Accepted
032 Unit of Measure System Accepted
033 Base Orchestration Pattern - Shared Infrastructure and Component Composition Accepted
034 GUID Primary Keys Accepted
035 Prism Journal Tables Accepted
036 Database Project Separation Accepted
037 Explicit Tenant Scope Operations Accepted
038 Permission Discovery Service References Accepted
039 Next.js API Proxy Pattern Accepted
040 HTML-First UI Architecture Accepted
041 BBU Processing Hardening Patterns Accepted
042 MQTT Message Delivery Architecture for IoT Devices Accepted
043 Azure Infrastructure Architecture for Dynaplex Accepted
044 PostgreSQL Public Access (Non-VNet Integration) Accepted
045 VNet Service Endpoints for External Storage Access Accepted
046 Library Projects in Dynaplex Accepted
047 Static Message Id Strategy for UI Translations Accepted
048 Agent-Driven Local Dev Stack with Docker Compose and Playwright Proposed
049 Stream-Centric Zebra RFID Architecture Accepted
050 Central Package Management with Directory.Packages.props Accepted
051 MSBuild Component Reference Properties Accepted
052 Semantic Versioning Strategy with Nerdbank.GitVersioning Proposed
053 Git Workflow Guidelines Proposed
054 Commit Message Guidelines and Conventions Proposed
055 Agent Teams Integration Accepted
056 E2E Test Infrastructure Conventions Accepted
057 Host-Build Docker Compose Architecture Accepted
058 Agent Specialization and Domain Ownership Exploratory
059 SAP Integration Architecture Accepted
060 Linear Notification System for Agent Sessions Accepted
061 Development Data Seeding Protocol Accepted
062 Testcontainers Integration Testing Accepted

Contributing

When making significant architectural decisions:

  1. Create a new ADR using the next sequential number
  2. Use the template format
  3. Discuss with the team before marking as "Accepted"
  4. Update this README with the new ADR

Template

# ADR-XXX: [Title]

## Status

[Proposed | Accepted | Deprecated | Superseded]

## Context

[Describe the situation that required a decision]

## Decision

[Describe the decision that was made]

## Consequences

[Describe the positive and negative outcomes]