Skip to content

ADR-0008: SaaS Framework Documentation Migration

  • Status: accepted
  • Deciders: ConnectSoft Architecture Team
  • Date: 2025-12-17

Context and Problem Statement

SaaS framework documentation (DDD Blueprint, DDD Entities Specification, and High-Level Design) currently exists in ConnectSoft.Documentation/Docs/saas/. This documentation describes a reusable SaaS framework solution that is part of the ConnectSoft framework and should be discoverable alongside other product portfolio and SaaS documentation.

The question: Where should SaaS framework documentation be located to ensure proper categorization, discoverability, and alignment with the overall documentation structure?

Decision Drivers

  • Need for centralized documentation location
  • Requirement for proper categorization (@saas, @product-portfolio)
  • Need for improved discoverability of framework documentation
  • Requirement for consistency with existing documentation structure
  • Need to separate framework documentation from individual product documentation

Considered Options

Option 1: Keep in ConnectSoft.Documentation

Approach: Leave documentation in the original location.

Pros:

  • No migration effort required
  • Existing links remain valid

Cons:

  • Documentation scattered across repositories
  • Difficult to discover alongside other SaaS and product portfolio docs
  • Inconsistent with centralized documentation approach
  • Missing proper categorization tags

Rejected - Does not meet discoverability and categorization requirements.

Option 2: Migrate to CompanyDocumentation under docs/saas/framework/ (Selected)

Approach: Migrate documentation to ConnectSoft.CompanyDocumentation/docs/saas/framework/ with appropriate categorization.

Pros:

  • Centralized documentation location
  • Proper categorization with @saas and @product-portfolio tags
  • Clear separation from individual product documentation
  • Improved discoverability in navigation
  • Consistent with existing documentation structure
  • Framework documentation grouped logically

Cons:

  • Migration effort required
  • Potential broken links (if any external references exist)
  • Need to update navigation

Decision

Migrate SaaS framework documentation from ConnectSoft.Documentation/Docs/saas/ to ConnectSoft.CompanyDocumentation/docs/saas/framework/:

Migrated Files:

  • saas-platform-ddd-blueprint.md - DDD Design Blueprint
  • saas-platform-ddd-entities.md - DDD Entities Specification
  • saas-platform-hld.md - High-Level Design

Categorization:

  • Add product-portfolio and framework tags to all migrated documents
  • Maintain existing tags (saas, ddd, architecture, etc.)

Navigation:

  • Add framework documentation section to mkdocs.yml under "SaaS & Solutions"
  • Create framework overview document for discoverability

Rationale

  • Centralization: Single source of truth for all company documentation improves maintainability and discoverability.
  • Categorization: Proper tags enable better search and filtering of framework documentation.
  • Organization: framework/ subdirectory clearly separates reusable framework documentation from individual SaaS product documentation.
  • Discoverability: Framework documentation is now accessible alongside other SaaS and product portfolio documentation in the navigation.
  • Consistency: Aligns with existing documentation structure and categorization patterns.

Consequences

Positive Consequences

  • Centralized documentation location
  • Improved discoverability and navigation
  • Proper categorization with appropriate tags
  • Clear separation between framework and product documentation
  • Consistent documentation structure
  • Better alignment with product portfolio organization

Negative Consequences

  • Migration effort required (completed)
  • Potential broken external links (if any exist, need to be updated)
  • Need to maintain navigation structure