Skip to content

Documentation Standards

These standards keep the ConnectSoft AI Software Factory documentation consistent, navigable, and trustworthy across hundreds of pages and many contributors (human and agent).

Target architecture vs. implementation

The documentation describes the final-state target architecture. Some of it is implemented today; much is planned. We make the distinction explicit with admonitions, never by ambiguity.

Target Architecture — Final-State Design

Use this callout for services, workers, APIs, or platforms that describe the intended final state and are not necessarily implemented yet.

Implemented

Use this callout when referencing assets that exist in the codebase today (templates, ConnectSoft.Extensions.* libraries, definition repos).

Implementation Notes

Use this for grounding details, current-state behavior, or constraints that differ from the target design. Always clearly separated from target content.

Do not frame anything as "MVP-only" in the final-architecture sections, and never describe the platform as a chatbot. It is an AI-native software factory platform.

Terminology

Use these terms precisely and consistently:

Term Meaning
Platform A top-level capability plane (Control Plane, Knowledge, Agent Mesh, ...).
Bounded context A DDD domain boundary within a platform.
Microservice An independently deployable service within a bounded context.
Module A generated unit: microservice, UI, worker, library, or gateway.
Agent An autonomous role that executes tasks.
Skill An atomic, reusable agent capability.
Artifact Any produced output (see Artifact Metadata).
Event A fact emitted in the canonical envelope.
Aggregate root The consistency boundary and entry point of a domain aggregate.
Worker A background processor triggered by events, schedules, or commands.
Storage owner The single service that owns a given store.

Page templates

Platform overview.md

# Platform Name
## Purpose
## Role in AI Software Factory
## Core Responsibilities
## Key Capabilities
## High-Level Component Diagram   (Mermaid)
## Integration with Other Platforms   (Mermaid)
## Final-State Summary

Other platform pages follow the standard sections: microservices.md (table: Microservice | Responsibility | APIs | Events | Aggregate Roots | Store), apis.md (Public / Internal / gRPC / Authorization / Versioning / Examples), workers.md (table: Worker | Trigger | Purpose | Input | Output | Retry | Idempotency), events.md (Commands / Domain Events / Integration Events / Envelope / Topics), aggregate-roots.md (per aggregate: Purpose, Fields, Entities, Value Objects, Invariants, Domain Events, Repository, Persistence), data-model.md, storage.md (table: Data | Store | Owner Service | Access Pattern | Retention | Notes), workflows.md, security.md, observability.md, deployment.md, extension-roadmap.md.

Every page must connect to the pillars

Each page explains how its subject contributes to:

  • Traceability — links to traceId, lineage, events.
  • Reusability — modules, templates, libraries, patterns.
  • Autonomy — agent-driven generation and validation.
  • Governance — policy, approval, audit, isolation.
  • Observability — logs, metrics, traces, feedback.
  • Multi-tenant scale — tenant isolation and horizontal scale.

Diagram standards (Mermaid)

All diagrams are authored as inline Mermaid code blocks (rendered by the Material superfences + panzoom config). No external images, no separate diagram appendix.

Authoring rules:

  • No spaces in node IDs — use camelCase, PascalCase, or under_scores.
  • Quote labels containing parentheses, colons, commas, or brackets: A["Process (main)"].
  • Do not use reserved words (end, graph, subgraph) as node IDs.
  • Do not set explicit colors/styles — the theme handles light/dark.
  • Use the right diagram type: flowchart for structure, sequenceDiagram for interactions, stateDiagram-v2 for lifecycles, erDiagram for data models.

Per-page diagram minimums: component diagram on overview.md, context map on bounded-contexts.md, service interaction on microservices.md, sequence + state diagrams on workflows.md, event flow on events.md, ER diagram on data-model.md, deployment topology on deployment.md.

Tables for catalogs

Catalog-style content uses tables, not prose lists. The global catalogs aggregate platform pages and link back to them as the single source of truth.

  • Use Markdown links with relative paths to other docs.
  • Cross-link platforms ↔ catalogs, microservices ↔ aggregate roots, APIs ↔ workflows, events ↔ workers, storage ↔ owning services.
  • Never link to external design notes or scratch documents as a source of record.