> ## Documentation Index
> Fetch the complete documentation index at: https://mint-tsdocs.saulo.engineer/llms.txt
> Use this file to discover all available pages before exploring further.

# Microservices Examples

> OpenDocs for microservices architectures

export const FileTree = ({structure, item, title, level = 0, maxDepth = 10, showIcons = true}) => {
  const getFileIcon = (fileName, hasChildren) => {
    if (hasChildren) {
      return 'folder-open';
    }
    return 'file';
  };
  if (structure !== undefined) {
    return <div data-component="tsdocs-filetree" className="code-block mt-5 mb-8 not-prose rounded-2xl relative group
                   text-gray-950 bg-gray-50 dark:bg-white/5 dark:text-gray-50
                   border border-gray-950/10 dark:border-white/10
                   p-0.5">
        {title && <div className="flex text-gray-400 text-xs rounded-t-[14px] leading-6 font-medium pl-4 pr-2.5 py-1">
            <div className="flex-none flex items-center gap-1.5 text-gray-700 dark:text-gray-300">
              {title}
            </div>
          </div>}
        <div className={`prose prose-sm dark:prose-invert w-0 min-w-full max-w-full py-3.5 px-4 bg-white dark:bg-codeblock overflow-x-auto scrollbar-thin scrollbar-thumb-rounded scrollbar-thumb-black/15 hover:scrollbar-thumb-black/20 dark:scrollbar-thumb-white/20 dark:hover:scrollbar-thumb-white/25 rounded-xt`} style={{
      fontFamily: 'ui-monospace, SFMono-Regular, monospace',
      fontSize: '0.875rem'
    }}>
          {structure.map((fileItem, index) => {
      if (!fileItem || !fileItem.name) return null;
      return <FileTree key={index} item={fileItem} level={0} maxDepth={maxDepth} showIcons={showIcons} />;
    })}
        </div>
      </div>;
  }
  if (!item) {
    return null;
  }
  if (level >= maxDepth) {
    return <div style={{
      paddingLeft: `${level * 20}px`,
      paddingTop: '4px',
      paddingBottom: '4px',
      color: '#6b7280',
      fontStyle: 'italic'
    }}>
        {showIcons && <Icon icon="AlertTriangle" />} (max depth reached)
      </div>;
  }
  const hasChildren = item.children != null && item.children.length > 0;
  const indent = level * 20;
  if (hasChildren) {
    return <div style={{
      position: 'relative',
      paddingLeft: `${indent}px`
    }}>
        {}
        {level > 0 && <div style={{
      position: 'absolute',
      left: `${indent - 12}px`,
      top: '20px',
      bottom: '0',
      width: '1px',
      backgroundColor: 'rgba(156, 163, 175, 0.2)',
      borderLeft: '1px solid rgba(156, 163, 175, 0.1)'
    }} />}
        <div style={{
      display: 'flex',
      alignItems: 'center',
      gap: '8px',
      paddingTop: '4px',
      paddingBottom: '4px'
    }}>
          {showIcons && <Icon icon={getFileIcon(item.name, true)} />}
          <span style={{
      fontWeight: 500
    }}>
            {item.name}
          </span>
          {item.description && <span style={{
      fontSize: '0.75rem',
      color: '#94a3b8',
      marginLeft: '8px'
    }}>
              {item.description}
            </span>}
          {item.badge && <Badge color={item.badge.color || 'blue'}>
              {item.badge.text}
            </Badge>}
        </div>
        {}
        {item.children && item.children.map((child, i) => {
      const key = child.name ? `${child.name}-${i}` : `child-${i}`;
      return <FileTree key={key} item={child} level={level + 1} maxDepth={maxDepth} showIcons={showIcons} />;
    })}
      </div>;
  }
  return <div style={{
    position: 'relative',
    paddingLeft: `${indent}px`,
    display: 'flex',
    alignItems: 'center',
    gap: '8px',
    paddingTop: '4px',
    paddingBottom: '4px'
  }}>
      {}
      {level > 0 && <div style={{
    position: 'absolute',
    left: `${indent - 12}px`,
    top: '0',
    bottom: '0',
    width: '1px',
    backgroundColor: 'rgba(156, 163, 175, 0.2)',
    borderLeft: '1px solid rgba(156, 163, 175, 0.1)'
  }} />}
      {showIcons && <Icon icon={getFileIcon(item.name, false)} />}
      <span>
        {item.name}
      </span>
      {item.description && <span style={{
    fontSize: '0.75rem',
    color: '#94a3b8',
    marginLeft: '8px'
  }}>
          {item.description}
        </span>}
      {item.badge && <Badge color={item.badge.color || 'blue'}>
          {item.badge.text}
        </Badge>}
    </div>;
};

# Microservices Examples

<Warning>
  **RFC Status**: This section contains proposed examples for the OpenDocs Specification RFC.

  These examples are provided to illustrate how the specification could be implemented.
  [Provide feedback](https://github.com/svallory/mintlify-tsdocs/issues) to help refine these examples.
</Warning>

## Microservices Architecture

This example demonstrates how to document a microservices architecture with cross-service references and performance optimization for large codebases.

### Project Structure

<FileTree
  structure={[
{
  name: "user-service/",
  children: [
    { name: "go.mod" },
    { name: "main.go" }
  ]
},
{
  name: "billing-service/",
  children: [
    { name: "package.json" },
    { name: "src/" }
  ]
},
{
  name: "notification-service/",
  children: [
    { name: "Cargo.toml" },
    { name: "src/" }
  ]
},
{
  name: "api-gateway/",
  children: [
    { name: "package.json" },
    { name: "src/" }
  ]
}
]}
/>

### opendocs.json Configuration

```json theme={null}
{
  "documentationSet": {
    "id": "acme-microservices-docs",
    "name": "Acme Microservices Documentation",
    "description": "Microservices architecture documentation",
    "version": "1.0.0",
    "created": "2024-01-01T00:00:00Z"
  },
  "projects": [
    {
      "id": "user-service",
      "name": "User Service",
      "language": "go",
      "version": "1.2.0",
      "location": {
        "type": "file",
        "path": "services/user-service.json",
        "format": "json"
      }
    },
    {
      "id": "billing-service",
      "name": "Billing Service",
      "language": "typescript",
      "version": "2.1.0",
      "location": {
        "type": "file",
        "path": "services/billing-service.json",
        "format": "json"
      }
    },
    {
      "id": "notification-service",
      "name": "Notification Service",
      "language": "rust",
      "version": "0.8.5",
      "location": {
        "type": "file",
        "path": "services/notification-service.json",
        "format": "json"
      }
    },
    {
      "id": "api-gateway",
      "name": "API Gateway",
      "language": "typescript",
      "version": "1.5.2",
      "location": {
        "type": "file",
        "path": "services/api-gateway.json",
        "format": "json"
      }
    }
  ],
  "navigation": {
    "title": "Microservices API",
    "groups": [
      {
        "name": "Core Services",
        "projects": ["user-service", "billing-service"]
      },
      {
        "name": "Support Services",
        "projects": ["notification-service"]
      },
      {
        "name": "Infrastructure",
        "projects": ["api-gateway"]
      }
    ]
  }
}
```

## Cross-Service References

The billing service demonstrates how to document dependencies on other services:

```json theme={null}
{
  "project": {
    "id": "billing-service",
    "name": "Billing Service",
    "language": "typescript",
    "items": {
      "format": "jsonl",
      "file": "billing-service-items.jsonl",
      "count": 203
    },
    "metadata": {
      "dependencies": [
        { "project": "user-service", "ref": "../user-service/user-service.json" },
        { "project": "notification-service", "ref": "../notification-service/notification-service.json" }
      ],
      "externalApis": ["Stripe API", "PayPal API"]
    }
  }
}
```

## Performance Optimization Examples

### Large Codebase with Streaming

For enterprise platforms with tens of thousands of documented items, use streaming and chunked processing:

```json theme={null}
{
  "workspace": {
    "id": "enterprise-platform",
    "name": "Enterprise Platform",
    "description": "Large enterprise platform with 50k+ documented items",
    "navigation": {
      "projects": [
        { "id": "core", "name": "Core Library", "_ref": "projects/core.json" },
        { "id": "modules", "name": "Business Modules", "_ref": "projects/modules.json" }
      ]
    },
    "organization": {
      "format": "streaming",
      "chunkSize": 1000
    }
  }
}
```

### Chunked Processing

Configure projects for efficient memory usage with parallel processing:

```json theme={null}
{
  "project": {
    "id": "modules",
    "name": "Business Modules",
    "language": "typescript",
    "items": {
      "format": "jsonl",
      "file": "modules-items.jsonl",
      "count": 45678
    },
    "metadata": {
      "processingStrategy": "chunked",
      "memoryLimit": "512MB",
      "parallelProcessing": true
    }
  }
}
```

## Key Features

* **Service Independence**: Each microservice maintains its own documentation
* **Cross-References**: Services can reference APIs from other services
* **External Dependencies**: Document integration with third-party APIs
* **Performance Optimization**: Streaming and chunked processing for large codebases
* **Logical Grouping**: Organize services by their role in the architecture

## Best Practices

1. **Document Service Boundaries**: Clearly indicate which APIs are public vs internal
2. **Track Dependencies**: Maintain explicit references between services
3. **Version Carefully**: Use semantic versioning and track breaking changes
4. **Optimize for Scale**: Use JSONL and streaming for services with large APIs
5. **Group by Function**: Organize navigation by service purpose, not technology

## Performance Considerations

For large microservices architectures:

* Use **JSONL format** for all services with 100+ documented items
* Enable **streaming processing** when total items exceed 10,000
* Configure **chunk size** based on available memory (1000 items = \~10MB)
* Use **parallel processing** for faster documentation generation
* Set **memory limits** to prevent out-of-memory errors

## See Also

* [Monorepo Examples](/opendocs/examples/monorepo) - Multi-language monorepo patterns
* [Performance Guide](/opendocs/implementation/performance) - Optimization strategies
* [Examples Overview](/opendocs/examples/index) - Back to all examples

***

*This example is part of the OpenDocs Specification RFC. [Provide feedback](https://github.com/svallory/mintlify-tsdocs/issues) to help improve it.*