Annotations
Annotations provide a centralized metadata storage system for configuration, documentation, and application context in Raindrop applications. Instead of scattering metadata across multiple systems, annotations let you attach information directly to your application’s logical structure.
What Annotations Provide
Hierarchical Organization Metadata is organized by application structure - from application-wide settings down to individual component configuration.
Machine-Readable Names (MRNs)
Every annotation has a precise address that specifies exactly where the metadata belongs, like app/v1.0.0/module/item/key
.
Revision Tracking Automatic versioning of metadata changes with complete history and rollback capabilities.
Flexible Data Storage Store any type of metadata - text, JSON objects, binary files, or structured documents.
When to Use Annotations
Good Fit
- Configuration Management: Feature flags, API endpoints, environment settings that change without code deployments
- Documentation: Deployment notes, architectural decisions, troubleshooting guides that stay with your code
- Audit Information: Configuration change logs, debugging data tied to specific versions
- Deployment Context: Version-specific metadata that varies between deployments
Consider Alternatives
- High-Volume Data: Transactional data and business records belong in databases
- Complex Queries: Data needing analysis and reporting works better in SQL databases
- Real-Time Updates: Frequently changing operational data might be better in KV storage
Integration Patterns
Service Configuration Services can load configuration from annotations at startup or runtime, enabling operational changes without redeployment.
Actor Enhancement Actors can store persistent behavioral configuration in annotations while maintaining stateful processing.
Cross-Component Coordination Shared configuration and service discovery information can live as annotations that multiple components reference.
Deployment Pipeline Integration Build systems can store deployment metadata, release notes, and operational procedures as annotations.
Annotations excel at metadata that needs to stay closely tied to your application structure and deployment lifecycle.