Phil Skentelbery
f10d0679da
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>
140 lines
4.1 KiB
Markdown
140 lines
4.1 KiB
Markdown
# 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 `` 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. |