StarPunk/docs/projectplan/ROADMAP.md

StarPunk Roadmap

Current Status

Latest Version: v1.1.2 "Syndicate" Released: 2025-11-27 Status: Production Ready

StarPunk has achieved V1 feature completeness with all core IndieWeb functionality implemented:

• ✅ IndieAuth authentication
• ✅ Micropub endpoint
• ✅ Notes management
• ✅ RSS syndication
• ✅ Full-text search
• ✅ Custom slugs

Version History

Released Versions

v1.1.2 "Syndicate" (2025-11-27)

• Multi-format feed support (RSS 2.0, ATOM 1.0, JSON Feed 1.1)
• Content negotiation for automatic format selection
• Feed caching with LRU eviction and TTL expiration
• ETag support with 304 conditional responses
• Feed statistics dashboard in admin panel
• OPML 2.0 export for feed discovery
• Complete metrics instrumentation

v1.1.1 (2025-11-26)

• Fix metrics dashboard 500 error
• Add data transformer for metrics template

v1.1.0 "SearchLight" (2025-11-25)

• Full-text search with FTS5
• Complete search UI
• Custom slugs via Micropub mp-slug
• RSS feed ordering fix
• Migration system improvements

v1.0.1 (2025-11-24)

• Fixed Micropub URL double-slash bug
• Minor bug fixes

v1.0.0 (2025-11-24)

• Initial production release
• IndieAuth authentication
• Micropub server implementation
• Notes CRUD functionality
• RSS feed generation
• Web interface (public & admin)

Future Roadmap

v1.1.1 "Polish" (Superseded)

Timeline: Completed as hotfix Status: Released as hotfix (2025-11-26) Note: Critical fixes released immediately, remaining scope moved to v1.2.0

Planned Features:

Search Configuration System (3-4 hours)

• SEARCH_ENABLED flag for sites that don't need search
• SEARCH_TITLE_LENGTH configurable limit (currently hardcoded at 100)
• Enhanced search term highlighting in results
• Search result relevance scoring display
• Graceful FTS5 degradation with fallback to LIKE queries

Performance Monitoring Foundation (4-6 hours)

• Add timing instrumentation to key operations
• Database query performance logging
• Slow query detection and warnings (configurable threshold)
• Memory usage tracking in production
• /admin/performance dashboard with real-time metrics

Production Readiness Improvements (3-5 hours)

• Graceful degradation when FTS5 unavailable
• Better error messages for common configuration issues
• Database connection pooling optimization
• Improved logging structure with configurable levels
• Enhanced health check endpoints (/health and /health/ready)

Bug Fixes & Edge Cases (2-3 hours)

• Fix 10 flaky timing tests from migration race conditions
• Handle Unicode edge cases in slug generation
• RSS feed memory optimization for large note counts
• Session timeout handling improvements

Technical Decisions:

• ADR-052: Configuration System Architecture
• ADR-053: Performance Monitoring Strategy
• ADR-054: Structured Logging Architecture
• ADR-055: Error Handling Philosophy

v1.1.2 "Syndicate" (Completed)

Timeline: Completed 2025-11-27 Status: Released Actual Effort: ~10 hours across 3 phases Focus: Expanded syndication format support

Delivered Features:

• ✅ Phase 1: Metrics Instrumentation
  • Comprehensive metrics collection system
  • Business metrics tracking for feed operations
  • Foundation for performance monitoring
• ✅ Phase 2: Multi-Format Feeds
  • RSS 2.0 (existing, enhanced)
  • ATOM 1.0 feed at /feed.atom (RFC 4287 compliant)
  • JSON Feed 1.1 at /feed.json
  • Content negotiation at /feed
  • Auto-discovery links for all formats
• ✅ Phase 3: Feed Enhancements
  • Feed caching with LRU eviction (50 entries max)
  • TTL-based expiration (5 minutes default)
  • ETag support with SHA-256 checksums
  • HTTP 304 conditional responses
  • Feed statistics dashboard
  • OPML 2.0 export at /opml.xml
  • Content-Type negotiation (optional)
  • Feed validation tests

See: ADR-038: Syndication Formats

v1.2.0 "Polish"

Timeline: December 2025 (Next Release) Focus: Quality improvements and production readiness Effort: 12-18 hours

Next Planned Features:

• Search Configuration System (3-4 hours)
  • SEARCH_ENABLED flag for sites that don't need search
  • SEARCH_TITLE_LENGTH configurable limit
  • Enhanced search term highlighting
  • Search result relevance scoring display
• Performance Monitoring Dashboard (4-6 hours)
  • Extend existing metrics infrastructure
  • Database query performance tracking
  • Memory usage monitoring
  • /admin/performance dedicated dashboard
• Production Improvements (3-5 hours)
  • Better error messages for configuration issues
  • Enhanced health check endpoints
  • Database connection pooling optimization
  • Structured logging with configurable levels
• Bug Fixes (2-3 hours)
  • Unicode edge cases in slug generation
  • Session timeout handling improvements
  • RSS feed memory optimization for large counts

v1.3.0 "Semantic"

Timeline: Q1 2026 Focus: Enhanced semantic markup and organization Effort: 10-16 hours for microformats2, plus category system

Planned Features:

• Strict Microformats2 Compliance (10-16 hours)
  • Complete h-entry properties (p-name, p-summary, p-author)
  • Author h-card implementation
  • h-feed wrapper for index pages
  • Full IndieWeb parser compatibility
  • Microformats2 validation suite
  • See: ADR-040: Microformats2 Compliance
• Tag/Category System
  • Database schema for tags
  • Tag-based filtering
  • Tag clouds
  • Category RSS/ATOM/JSON feeds
  • p-category microformats2 support
• Hierarchical Slugs
  • Support for / in slugs
  • Directory-like organization
  • Breadcrumb navigation with microformats2
• Draft Management
  • Explicit draft status
  • Draft preview
  • Scheduled publishing
• Search Enhancements
  • Tag search
  • Date range filtering
  • Advanced query syntax

v1.4.0 "Connections"

Timeline: Q2 2026 Focus: IndieWeb social features

Planned Features:

• Webmentions
  • Receive endpoint
  • Send on publish
  • Display received mentions
  • Moderation interface
• IndieAuth Provider (optional)
  • Self-hosted IndieAuth server
  • Token endpoint
  • Client registration
• Reply Contexts
  • In-reply-to support
  • Like/repost posts
  • Bookmark posts

v1.4.0 "Media"

Timeline: Q3 2026 Focus: Rich content support

Planned Features:

• Media Uploads
  • Image upload via Micropub
  • File management interface
  • Thumbnail generation
  • CDN integration (optional)
• Photo Posts
  • Instagram-like photo notes
  • Gallery views
  • EXIF data preservation
• Video/Audio Support
  • Embed support
  • Podcast RSS (optional)

v2.0.0 "MultiUser"

Timeline: 2027 Focus: Multi-author support (BREAKING CHANGES)

Major Features:

• User Management
  • Multiple authors
  • Role-based permissions
  • User profiles
• Content Attribution
  • Per-note authorship
  • Author pages
  • Author RSS feeds
• Collaborative Features
  • Draft sharing
  • Editorial workflow
  • Comment system

Design Principles

All future development will maintain these core principles:

1. Simplicity First: Every feature must justify its complexity
2. IndieWeb Standards: Full compliance with specifications
3. Progressive Enhancement: Core functionality works without JavaScript
4. Data Portability: User data remains exportable and portable
5. Backwards Compatibility: Minor versions preserve compatibility

Feature Request Process

To propose new features:

1. Check Alignment

   • Does it align with IndieWeb principles?
   • Does it solve a real user problem?
   • Can it be implemented simply?

2. Document Proposal

   • Create issue or discussion
   • Describe use case clearly
   • Consider implementation complexity

3. Architectural Review

   • Impact on existing features
   • Database schema changes
   • API compatibility

4. Priority Assessment

   • User value vs. complexity
   • Maintenance burden
   • Dependencies on other features

Deferred Features

These features have been considered but deferred indefinitely:

• Static Site Generation: Conflicts with dynamic Micropub
• Multi-language UI: Low priority for single-user system
• Advanced Analytics: Privacy concerns, use external tools
• Comments System: Use Webmentions instead
• WYSIWYG Editor: Markdown is sufficient
• Mobile App: Web interface is mobile-friendly

Support Lifecycle

Version Support

• Current Release (v1.1.0): Full support
• Previous Minor (v1.0.x): Security fixes only
• Older Versions: Community support only

Compatibility Promise

• Database: Migrations always provided
• API: Micropub/IndieAuth remain stable
• Configuration: Changes documented in upgrade guides

Contributing

StarPunk welcomes contributions that align with its philosophy:

Code Contributions

• Follow existing patterns
• Include tests
• Document changes
• Keep it simple

Documentation

• User guides
• API documentation
• Deployment guides
• Migration guides

Testing

• Bug reports with reproduction steps
• Compatibility testing
• Performance testing
• Security testing

Technology Evolution

Near-term Considerations

• Python 3.12+ adoption
• SQLite WAL mode
• HTTP/2 support
• Container optimizations

Long-term Possibilities

• Alternative database backends (PostgreSQL)
• Federation protocols (ActivityPub)
• Real-time features (WebSockets)
• AI-assisted writing (local models)

Success Metrics

StarPunk success is measured by:

• Simplicity: Lines of code remain minimal
• Reliability: Uptime and stability
• Standards Compliance: Passing validators
• User Satisfaction: Feature completeness
• Performance: Response times <300ms

Philosophy

"Every line of code must justify its existence. When in doubt, leave it out."

This philosophy guides all development decisions. StarPunk aims to be the simplest possible IndieWeb CMS that works correctly, not the most feature-rich.

---

Document Created: 2025-11-25 Last Updated: 2025-11-25 Status: Living Document

For the latest updates, see:

• Release Notes
• Project Plan
• Architecture Decisions