​
CLAUDE.md

​
Mintlify documentation

​
Working relationship

  • You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so
  • ALWAYS ask for clarification rather than making assumptions
  • NEVER lie, guess, or make up information

​
Project context

  • Format: MDX files with YAML frontmatter
  • Config: docs.json for navigation, theme, settings
  • Components: Mintlify components

​
Content strategy

  • Document just enough for user success - not too much, not too little
  • Prioritize accuracy and usability of information
  • Make content evergreen when possible
  • Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason
  • Check existing patterns for consistency
  • Start by making the smallest reasonable changes

​
docs.json

  • Refer to the docs.json schema when building the docs.json file and site navigation

​
Frontmatter requirements for pages

  • title: Clear, descriptive page title
  • description: Concise summary for SEO/navigation

​
Writing standards

  • Second-person voice (“you”)
  • Prerequisites at start of procedural content
  • Test all code examples before publishing
  • Match style and formatting of existing pages
  • Include both basic and advanced use cases
  • Language tags on all code blocks
  • Alt text on all images
  • Relative paths for internal links

​
Git workflow

  • NEVER use —no-verify when committing
  • Ask how to handle uncommitted changes before starting
  • Create a new branch when no clear branch exists for changes
  • Commit frequently throughout development
  • NEVER skip or disable pre-commit hooks

​
Do not

  • Skip frontmatter on any MDX file
  • Use absolute URLs for internal links
  • Include untested code examples
  • Make assumptions - always ask for clarification
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

​
Repository Overview

This is the documentation repository for PlayFlow Cloud, a game-server orchestration platform for multiplayer games. The documentation is built using Mintlify, a modern documentation platform optimized for developer docs.

​
Common Development Commands

# Install Mintlify CLI (required for local development)
npm i -g mintlify

# Run local development server (default port 3000)
mintlify dev

# Run on custom port
mintlify dev --port 3333

# Check for broken links
mintlify broken-links

# Troubleshooting: Reinstall dependencies if dev server fails
mintlify install

​
Architecture & Structure

​
Core Configuration

  • docs.json - Main configuration file that defines:
    • Navigation structure (tabs, groups, pages)
    • Theme settings (colors, icons, logos)
    • SEO metadata
    • API reference integration via OpenAPI specs

​
Content Organization

  • MDX Format: All documentation uses MDX (Markdown + JSX components)
  • Frontmatter: Each page includes metadata (title, description, icon)
  • Navigation: Two-tab structure - “Documentation” and “API Reference”

​
Key Directories

  • /api-reference/ - OpenAPI specification files for automatic API docs generation
    • game-servers-openapi.json - Game server API specifications
    • playflow-matchmaking.json - Matchmaking and lobby API specifications
  • /unity/ - Unity SDK documentation with lobby system and matchmaking guides
  • /guides/ - Tutorials including WebGL deployments and migration guides
  • /fundamentals/ - Core concepts like plan instance types
  • /images/ - Documentation images and diagrams
  • /logo/ - Brand assets (light/dark mode SVGs)

​
Mintlify Components

Common components used throughout the docs:
  • <Card> and <CardGroup> - Feature cards with icons
  • <Info>, <Warning>, <Tip> - Callout boxes
  • <CodeGroup> - Multi-language code examples
  • <ResponseExample> - API response examples

​
Deployment

  • Automatic deployment via GitHub App integration
  • Changes to main branch auto-deploy to production
  • No manual build process required

​
PlayFlow Context

This documentation covers:
  • Game Server Management: On-demand server spinning, auto-scaling
  • Matchmaking System: ELO-based, region-aware player matching
  • Lobby System: WebSocket-powered lobbies with chat and ready-checks
  • Unity SDK: Primary SDK focus with comprehensive guides
  • WebGL Deployments: Browser-based game hosting
  • Global Infrastructure: Multi-region, multi-cloud support

​
Development Guidelines

  1. MDX Best Practices:
    • Use appropriate Mintlify components for better UX
    • Include code examples in relevant languages (Unity C#, REST API)
    • Add icons to pages via frontmatter for visual hierarchy
  2. API Documentation:
    • API docs are auto-generated from OpenAPI specs
    • Update JSON files in /api-reference/ for API changes
    • Don’t manually edit generated API reference pages
  3. Navigation Updates:
    • Modify docs.json to add/remove pages or reorganize structure
    • Maintain logical grouping (Getting Started → SDK → Advanced)
    • Use descriptive icons from Lucide icon set
  4. Local Development:
    • Always run mintlify dev to preview changes
    • Test navigation and links before committing
    • Verify images load correctly from /images/ directory