phil/StarPunk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
247eb34c365a561e96b68c405fd1f93dd1cc4491
StarPunk/docs/design/v1.1.2/v1.1.2-options.md
Phil Skentelbery f10d0679da 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>
2025-12-10 11:24:23 -07:00

6.8 KiB
Raw Blame History

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 View Git Blame Copy Permalink