feat(tags): Add database schema and tags module (v1.3.0 Phase 1)
Implements tag/category system backend following microformats2 p-category specification. Database changes: - Migration 008: Add tags and note_tags tables - Normalized tag storage (case-insensitive lookup, display name preserved) - Indexes for performance New module: - starpunk/tags.py: Tag management functions - normalize_tag: Normalize tag strings - get_or_create_tag: Get or create tag records - add_tags_to_note: Associate tags with notes (replaces existing) - get_note_tags: Retrieve note tags (alphabetically ordered) - get_tag_by_name: Lookup tag by normalized name - get_notes_by_tag: Get all notes with specific tag - parse_tag_input: Parse comma-separated tag input Model updates: - Note.tags property (lazy-loaded, prefer pre-loading in routes) - Note.to_dict() add include_tags parameter CRUD updates: - create_note() accepts tags parameter - update_note() accepts tags parameter (None = no change, [] = remove all) Micropub integration: - Pass tags to create_note() (tags already extracted by extract_tags()) - Return tags in q=source response Per design doc: docs/design/v1.3.0/microformats-tags-design.md Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
220
docs/design/v1.1.2/v1.1.2-options.md
Normal file
220
docs/design/v1.1.2/v1.1.2-options.md
Normal file
@@ -0,0 +1,220 @@
|
||||
# StarPunk v1.1.2 Release Plan Options
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Three distinct paths forward from v1.1.1 "Polish", each addressing the critical metrics instrumentation gap while offering different value propositions:
|
||||
|
||||
- **Option A**: "Observatory" - Complete observability with full metrics + distributed tracing
|
||||
- **Option B**: "Syndicate" - Fix metrics + expand syndication with ATOM and JSON feeds
|
||||
- **Option C**: "Resilient" - Fix metrics + add robustness features (backup/restore, rate limiting)
|
||||
|
||||
---
|
||||
|
||||
## Option A: "Observatory" - Complete Observability Stack
|
||||
|
||||
### Theme
|
||||
Transform StarPunk into a fully observable system with comprehensive metrics, distributed tracing, and actionable insights.
|
||||
|
||||
### Scope
|
||||
**12-14 hours**
|
||||
|
||||
### Features
|
||||
- ✅ **Complete Metrics Instrumentation** (4 hours)
|
||||
- Instrument all database operations with timing
|
||||
- Add HTTP client/server request metrics
|
||||
- Implement memory monitoring thread
|
||||
- Add business metrics (notes created, syndication success rates)
|
||||
|
||||
- ✅ **Distributed Tracing** (4 hours)
|
||||
- OpenTelemetry integration for request tracing
|
||||
- Trace context propagation through all layers
|
||||
- Correlation IDs for log aggregation
|
||||
- Jaeger/Zipkin export support
|
||||
|
||||
- ✅ **Smart Alerting** (2 hours)
|
||||
- Threshold-based alerts for key metrics
|
||||
- Alert history and acknowledgment system
|
||||
- Webhook notifications for alerts
|
||||
|
||||
- ✅ **Performance Profiling** (2 hours)
|
||||
- CPU and memory profiling endpoints
|
||||
- Flame graph generation
|
||||
- Query analysis tools
|
||||
|
||||
### User Value
|
||||
- **For Operators**: Complete visibility into system behavior, proactive problem detection
|
||||
- **For Developers**: Easy debugging with full request tracing
|
||||
- **For Users**: Better reliability through early issue detection
|
||||
|
||||
### Risks
|
||||
- Requires learning OpenTelemetry concepts
|
||||
- May add slight performance overhead (typically <1%)
|
||||
- Additional dependencies for tracing libraries
|
||||
|
||||
---
|
||||
|
||||
## Option B: "Syndicate" - Enhanced Content Distribution
|
||||
|
||||
### Theme
|
||||
Fix metrics and expand StarPunk's reach with multiple syndication formats, making content accessible to more readers.
|
||||
|
||||
### Scope
|
||||
**14-16 hours**
|
||||
|
||||
### Features
|
||||
- ✅ **Complete Metrics Instrumentation** (4 hours)
|
||||
- Instrument all database operations with timing
|
||||
- Add HTTP client/server request metrics
|
||||
- Implement memory monitoring thread
|
||||
- Add syndication-specific metrics
|
||||
|
||||
- ✅ **ATOM Feed Support** (4 hours)
|
||||
- Full ATOM 1.0 specification compliance
|
||||
- Parallel generation with RSS
|
||||
- Content negotiation support
|
||||
- Feed validation tools
|
||||
|
||||
- ✅ **JSON Feed Support** (4 hours)
|
||||
- JSON Feed 1.1 implementation
|
||||
- Author metadata support
|
||||
- Attachment handling for media
|
||||
- Hub support for real-time updates
|
||||
|
||||
- ✅ **Feed Enhancements** (2-4 hours)
|
||||
- Feed statistics dashboard
|
||||
- Custom feed URLs/slugs
|
||||
- Feed caching layer
|
||||
- OPML export for feed lists
|
||||
|
||||
### User Value
|
||||
- **For Publishers**: Reach wider audience with multiple feed formats
|
||||
- **For Readers**: Choose preferred feed format for their reader
|
||||
- **For IndieWeb**: Better ecosystem compatibility
|
||||
|
||||
### Risks
|
||||
- More complex content negotiation logic
|
||||
- Feed format validation complexity
|
||||
- Potential for feed generation performance issues
|
||||
|
||||
---
|
||||
|
||||
## Option C: "Resilient" - Operational Excellence
|
||||
|
||||
### Theme
|
||||
Fix metrics and add critical operational features for data protection and system stability.
|
||||
|
||||
### Scope
|
||||
**12-14 hours**
|
||||
|
||||
### Features
|
||||
- ✅ **Complete Metrics Instrumentation** (4 hours)
|
||||
- Instrument all database operations with timing
|
||||
- Add HTTP client/server request metrics
|
||||
- Implement memory monitoring thread
|
||||
- Add backup/restore metrics
|
||||
|
||||
- ✅ **Backup & Restore System** (4 hours)
|
||||
- Automated SQLite backup with rotation
|
||||
- Point-in-time recovery
|
||||
- Export to IndieWeb-compatible formats
|
||||
- Restore validation and testing
|
||||
|
||||
- ✅ **Rate Limiting & Protection** (3 hours)
|
||||
- Per-endpoint rate limiting
|
||||
- Sliding window implementation
|
||||
- DDoS protection basics
|
||||
- Graceful degradation under load
|
||||
|
||||
- ✅ **Data Transformer Refactor** (1 hour)
|
||||
- Fix technical debt from hotfix
|
||||
- Implement proper contract pattern
|
||||
- Add transformer tests
|
||||
|
||||
- ✅ **Operational Utilities** (2 hours)
|
||||
- Database vacuum scheduling
|
||||
- Log rotation configuration
|
||||
- Disk space monitoring
|
||||
- Graceful shutdown handling
|
||||
|
||||
### User Value
|
||||
- **For Operators**: Peace of mind with automated backups and protection
|
||||
- **For Users**: Data safety and system reliability
|
||||
- **For Self-hosters**: Production-ready operational features
|
||||
|
||||
### Risks
|
||||
- Backup strategy needs careful design to avoid data loss
|
||||
- Rate limiting could affect legitimate users if misconfigured
|
||||
- Additional background tasks may increase resource usage
|
||||
|
||||
---
|
||||
|
||||
## Comparison Matrix
|
||||
|
||||
| Aspect | Observatory | Syndicate | Resilient |
|
||||
|--------|------------|-----------|-----------|
|
||||
| **Primary Focus** | Observability | Content Distribution | Operational Safety |
|
||||
| **Metrics Fix** | ✅ Complete | ✅ Complete | ✅ Complete |
|
||||
| **New Features** | Tracing, Profiling | ATOM, JSON feeds | Backup, Rate Limiting |
|
||||
| **Complexity** | High (new concepts) | Medium (new formats) | Low (straightforward) |
|
||||
| **External Deps** | OpenTelemetry | Feed validators | None |
|
||||
| **User Impact** | Indirect (better ops) | Direct (more readers) | Indirect (reliability) |
|
||||
| **Performance** | Slight overhead | Neutral | Improved (rate limiting) |
|
||||
| **IndieWeb Value** | Medium | High | Medium |
|
||||
|
||||
---
|
||||
|
||||
## Recommendation Framework
|
||||
|
||||
### Choose **Observatory** if:
|
||||
- You're running multiple StarPunk instances
|
||||
- You need to debug production issues
|
||||
- You value deep system insights
|
||||
- You're comfortable with observability tools
|
||||
|
||||
### Choose **Syndicate** if:
|
||||
- You want maximum reader compatibility
|
||||
- You're focused on content distribution
|
||||
- You need modern feed formats
|
||||
- You want to support more IndieWeb tools
|
||||
|
||||
### Choose **Resilient** if:
|
||||
- You're running in production
|
||||
- You value data safety above features
|
||||
- You need protection against abuse
|
||||
- You want operational peace of mind
|
||||
|
||||
---
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
### All Options Include:
|
||||
1. **Metrics Instrumentation** (identical across all options)
|
||||
- Database operation timing
|
||||
- HTTP request/response metrics
|
||||
- Memory monitoring thread
|
||||
- Business metrics relevant to option theme
|
||||
|
||||
2. **Version Bump** to v1.1.2
|
||||
3. **Changelog Updates** following versioning strategy
|
||||
4. **Documentation** for new features
|
||||
5. **Tests** for all new functionality
|
||||
|
||||
### Phase Breakdown
|
||||
|
||||
Each option can be delivered in 2-3 phases:
|
||||
|
||||
**Phase 1** (4-6 hours): Metrics instrumentation + planning
|
||||
**Phase 2** (4-6 hours): Core new features
|
||||
**Phase 3** (4 hours): Polish, testing, documentation
|
||||
|
||||
---
|
||||
|
||||
## Decision Deadline
|
||||
|
||||
Please select an option by reviewing:
|
||||
1. Your operational priorities
|
||||
2. Your user community needs
|
||||
3. Your comfort with complexity
|
||||
4. Available time for implementation
|
||||
|
||||
Each option is designed to be completable in 2-3 focused work sessions while delivering distinct value to different stakeholder groups.
|
||||
Reference in New Issue
Block a user