StarPunk/docs/projectplan/v1.1/potential-features.md

StarPunk V1.1: Potential Features

Overview

This document tracks features that were considered for StarPunk V1.0 but have been deferred to V1.1 or later releases. These features represent enhancements and additions that would improve the system but are not essential for the initial release.

Status: Planning / Future Consideration Related Documents:

• V1.0 Implementation Plan
• Architecture Overview

Feature Categories

Features are organized by category and priority for V1.1 planning.

---

Search and Discovery

Full-Text Note Search

Status: Deferred from V1.0 Phase 2.1 Priority: MEDIUM Estimated Effort: 3-4 hours

Description: Implement full-text search functionality across all note content to help users find specific notes quickly.

Proposed Function: search_notes() in starpunk/notes.py

Type Signature:

def search_notes(
    query: str,
    published_only: bool = False,
    limit: int = 50,
    offset: int = 0
) -> list[Note]:
    """
    Search notes by content

    Performs full-text search across note content (markdown files).
    Returns matching notes sorted by relevance or date.

    Args:
        query: Search query string
        published_only: If True, only search published notes
        limit: Maximum number of results to return
        offset: Pagination offset

    Returns:
        List of matching Note objects

    Examples:
        >>> results = search_notes("python programming")
        >>> for note in results:
        ...     print(note.slug, note.title)
    """

Implementation Options:

1. Simple grep-based search (Simplest)

   • Use Python's file search or subprocess to grep through markdown files
   • Pros: Zero dependencies, fast for small collections
   • Cons: Limited relevance ranking, no stemming
   • Fitness: 7/10 for single-user blog with <1000 notes

2. Python full-text search (Moderate complexity)

   • Use whoosh library for pure-Python full-text search
   • Pros: Better relevance ranking, stemming support
   • Cons: Adds dependency, requires index maintenance
   • Fitness: 8/10 for better search quality

3. SQLite FTS5 (Database-integrated)

   • Use SQLite's FTS5 extension for full-text search
   • Pros: Integrated with existing database, good performance
   • Cons: Requires content duplication in FTS table
   • Fitness: 9/10 for best integration

Recommended Approach: Start with SQLite FTS5 for V1.1

• Create shadow FTS5 table for note content
• Update on note create/update/delete
• Query with native SQLite FTS syntax
• Simple integration with existing database

Requirements:

• Search across all note content (markdown text)
• Support published_only filter
• Pagination support (limit/offset)
• Reasonable performance (< 100ms for typical queries)
• Optional: Highlight search terms in results
• Optional: Sort by relevance or date

Edge Cases:

• Empty query string
• Very long queries
• Special characters in query
• Unicode/emoji in content
• Very large note collections (>10,000 notes)

Testing Requirements:

• Search finds exact matches
• Search handles case-insensitive matching
• Search respects published_only filter
• Pagination works correctly
• Performance acceptable for expected data volumes

Documentation Needed:

• User guide for search syntax
• API documentation
• Performance characteristics
• Index maintenance procedures (if applicable)

References:

• SQLite FTS5 documentation: https://www.sqlite.org/fts5.html
• IndieWeb search considerations

---

Content Management Enhancements

Custom Slug Support

Status: Future consideration Priority: LOW Estimated Effort: 1-2 hours

Description: Allow users to specify custom slugs when creating notes, instead of always generating from content.

Rationale: Some users prefer explicit control over URLs for SEO or aesthetics.

Implementation:

• Add optional custom_slug parameter to create_note()
• Validate custom slug format
• Still check uniqueness
• Fall back to generated slug if custom slug invalid

Example:

note = create_note(
    content="My note content",
    published=True,
    custom_slug="my-preferred-slug"
)

---

Note Tags/Categories

Status: Future consideration Priority: MEDIUM Estimated Effort: 6-8 hours

Description: Add support for tagging notes with categories or tags for organization.

Requirements:

• Add tags table to database
• Add note_tags junction table
• Update Note model with tags property
• Add tag filtering to list_notes()
• Add tag management functions (create_tag, delete_tag, etc.)
• Support tag-based RSS feeds

IndieWeb Considerations:

• Map to Micropub categories property
• Include in h-entry microformats
• Support in RSS feed

---

Media Attachments

Status: Future consideration Priority: MEDIUM Estimated Effort: 10-12 hours

Description: Support uploading and attaching images/media to notes.

Requirements:

• File upload handling
• Image storage and organization
• Thumbnail generation
• Media model and database table
• Micropub media endpoint
• Image optimization (optional)

References:

• Micropub Media Endpoint spec

---

IndieWeb Features

Webmentions

Status: Future consideration Priority: HIGH (for IndieWeb compliance) Estimated Effort: 8-10 hours

Description: Support sending and receiving Webmentions for note interactions.

Requirements:

• Webmention endpoint
• Webmention verification
• Display received mentions
• Send webmentions for published notes
• Moderation interface

References:

• Webmention spec: https://www.w3.org/TR/webmention/

---

Syndication (POSSE)

Status: Future consideration Priority: MEDIUM Estimated Effort: 15-20 hours

Description: Automatically syndicate notes to social media platforms (Twitter, Mastodon, etc.)

Requirements:

• OAuth integration for each platform
• Syndication configuration UI
• Syndication status tracking
• Error handling and retry logic
• Syndication URLs stored with notes

IndieWeb Concept: POSSE (Publish on your Own Site, Syndicate Elsewhere)

---

Performance and Scalability

Content Caching

Status: Future consideration Priority: LOW Estimated Effort: 4-5 hours

Description: Cache rendered HTML and RSS feeds for better performance.

Implementation:

• Redis or file-based cache
• Cache invalidation on note updates
• Configurable TTL

Note: May not be needed for single-user system with modest traffic

---

Static Site Generation

Status: Future consideration Priority: LOW Estimated Effort: 20-30 hours

Description: Generate static HTML for all published notes for maximum performance.

Rationale: Static sites are faster and can be hosted anywhere (S3, Netlify, etc.)

Challenges:

• Requires complete rewrite of delivery model
• Micropub integration becomes more complex
• May not align with V1 goals

---

User Experience

Rich Text Editor

Status: Future consideration Priority: LOW Estimated Effort: 8-10 hours

Description: Add a rich text editor with markdown preview for the admin interface.

Options:

• SimpleMDE
• CodeMirror
• Quill
• Custom solution

Note: Plain textarea with markdown is sufficient for V1

---

Draft Management

Status: Future consideration Priority: MEDIUM Estimated Effort: 3-4 hours

Description: Better support for draft notes separate from published notes.

Requirements:

• Explicit draft status (not just published=False)
• Draft-only views in admin
• Auto-save drafts
• Schedule publishing (optional)

---

Administration

Multi-User Support

Status: Future consideration (V2+) Priority: LOW (changes core architecture) Estimated Effort: 40-60 hours

Description: Support multiple authors with different permissions.

Scope: This is a major architectural change and likely belongs in V2, not V1.1.

Requirements:

• User management
• Permissions system
• Author attribution
• Multi-user IndieAuth

---

Analytics Integration

Status: Future consideration Priority: LOW Estimated Effort: 2-3 hours

Description: Add privacy-respecting analytics (e.g., Plausible, GoatCounter).

Implementation:

• Configuration for analytics provider
• Template integration
• Privacy policy considerations

---

Backup and Export

Status: Future consideration Priority: MEDIUM Estimated Effort: 4-5 hours

Description: Automated backup and data export functionality.

Requirements:

• Export all notes as zip/tar archive
• Export database
• Automated backup scheduling
• Import functionality for migration

---

Technical Improvements

API Documentation

Status: Future consideration Priority: MEDIUM Estimated Effort: 4-6 hours

Description: Generate API documentation for Micropub and other endpoints.

Tools:

• OpenAPI/Swagger
• Sphinx for Python docs
• Custom documentation site

---

Monitoring and Logging

Status: Future consideration Priority: LOW Estimated Effort: 3-4 hours

Description: Structured logging and basic monitoring.

Requirements:

• Structured JSON logging
• Log rotation
• Error tracking (Sentry, etc.)
• Health check endpoint

---

Decision Process for V1.1

When planning V1.1, features should be evaluated using:

1. IndieWeb Alignment: Does it improve IndieWeb compliance?
2. User Value: Does it solve a real user problem?
3. Simplicity: Can it be implemented without significant complexity?
4. Maintenance: Does it add ongoing maintenance burden?
5. Dependencies: Does it require new external dependencies?

Priority Scoring:

• HIGH: Essential for IndieWeb functionality or major user value
• MEDIUM: Useful but not essential
• LOW: Nice to have, minimal impact

---

References

• V1.0 Implementation Plan
• Architecture Overview
• IndieWeb Principles
• Micropub Specification
• Webmention Specification

---

Contributing

To propose a new feature for V1.1:

1. Add it to this document in the appropriate category
2. Include status, priority, and effort estimate
3. Provide clear description and requirements
4. Consider IndieWeb alignment
5. Evaluate against V1 simplicity principles

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