🇺🇸 English | 🇪🇸 Español

Hi, I'm Erickson Lopez 👋

Software Engineer & Architect

• Welcome to the Ecosystem
• Repository Matrix
• Architecture Map
• Technology Landscape
• Engineering Principles
• Repository Standards
• Recommended Reading Order
• Current Initiatives & Roadmap
• Contributing
• License

Each repository here exists because it solves a concrete problem that surfaces in enterprise software engineering. Together they form an interconnected ecosystem where:

• 📦 Libraries (dotnet-shared-kernel, dapper-extensions-pg) provide reusable abstractions.
• 🏗️ Reference implementations (dotnet-enterprise-api, angular-enterprise-app) demonstrate how these libraries compose into robust applications.
• 🔬 Labs (postgresql-lab) provide reproducible benchmarks with measured EXPLAIN ANALYZE output—not just theory.
• 🧪 Testing patterns (testing-patterns-dotnet) explore the spectrum from unit to architecture testing.
• 📖 Documentation (engineering-handbook) records every architectural decision with direct links to the code that implements it.

Here is the current layout of the ecosystem. Every project is actively maintained and backed by continuous integration.

Repository	Type	Language	Status	CI	Description
dotnet-shared-kernel	📦 Library	C# / .NET 10			BaseEntity, Result<T>, ValueObject, Specification.
dapper-extensions-pg	📦 Library	C# / .NET 10			UNNEST bulk ops, keyset pagination, advanced type handlers.
testing-patterns-dotnet	📚 Reference	C# / .NET 10			5 chapters: Unit → Integration → Mutation → Architecture testing.
dotnet-enterprise-api	🏗️ Template	C# / .NET 10			Clean Architecture + CQRS + JWT + Minimal APIs.
angular-enterprise-app	🏗️ Template	TypeScript			Angular 22 + Signals + Tailwind 4 — Dashboard, CRUD, Auth.
postgresql-lab	🔬 Lab	SQL			10 labs, 2.2M rows, real EXPLAIN ANALYZE benchmarks.
engineering-handbook	📖 Docs	Markdown		—	ADRs, design principles, and operational runbooks.

The ecosystem is designed to be highly cohesive. This dependency map shows how the pieces interact.

graph TB
    subgraph docs["📖 Documentation"]
        EH["engineering-handbook<br/><i>ADRs · Principles · Runbooks</i>"]
    end

    subgraph libs["📦 Libraries (NuGet)"]
        SK["dotnet-shared-kernel<br/><i>Result&lt;T&gt; · BaseEntity · Specification</i>"]
        DE["dapper-extensions-pg<br/><i>UNNEST · Pagination · TypeHandlers</i>"]
    end

    subgraph apps["🏗️ Applications"]
        API["dotnet-enterprise-api<br/><i>Clean Architecture · CQRS · JWT</i>"]
        SPA["angular-enterprise-app<br/><i>Angular 22 · Signals · Tailwind 4</i>"]
    end

    subgraph data["🔬 Data & Testing"]
        PG["postgresql-lab<br/><i>10 labs · EXPLAIN ANALYZE</i>"]
        TP["testing-patterns-dotnet<br/><i>Unit → Mutation → Architecture</i>"]
    end

    SK -->|NuGet dependency| API
    DE -->|NuGet dependency| API
    SPA -->|HTTP / JWT| API
    API -->|SQL| PG
    TP -.->|patterns applied in| API
    EH -.->|documents decisions in| API
    EH -.->|documents decisions in| SPA
    PG -.->|benchmarks inform| DE

    classDef lib fill:#1f3a5f,stroke:#58a6ff,color:#fff,rx:5px,ry:5px
    classDef app fill:#1a3a2a,stroke:#2ea043,color:#fff,rx:5px,ry:5px
    classDef data fill:#3a2a1a,stroke:#d29922,color:#fff,rx:5px,ry:5px
    classDef doc fill:#2a1a3a,stroke:#a371f7,color:#fff,rx:5px,ry:5px

    class SK,DE lib
    class API,SPA app
    class PG,TP data
    class EH doc

Rather than listing every tool, here are the core technologies and patterns that define this ecosystem's architecture, performance, and security.

• Backend Framework: .NET 10 (C# 13) — Clean Architecture, Domain-Driven Design (Rich Domain Models).
• Frontend Framework: Angular 22 (TypeScript) — Modular, Standalone Components, Signals, Tailwind CSS 4.
• Design Patterns: Result Pattern (error handling), CQRS (MediatR), Specification, Outbox Pattern.

• Database: PostgreSQL 17 — Advanced usage of JSONB, Full-Text Search (GIN), Keyset Pagination (0.31ms at page 25k).
• Data Access: Dapper (Micro-ORM) — Zero magic, explicit queries. Uses UNNEST arrays for 125k rows/sec insert throughput.
• Caching & Messaging: Redis for distributed caching; RabbitMQ / Kafka for event-driven flows.

• Cryptography: BCrypt for hashing; DPAPI, AES, and Shamir Secret Sharing for advanced secret management.
• DevSecOps Pipeline: GitHub Actions integrated with SonarQube, CodeQL, Trivy, and Gitleaks for automated auditing.
• Testing Mastery: xUnit, AutoFixture, Bogus for unit/integration; Testcontainers for I/O; Stryker.NET for mutation testing.

• Infrastructure as Code: Docker, Terraform, with a roadmap towards Kubernetes orchestration.
• Observability: OpenTelemetry distributed tracing and structured logging for production readiness.

• 🎯 Explicit over implicit: We use Result<T> instead of throwing exceptions for business logic. We write raw SQL instead of relying on opaque ORM generation.
• 🧩 Composition over inheritance: The shared kernel provides lean abstractions consumed by the Enterprise API without deep inheritance chains.
• 📊 Measure, don't guess: Every performance claim is backed by postgresql-lab benchmarks (e.g., proving UNNEST's 125k rows/sec throughput).
• 📝 Document the 'Why': The engineering-handbook houses Architecture Decision Records (ADRs) to explain reasoning, not just outcomes.
• 🧪 Test behavior, not implementation: Unit tests verify strict domain rules; integration tests verify API contracts.

Consistency is key across the ecosystem. Every repository strictly adheres to these baselines.

Every repo features a standard layout: src/, tests/ (Unit/Integration), docs/, a comprehensive README.md, .github/workflows/ci.yml, and an .editorconfig.

Every repository includes the full OSS governance suite: LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, CHANGELOG.md, issue templates, PR template, and Dependabot.

• Builds: TreatWarningsAsErrors = true across all .NET projects.
• Coverage: 100% test coverage target for domain invariants.
• CI/CD: Trunk-based development where main is always deployable. .NET repos share a reusable workflow for build & test, reducing CI duplication.
• Performance: Sub-millisecond pagination, < 5ms FTS query times, and highly optimized Angular lazy-loading bundles (< 1.5 MB initial load).

If you're exploring the ecosystem for the first time, I recommend this path to see how the pieces fit together:

1. 📖 Clean Architecture Principles — Understand the core layers and dependency rules.
2. 📦 dotnet-shared-kernel — Review the foundational Result<T>, BaseEntity, and ValueObject types.
3. 📦 dapper-extensions-pg — Explore the high-performance PostgreSQL extensions (UNNEST, Keyset).
4. 🔬 postgresql-lab — See the raw SQL benchmarks that validate the data access decisions.
5. 🏗️ dotnet-enterprise-api — Discover how the kernel and data access compose into a Clean Architecture API.
6. 🏗️ angular-enterprise-app — Check out the modern Angular 22 Signals implementation consuming the API.
7. 📚 testing-patterns-dotnet — Dive deep into the testing strategies keeping the code robust.

The ecosystem is built to scale to 20+ repositories without losing cohesion.

• Publish dotnet-shared-kernel and dapper-extensions-pg to NuGet.org
• Enhance integration test coverage in dotnet-enterprise-api with Testcontainers
• Add CODE_OF_CONDUCT.md (Contributor Covenant v2.1) to all repositories
• Implement reusable GitHub Actions workflows across .NET repositories
• Add code coverage reporting to angular-enterprise-app CI
• Deploy Stryker mutation reports to GitHub Pages (testing-patterns-dotnet)
• Introduce E2E tests (Playwright) to angular-enterprise-app

• 📡 Observability: OpenTelemetry distributed tracing across the API and PostgreSQL.
• 📬 Event-Driven Architecture: Outbox pattern and message broker integration.
• 🏢 Multi-Tenant Patterns: Schema-per-tenant architecture relying on the shared kernel.
• 🚢 Deployment Recipes: Progression from Docker Compose to full Kubernetes manifests.

While this ecosystem serves primarily as a personal reference architecture and engineering playground, constructive discussions, suggestions, and feedback are always welcome. Feel free to open an Issue in the relevant repository if you spot a bug or want to discuss a specific architectural pattern.

This ecosystem and its repositories are open-sourced software licensed under the MIT License. You are free to use these architectural patterns and reference implementations in your own projects.

engineering-handbook · Designed & built with care by Erickson Lopez.