Create Platform Service development guide

[maximiliantech]

Understand the Task

Create a development guide for Platform Services, parallel to the existing Service Provider development guide.

Problem

Contributors have no guidance on how to develop a Platform Service. The Service Provider guide covers:

• Prerequisites and setup
• Template usage
• Project structure
• API creation (ServiceProviderAPI, ProviderConfig)
• Reconciler implementation
• Testing with openmcp-testing
• Best practices

Platform Services need equivalent documentation.

Proposed Structure

Mirror the Service Provider guide structure:

/docs/developers/platform-services/
├── index.md (Overview)
├── prerequisites.md
├── template-usage.md (once platform-service-template exists)
├── project-structure.md
├── apis.md (PlatformService, custom config CRD)
├── reconciler.md
├── testing.md
└── best-practices.md

Content Outline

1. Overview

• What is a Platform Service (link to concept)
• Key differences from Service Providers
• When to build a Platform Service

2. Prerequisites

• Clone platform-service-template
• Go installation
• Local openMCP environment setup

3. Template Usage

• CLI generator commands
• Configuration options

4. Project Structure

• API types location
• Controller/reconciler location
• Config CRD pattern

5. API Creation

• PlatformService resource (how operators deploy your service)
• Custom config CRD (e.g., GatewayServiceConfig)
• Spec and status fields

6. Reconciler Implementation

• Platform cluster access
• Backend cluster access (if needed)
• Resource deployment patterns

7. Testing

• Unit testing
• E2E testing with openmcp-testing
• Local development workflow

8. Best Practices

• When to use Helm/Flux vs direct Go deployment
• Permission scoping
• Configuration patterns

Acceptance Criteria

• Development guide published at /docs/developers/platform-services
• All major sections from Service Provider guide covered
• Code examples using platform-service-template (or existing platform-service)
• Links to reference implementations

Dependencies

• Platform Service concept docs expanded (openmcp-project/docs#...)
• platform-service-template repository created

Parent Epic

Part of openmcp-project/backlog#514 (Enable Platform Service contributions)

References

• Service Provider guide: https://openmcp-project.github.io/docs/developers/service-providers
• platform-service-gateway as reference: https://github.com/openmcp-project/platform-service-gateway