​

CLAUDE.md - StreamNative Cloud Documentation

​

Purpose

​

Source Code Repository Mappings

​

Core Cloud Infrastructure

• cloud-api-server (source_code_refs/cloud-api-server/): Cloud API backend
  • Go-based API server implementing cloud management APIs
  • Handles authentication, authorization, and resource management
  • OpenAPI specs in apis/ directory generate documentation in api-references/cloudapi/
• cloud-manager (source_code_refs/cloud-manager/): Cloud orchestration backend
  • Manages cloud infrastructure and deployments
  • Contains email templates and UI components
  • Handles billing, maintenance, and platform operations

​

Security & Access Control

• unified-rbac (source_code_refs/unified-rbac/): Universal RBAC implementation
  • Maps to cloud/security/access/ documentation
  • Implements role-based access control across the platform
  • Design docs in docs/ directory

​

Data Processing & Storage

• ursa-storage (source_code_refs/ursa-storage/): Ursa storage engine
  • Maps to cloud/lakehouse/ documentation
  • Implements tiered storage and lakehouse features
  • Includes Iceberg integration and cloud storage support
• unilink (source_code_refs/unilink/): Universal linking service
  • Maps to cloud/universal-linking/ documentation
  • Enables cross-protocol message routing
  • Supports Kafka-Pulsar interoperability

​

Protocol Support

• ksn (source_code_refs/ksn/): Kafka protocol support (KoP/KSN)
  • Maps to Kafka-related features throughout cloud docs
  • Implements Kafka API compatibility
  • Includes Kafka Connect support
  • Documentation in docs/ directory

​

CLI Tools

• cloud-cli (source_code_refs/cloud-cli/): snctl CLI tool
  • Maps to tools/cli/snctl/ documentation
  • Command-line interface for StreamNative Cloud
  • Auto-generated docs synced from separate repository

​

Documentation Patterns

​

Common Sections

1. Overview: High-level concepts and architecture
2. Get Started: Quick start guides and tutorials
3. Clusters: Cluster management and configuration
4. Security: Authentication, authorization, and encryption
5. Process: Data processing with Functions, PfSQL, and Kafka Streams
6. Connect: Connector management (Pulsar IO and Kafka Connect)
7. Lakehouse: Tiered storage and analytics features
8. Billing: Usage tracking and cost management
9. Monitoring: Metrics, logging, and observability

​

Key Features to Document

• Multi-tenancy (tenants, namespaces, topics)
• Geo-replication
• Auto-scaling
• BYOC (Bring Your Own Cloud)
• Serverless instances
• Advanced observability
• Lakehouse storage with Iceberg

​

SNIP References

• Cloud features (SNIP-11, SNIP-130, SNIP-141)
• RBAC improvements (SNIP-108, SNIP-148)
• Lakehouse/Ursa features (SNIP-11, SNIP-135, SNIP-145)
• Kafka protocol enhancements (SNIP-101, SNIP-102, SNIP-110, SNIP-112, SNIP-122)
• Universal linking (SNIP proposals for unilink)

​

Common Tasks

​

Adding New Cloud Features

1. Check relevant source repository for implementation details
2. Review SNIP proposals for design decisions
3. Follow existing documentation patterns in similar features
4. Update navigation in docs.json
5. Add cross-references to related features

​

Updating API Documentation

1. API specs are in apis/cloudapi/ directory
2. Generated docs go in api-references/cloudapi/
3. Use scripts in migration_scripts/ for generation
4. Follow OpenAPI documentation standards

​

Security Documentation

1. Reference unified-rbac for RBAC concepts
2. Check cloud-api-server for authentication flows
3. Document both UI and API approaches
4. Include examples with service accounts and API keys

​

Cross-References

• Private Cloud docs for on-premises deployments
• Tools docs for CLI and Terraform usage
• Clients docs for SDK integration
• Connect docs for connector configuration