Platform Documentation Template¶

This template provides a standardized structure for documenting ConnectSoft SaaS platforms. Use this template when creating documentation for new platforms to ensure consistency across all 100+ platforms.

Note

Copy this template and fill in the platform-specific information. Remove sections that don't apply to your platform, but maintain the overall structure.

Template Structure¶

---
title: [Platform Name]
description: [Brief one-line description of what the platform does]
tags:
  - product
  - platform
  - [category-tag]
  - [additional-tags]
---
# [Platform Name]

This page describes the ConnectSoft [Platform Name] — [brief description]. It is written for [target audience].

[2-3 sentence overview of the platform, its purpose, and key value proposition.]

!!! tip
    The [Platform Name] is built by the Factory and serves as a reference implementation of our microservice template patterns. Customers can use it directly or generate custom [domain] services using the Factory.

## What This Platform Does

The [Platform Name] provides:

- **[Feature 1]** - [Description]
- **[Feature 2]** - [Description]
- **[Feature 3]** - [Description]
- **[Feature 4]** - [Description]
- **[Feature 5]** - [Description]

## Core Features

- **[Feature Name]** - [Detailed description of feature]
- **[Feature Name]** - [Detailed description of feature]
- **[Feature Name]** - [Detailed description of feature]
- **[Feature Name]** - [Detailed description of feature]
- **[Feature Name]** - [Detailed description of feature]
- **[Feature Name]** - [Detailed description of feature]
- **[Feature Name]** - [Detailed description of feature]
- **[Feature Name]** - [Detailed description of feature]
- **[Feature Name]** - [Detailed description of feature]
- **[Feature Name]** - [Detailed description of feature]

## Typical Integrations

### Microservices
- [How microservices integrate with this platform]
- [Integration pattern or approach]
- [API usage]

### External Services
- [External service integration 1]
- [External service integration 2]
- [External service integration 3]

### Frontend Applications
- [How frontend applications use this platform]
- [Integration approach]
- [API or SDK usage]

### Other ConnectSoft Platforms
- [Integration with Identity Platform]
- [Integration with Audit Platform]
- [Integration with Config Platform]
- [Integration with other platforms]

## Ideal Use Cases

- **[Use Case 1]** - [Description of when to use this platform for this use case]
- **[Use Case 2]** - [Description of when to use this platform for this use case]
- **[Use Case 3]** - [Description of when to use this platform for this use case]
- **[Use Case 4]** - [Description of when to use this platform for this use case]
- **[Use Case 5]** - [Description of when to use this platform for this use case]

## API Documentation

### REST API

The [Platform Name] provides a RESTful API for all operations.

**Base URL:** `https://[platform-name].connectsoft.io/api/v1`

**Authentication:** OAuth2/OIDC via Identity Platform

**Key Endpoints:**
- `GET /[resource]` - List [resources]
- `POST /[resource]` - Create [resource]
- `GET /[resource]/{id}` - Get [resource] by ID
- `PUT /[resource]/{id}` - Update [resource]
- `DELETE /[resource]/{id}` - Delete [resource]

**See:** [API Documentation Link] for complete API reference.

### gRPC API

The [Platform Name] also provides gRPC services for high-performance scenarios.

**Service:** `[ServiceName]`

**Key Methods:**
- `[MethodName]` - [Description]

**See:** [gRPC Documentation Link] for complete gRPC reference.

### Webhooks

The [Platform Name] supports webhooks for event notifications.

**Supported Events:**
- `[event.name]` - [Description]
- `[event.name]` - [Description]

**See:** [Webhook Documentation Link] for webhook configuration.

## Integration Guides

### Quick Start

[Step-by-step quick start guide for integrating the platform]

### Authentication

[How to authenticate with the platform]

### Basic Integration

[Basic integration example with code snippets]

### Advanced Integration

[Advanced integration patterns and examples]

**See:** [Integration Guide Link] for detailed integration documentation.

## Pricing and Licensing

### Hosted SaaS (Recommended)

**Pricing Model:** [Subscription/Usage-based/Hybrid]

**Tiers:**
- **Starter** - [Price/month] - [What's included]
- **Growth** - [Price/month] - [What's included]
- **Enterprise** - [Price/month] - [What's included]

**See:** [SaaS Platforms Business Model](../business-model/saas-platforms-model.md) for detailed pricing.

### Self-Host License

**Model:** Annual license fee per platform, per region/cluster

**Includes:**
- Compiled package or private repository access
- Support & maintenance contract (SLA-based)
- Optional professional services

**See:** [SaaS Platforms Business Model](../business-model/saas-platforms-model.md) for self-host licensing.

## Deployment Options

### Hosted SaaS on connectsoft.io

**URL:** `https://[platform-name].connectsoft.io`

**Benefits:**
- Fastest time-to-value (deploy in days)
- No infrastructure management
- Automatic updates and improvements
- Scalable and reliable

### Self-Host License

**Deployment:** Customer runs platform in their own Azure subscription

**Benefits:**
- Full control over data residency and compliance
- Custom configurations and integrations
- Infrastructure control

**When to Choose:**
- Regulated industries (healthcare, finance, government)
- Data residency requirements
- High-scale deployments
- Custom compliance needs

## Relationship to the Factory

The [Platform Name] demonstrates what the Factory can produce:

- **Built by the Factory** - The [Platform Name] was generated using the Factory's microservice template
- **Reference Implementation** - Shows best practices for multi-tenant SaaS, DDD, and event-driven architecture
- **Customizable via Factory** - Customers can generate custom [domain] services with specific requirements
- **Template Source** - [Domain] patterns are available as templates for Factory users

!!! note
    Customers can use the [Platform Name] as-is, or use the Factory to generate custom [domain] services tailored to their specific needs. The Factory includes [domain]-related templates and patterns.

## Related Platforms

### Commonly Used Together

- **[Related Platform 1]** - [Why they're used together]
- **[Related Platform 2]** - [Why they're used together]
- **[Related Platform 3]** - [Why they're used together]

### Platform Bundles

- **[Bundle Name]** - Includes [Platform Name] + [other platforms]
- **[Bundle Name]** - Includes [Platform Name] + [other platforms]

**See:** [Category Page Link] for platform bundles.

## Category

This platform belongs to the **[Category Name]** category.

**See:** [Category Page Link] for related platforms in this category.

## Related Documents

- [SaaS Platforms Business Model](../business-model/saas-platforms-model.md) - Pricing and licensing
- [Factory Overview](../factory/overview.md) - How the Factory generates platforms
- [Platform Creation Playbook](../playbooks/platform-creation-playbook.md) - How platforms are created
- [Category Page](../product-portfolio/platforms/categories/[category-file].md) - Related platforms
- [API Documentation]([api-doc-link]) - Complete API reference

Section Guidelines¶

Title and Description¶

Title: Use the exact platform name
Description: One-line description (max 160 characters) for SEO and previews
Tags: Include product, platform, category tag, and any relevant domain tags

What This Platform Does¶

List 4-6 high-level capabilities
Use bullet points for scannability
Focus on value, not implementation details

Core Features¶

List 8-12 detailed features
Each feature should be a complete sentence
Include both functional and non-functional features
Mention multi-tenancy, observability, security, etc.

Typical Integrations¶

Organize by integration type (Microservices, External Services, Frontend, Other Platforms)
Be specific about integration patterns
Link to detailed integration guides

Ideal Use Cases¶

List 4-6 common use cases
Each use case should be a specific scenario
Explain when to use this platform vs alternatives

API Documentation¶

Provide overview of API types (REST, gRPC, Webhooks)
List key endpoints/methods
Link to complete API documentation
Include authentication requirements

Integration Guides¶

Provide quick start guide
Include code examples
Link to detailed guides
Show common patterns

Pricing and Licensing¶

Reference business model document
Provide tier overview
Mention both hosted and self-host options
Link to detailed pricing

Deployment Options¶

Compare hosted vs self-host
Explain benefits of each
Provide guidance on when to choose each option

Relationship to the Factory¶

Explain Factory connection
Mention customization options
Link to Factory documentation

List commonly used together platforms
Mention platform bundles
Link to category pages

Examples¶

See existing platform documentation for examples: - Identity Platform - Audit Platform - Config Platform - Bot Platform