phil/StarPunk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
41b65703f9367efb8188433341f8758aaba830ac
StarPunk/docs/design/v1.2.0/2025-11-28-v1.2.0-design-complete.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

4.1 KiB
Raw Blame History

v1.2.0 Design Review - Complete

Date: 2025-11-28 Architect: StarPunk Architect Subagent Status: Design Complete and Ready for Implementation

Executive Summary

The v1.2.0 feature specification has been updated with all user decisions and architectural designs. The three core features (Custom Slugs, Media Upload, Microformats2) are fully specified with implementation details, database schemas, and edge case handling.

User Decisions Incorporated

1. Custom Slugs

  • Decision: Read-only after creation (Option B)
  • Implementation: Field disabled on edit form with warning message
  • Rationale: Prevents broken permalinks

2. Media Upload

  • Storage: data/media/ directory (Option A)
  • URL Structure: Date-organized /media/2025/01/filename.jpg (Option A)
  • Insertion: Auto-insert markdown at cursor position (Option A)
  • Tracking: Database table for metadata (Option A)
  • Format: Minimal markdown ![](url) for simplicity

3. Microformats2 / Author Discovery

  • Critical Decision: Author info discovered from IndieAuth profile URL
  • NOT environment variables or config files
  • Implementation: New discovery system with caching
  • h-card Placement: Only within h-entries (Option B)
  • Fallback: Graceful degradation when discovery fails

Architectural Decisions

ADR-061: Author Profile Discovery

Created new Architecture Decision Record documenting:

  • Discovery from IndieAuth profile URL
  • Database caching strategy
  • Fallback behavior
  • Integration with existing auth flow

Database Changes

Two new tables required:

  1. media - Track uploaded files with metadata
  2. author_profile - Cache discovered author information

Security Considerations

  • Media validation (MIME types, file size)
  • Slug validation (URL-safe characters)
  • Directory traversal prevention
  • No SVG uploads (XSS risk)

Implementation Guidance

Phase 1: Custom Slugs (Simplest)

  • Template changes only
  • Validation in existing create/edit routes
  • No database changes needed

Phase 2: Microformats2 + Author Discovery

  • Build discovery module first
  • Integrate with auth flow
  • Update templates with discovered data
  • Add manual refresh in admin

Phase 3: Media Upload (Most Complex)

  • Create media module
  • Database migration for media table
  • AJAX upload endpoint
  • Cursor tracking JavaScript

Standards Compliance Verified

Microformats2

  • h-entry: All properties optional (confirmed via spec)
  • h-feed: Proper container structure
  • h-card: Standard properties for author
  • rel-me: Identity verification links

IndieWeb

  • IndieAuth profile discovery pattern
  • Micropub compatibility maintained
  • RSS/Atom feed preservation

Edge Cases Addressed

Author Discovery

  • Multiple h-cards on profile
  • Missing properties
  • Network failures
  • Invalid markup
  • All have graceful fallbacks

Media Upload

  • Concurrent uploads
  • Orphaned files
  • Invalid MIME types
  • File size limits

Custom Slugs

  • Uniqueness validation
  • Character restrictions
  • Immutability enforcement

No Outstanding Questions

All user requirements have been addressed. The design is complete and ready for developer implementation.

Success Criteria Defined

Eight clear metrics for v1.2.0 success:

  1. Custom slug specification (immutable)
  2. Image upload with auto-insertion
  3. Author discovery from IndieAuth
  4. IndieWebify.me Level 2 pass
  5. Test suite passes
  6. No regressions
  7. Media tracking in database
  8. Graceful failure handling

Recommendation

The v1.2.0 design is COMPLETE and ready for implementation. The developer should:

  1. Review /docs/design/v1.2.0/feature-specification.md
  2. Review /docs/decisions/ADR-061-author-discovery.md
  3. Follow the recommended implementation order
  4. Create implementation reports in /docs/reports/
  5. Update CHANGELOG.md with changes

Files Created/Updated

  • /docs/design/v1.2.0/feature-specification.md - UPDATED with all decisions
  • /docs/decisions/ADR-061-author-discovery.md - NEW architecture decision
  • /docs/reviews/2025-11-28-v1.2.0-design-complete.md - THIS DOCUMENT

Next Steps

Hand off to developer for implementation following the specified design.

Reference in New Issue View Git Blame Copy Permalink