Skip to content

Modularization

This document defines ConnectSoft's modularization philosophy. It is written for architects and engineers designing systems that scale to thousands of modules without coupling complexity.

Modularization is the universal building block philosophy at ConnectSoft. We treat "module" as a universal concept that applies to microservices, agents, templates, libraries, events, and documentation—each independently understandable, reusable, replaceable, and observable.

Tip

The goal is to scale to 3,000+ modules without drowning in coupling. Clear separation between microservice templates, library templates, agent modules, and DevOps/IaC modules enables the Factory to recombine pieces into many different SaaS products.

Why Modularization Matters

Modularization is essential for:

Scalability

  • Independent scaling - Each module scales independently based on load
  • Parallel development - Teams can work on different modules simultaneously
  • Horizontal growth - Add new modules without affecting existing ones

Maintainability

  • Clear boundaries - Each module has a well-defined purpose and interface
  • Isolated changes - Changes to one module don't break others
  • Easier debugging - Problems are contained within module boundaries

Independent Evolution

  • Version independently - Modules evolve at their own pace
  • Replace without disruption - Swap modules without affecting the system
  • Technology diversity - Different modules can use different technologies (within constraints)

Agent Generation

  • Template-driven - Each module type has its own template
  • Predictable structure - Agents know exactly what to generate
  • Composable - Modules combine into larger systems

Bounded Contexts and Services

At ConnectSoft, DDD bounded contexts map directly to deployable services:

Bounded Context → Microservice

One bounded context = One microservice

  • Each bounded context is independently deployable
  • Each bounded context has its own domain model
  • Each bounded context owns its own data

Example: Invoice bounded context becomes Invoice microservice

Bounded Context → Library

Shared bounded contexts become libraries

  • Common functionality (logging, HTTP, OAuth) becomes shared libraries
  • Libraries are versioned independently
  • Libraries are used by multiple microservices

Example: Identity bounded context becomes Identity library used by all services

Shared Kernel (When Necessary)

Shared kernel only when absolutely required

  • Avoid shared kernels—they create coupling
  • Prefer libraries for shared functionality
  • Use events for cross-context communication

Example: Common value objects (Money, Address) become shared library, not shared kernel

Types of Modules

ConnectSoft recognizes several types of modules, each following the same principles:

Module Type Description Examples
Domain Services Business logic modules within a bounded context InvoiceService, PaymentService, NotificationService
Shared Libraries Reusable functionality across contexts ConnectSoft.Extensions.Logging, ConnectSoft.Extensions.Http
Infrastructure Modules Technical capabilities (messaging, persistence) EventBus, Repository, ExternalServiceClient
UI Modules Frontend components and pages Dashboard, Login, Settings (future)
Agent Modules Specialized AI agents ArchitectAgent, EngineeringAgent, QAAgent
Template Modules Code generation templates MicroserviceTemplate, LibraryTemplate
Event Modules Event schemas and handlers InvoiceCreatedEvent, PaymentProcessedEvent

Module Characteristics

All modules share these characteristics:

  • Independently understandable - Can be understood without deep context
  • Reusable - Can be composed into different products
  • Replaceable - Can be swapped without breaking the system
  • Observable - Expose metrics, logs, and traces

Modularization Guidelines

Follow these guidelines when designing modules:

Keep Domain Logic in Its Own Context

  • One domain = One module - Don't mix domains in a single module
  • Clear boundaries - Domain boundaries should be obvious
  • No shared domain models - Each context has its own domain model

Avoid Shared Databases

  • Database per service - Each microservice has its own database
  • No shared tables - Don't share database tables between services
  • Use events for data sync - Synchronize data via events, not shared databases

Use Events for Cross-Context Communication

  • Domain events - Use domain events within a bounded context
  • Integration events - Use integration events between bounded contexts
  • No direct calls - Avoid direct service-to-service calls for business logic

Keep Modules Small and Focused

  • Single responsibility - Each module has one clear purpose
  • Small interfaces - Minimal, well-defined interfaces
  • High cohesion - Related functionality grouped together

Version Modules Independently

  • Semantic versioning - Use semantic versioning for all modules
  • Backward compatibility - Maintain backward compatibility when possible
  • Clear deprecation - Deprecate old versions clearly

Tip

Do: Design modules with clear boundaries, use events for communication, version independently. Don't: Share databases, create shared kernels, mix domains in one module, create circular dependencies.

Example Modularization Pattern

Here's how ConnectSoft platforms are modularized:

flowchart TD
    subgraph "Identity Bounded Context"
        IDENTITY[Identity Microservice<br/>User Management<br/>Authentication]
    end

    subgraph "Audit Bounded Context"
        AUDIT[Audit Microservice<br/>Event Logging<br/>Compliance]
    end

    subgraph "Config Bounded Context"
        CONFIG[Config Microservice<br/>Configuration<br/>Feature Flags]
    end

    subgraph "Business Bounded Contexts"
        INVOICE[Invoice Microservice]
        BILLING[Billing Microservice]
        NOTIFICATION[Notification Microservice]
    end

    subgraph "Shared Libraries"
        LIB1[ConnectSoft.Extensions.Identity]
        LIB2[ConnectSoft.Extensions.Audit]
        LIB3[ConnectSoft.Extensions.Config]
    end

    subgraph "Event Bus"
        EB[Azure Service Bus<br/>Integration Events]
    end

    IDENTITY -->|Provides| LIB1
    AUDIT -->|Provides| LIB2
    CONFIG -->|Provides| LIB3

    INVOICE -->|Uses| LIB1
    INVOICE -->|Uses| LIB2
    INVOICE -->|Publishes| EB

    BILLING -->|Uses| LIB1
    BILLING -->|Publishes| EB

    NOTIFICATION -->|Uses| LIB1
    NOTIFICATION -->|Subscribes| EB

    AUDIT -->|Subscribes| EB

    style IDENTITY fill:#2563EB,color:#fff
    style AUDIT fill:#4F46E5,color:#fff
    style CONFIG fill:#10B981,color:#fff
    style EB fill:#EAB308,color:#fff
Hold "Alt" / "Option" to enable pan & zoom

Upstream/Downstream Relationships:

  • Identity, Audit, Config - Upstream services providing shared capabilities
  • Business contexts - Downstream services consuming shared capabilities
  • Event Bus - Enables loose coupling between contexts
  • Shared Libraries - Provide common functionality without tight coupling

Key Principles:

  • No direct dependencies - Business contexts use libraries, not direct service calls
  • Event-driven - Cross-context communication via events
  • Independent deployment - Each context deploys independently
  • Version independently - Libraries version separately from services