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>
This commit is contained in:
@@ -1,166 +0,0 @@
|
||||
# StarPunk Project Planning Index
|
||||
|
||||
## Overview
|
||||
|
||||
This directory contains all project planning documentation for StarPunk, organized by version and planning phase. Use this index to navigate to the appropriate documentation.
|
||||
|
||||
## Current Status
|
||||
|
||||
**Latest Release**: v1.1.0 "SearchLight" (2025-11-25)
|
||||
**Project Status**: Production Ready - V1 Feature Complete
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
/docs/projectplan/
|
||||
├── INDEX.md (this file)
|
||||
├── ROADMAP.md → Future development roadmap
|
||||
├── v1/ → V1.0 planning (COMPLETE)
|
||||
│ ├── README.md → V1 planning overview
|
||||
│ ├── implementation-plan.md → Detailed implementation phases
|
||||
│ ├── feature-scope.md → In/out of scope decisions
|
||||
│ ├── quick-reference.md → Developer quick reference
|
||||
│ └── dependencies-diagram.md → Module dependencies
|
||||
└── v1.1/ → V1.1 planning (COMPLETE)
|
||||
├── RELEASE-STATUS.md → V1.1.0 release tracking
|
||||
├── priority-work.md → Completed priority items
|
||||
└── potential-features.md → Feature backlog
|
||||
```
|
||||
|
||||
## Quick Navigation
|
||||
|
||||
### For Current Development
|
||||
- [Roadmap](/home/phil/Projects/starpunk/docs/projectplan/ROADMAP.md) - Future versions and features
|
||||
- [V1.1 Release Status](/home/phil/Projects/starpunk/docs/projectplan/v1.1/RELEASE-STATUS.md) - Latest release details
|
||||
|
||||
### For Historical Reference
|
||||
- [V1 Implementation Plan](/home/phil/Projects/starpunk/docs/projectplan/v1/implementation-plan.md) - How V1 was built
|
||||
- [Feature Scope](/home/phil/Projects/starpunk/docs/projectplan/v1/feature-scope.md) - V1 scope decisions
|
||||
|
||||
### For Daily Work
|
||||
- [Quick Reference](/home/phil/Projects/starpunk/docs/projectplan/v1/quick-reference.md) - Commands and lookups
|
||||
- [Potential Features](/home/phil/Projects/starpunk/docs/projectplan/v1.1/potential-features.md) - Feature backlog
|
||||
|
||||
## Version History
|
||||
|
||||
### V1.1.0 "SearchLight" (Released 2025-11-25)
|
||||
- Full-text search with FTS5
|
||||
- Custom slugs via Micropub
|
||||
- RSS feed fixes
|
||||
- Migration improvements
|
||||
- [Full Release Details](/home/phil/Projects/starpunk/docs/projectplan/v1.1/RELEASE-STATUS.md)
|
||||
|
||||
### V1.0.0 (Released 2025-11-24)
|
||||
- IndieAuth authentication
|
||||
- Micropub endpoint
|
||||
- Notes management
|
||||
- RSS syndication
|
||||
- Web interface
|
||||
- [Implementation Report](/home/phil/Projects/starpunk/docs/reports/v1.0.0-implementation-report.md)
|
||||
|
||||
## Key Documents
|
||||
|
||||
### Planning Documents
|
||||
1. **[Roadmap](/home/phil/Projects/starpunk/docs/projectplan/ROADMAP.md)**
|
||||
- Future version planning
|
||||
- Feature timeline
|
||||
- Design principles
|
||||
|
||||
2. **[V1 Implementation Plan](/home/phil/Projects/starpunk/docs/projectplan/v1/implementation-plan.md)**
|
||||
- Phase-by-phase implementation
|
||||
- Task tracking
|
||||
- Test requirements
|
||||
|
||||
3. **[Feature Scope](/home/phil/Projects/starpunk/docs/projectplan/v1/feature-scope.md)**
|
||||
- In/out of scope matrix
|
||||
- Decision framework
|
||||
- Lines of code budget
|
||||
|
||||
### Status Documents
|
||||
1. **[V1.1 Release Status](/home/phil/Projects/starpunk/docs/projectplan/v1.1/RELEASE-STATUS.md)**
|
||||
- Latest release tracking
|
||||
- Completed features
|
||||
- Test coverage
|
||||
|
||||
2. **[Priority Work](/home/phil/Projects/starpunk/docs/projectplan/v1.1/priority-work.md)**
|
||||
- Critical items (completed)
|
||||
- Implementation notes
|
||||
- Success criteria
|
||||
|
||||
### Reference Documents
|
||||
1. **[Quick Reference](/home/phil/Projects/starpunk/docs/projectplan/v1/quick-reference.md)**
|
||||
- Common commands
|
||||
- File checklist
|
||||
- Configuration guide
|
||||
|
||||
2. **[Potential Features](/home/phil/Projects/starpunk/docs/projectplan/v1.1/potential-features.md)**
|
||||
- Feature backlog
|
||||
- Implementation options
|
||||
- Priority scoring
|
||||
|
||||
## Related Documentation
|
||||
|
||||
### Architecture
|
||||
- [Architecture Overview](/home/phil/Projects/starpunk/docs/architecture/overview.md)
|
||||
- [Technology Stack](/home/phil/Projects/starpunk/docs/architecture/technology-stack.md)
|
||||
- [Architecture Decision Records](/home/phil/Projects/starpunk/docs/decisions/)
|
||||
|
||||
### Implementation Reports
|
||||
- [V1.1.0 Implementation Report](/home/phil/Projects/starpunk/docs/reports/v1.1.0-implementation-report.md)
|
||||
- [V1.0.0 Implementation Report](/home/phil/Projects/starpunk/docs/reports/v1.0.0-implementation-report.md)
|
||||
- [All Reports](/home/phil/Projects/starpunk/docs/reports/)
|
||||
|
||||
### Standards
|
||||
- [Python Coding Standards](/home/phil/Projects/starpunk/docs/standards/python-coding-standards.md)
|
||||
- [Git Branching Strategy](/home/phil/Projects/starpunk/docs/standards/git-branching-strategy.md)
|
||||
- [Versioning Strategy](/home/phil/Projects/starpunk/docs/standards/versioning-strategy.md)
|
||||
|
||||
## How to Use This Documentation
|
||||
|
||||
### For New Contributors
|
||||
1. Read the [Roadmap](/home/phil/Projects/starpunk/docs/projectplan/ROADMAP.md)
|
||||
2. Review [Feature Scope](/home/phil/Projects/starpunk/docs/projectplan/v1/feature-scope.md)
|
||||
3. Check [Potential Features](/home/phil/Projects/starpunk/docs/projectplan/v1.1/potential-features.md)
|
||||
|
||||
### For Implementation
|
||||
1. Check [Current Status](#current-status) above
|
||||
2. Review relevant ADRs in `/docs/decisions/`
|
||||
3. Follow [Quick Reference](/home/phil/Projects/starpunk/docs/projectplan/v1/quick-reference.md)
|
||||
4. Document in `/docs/reports/`
|
||||
|
||||
### For Planning
|
||||
1. Review [Roadmap](/home/phil/Projects/starpunk/docs/projectplan/ROADMAP.md)
|
||||
2. Check [Feature Backlog](/home/phil/Projects/starpunk/docs/projectplan/v1.1/potential-features.md)
|
||||
3. Create ADRs for major decisions
|
||||
4. Update this index when adding documents
|
||||
|
||||
## Maintenance
|
||||
|
||||
This planning documentation should be updated:
|
||||
- After each release (update status, versions)
|
||||
- When planning new features (update roadmap)
|
||||
- When making scope decisions (update feature documents)
|
||||
- When creating new planning documents (update this index)
|
||||
|
||||
## Success Metrics
|
||||
|
||||
Project planning success is measured by:
|
||||
- ✅ All V1 features implemented
|
||||
- ✅ 598 tests (588 passing)
|
||||
- ✅ IndieWeb compliance achieved
|
||||
- ✅ Documentation complete
|
||||
- ✅ Production ready
|
||||
|
||||
## Philosophy
|
||||
|
||||
> "Every line of code must justify its existence. When in doubt, leave it out."
|
||||
|
||||
This philosophy guides all planning and implementation decisions.
|
||||
|
||||
---
|
||||
|
||||
**Index Created**: 2025-11-25
|
||||
**Last Updated**: 2025-11-25
|
||||
**Maintained By**: StarPunk Architect
|
||||
|
||||
For questions about project planning, consult the Architect agent or review the ADRs.
|
||||
@@ -1,368 +0,0 @@
|
||||
# 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](/home/phil/Projects/starpunk/docs/decisions/ADR-052-configuration-system-architecture.md)
|
||||
- [ADR-053: Performance Monitoring Strategy](/home/phil/Projects/starpunk/docs/decisions/ADR-053-performance-monitoring-strategy.md)
|
||||
- [ADR-054: Structured Logging Architecture](/home/phil/Projects/starpunk/docs/decisions/ADR-054-structured-logging-architecture.md)
|
||||
- [ADR-055: Error Handling Philosophy](/home/phil/Projects/starpunk/docs/decisions/ADR-055-error-handling-philosophy.md)
|
||||
|
||||
### 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](/home/phil/Projects/starpunk/docs/decisions/ADR-038-syndication-formats.md)
|
||||
|
||||
### 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, organization, and advanced feed media
|
||||
**Effort**: 10-16 hours for microformats2, 12-18 hours for feed media, 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](/home/phil/Projects/starpunk/docs/decisions/ADR-040-microformats2-compliance.md)
|
||||
- **Enhanced Feed Media Support** (12-18 hours) - Full Standardization Phase A
|
||||
- Multiple image sizes/thumbnails (150px, 320px, 640px, 1280px)
|
||||
- Full Media RSS implementation (media:group, all attributes)
|
||||
- Enhanced JSON Feed attachments
|
||||
- ATOM enclosure links for all media
|
||||
- See: [ADR-059: Full Feed Media Standardization](/home/phil/Projects/starpunk/docs/decisions/ADR-059-full-feed-media-standardization.md)
|
||||
- **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 and podcast/video syndication
|
||||
|
||||
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
|
||||
- **Audio/Podcast Support** (10-16 hours) - Full Standardization Phase B
|
||||
- Podcast RSS with iTunes namespace
|
||||
- Audio duration extraction
|
||||
- Episode metadata support
|
||||
- Apple/Google podcast compatibility
|
||||
- See: [ADR-059: Full Feed Media Standardization](/home/phil/Projects/starpunk/docs/decisions/ADR-059-full-feed-media-standardization.md)
|
||||
- **Video Support** (16-24 hours) - Full Standardization Phase C
|
||||
- Video upload handling
|
||||
- Poster image generation
|
||||
- Video in Media RSS feeds
|
||||
- HTML5 video embedding
|
||||
|
||||
### 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](/home/phil/Projects/starpunk/CHANGELOG.md)
|
||||
- [Project Plan](/home/phil/Projects/starpunk/docs/projectplan/)
|
||||
- [Architecture Decisions](/home/phil/Projects/starpunk/docs/decisions/)
|
||||
@@ -1,220 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,222 +0,0 @@
|
||||
# StarPunk v1.1.0 "SearchLight" Release Status
|
||||
|
||||
## Release Overview
|
||||
|
||||
**Version**: v1.1.0
|
||||
**Codename**: SearchLight
|
||||
**Release Date**: 2025-11-25
|
||||
**Status**: RELEASED ✅
|
||||
**Previous Version**: v1.0.1
|
||||
|
||||
## Completed Features
|
||||
|
||||
### Core Features
|
||||
|
||||
#### 1. Full-Text Search with FTS5 ✅
|
||||
**Status**: COMPLETE
|
||||
**ADR**: ADR-034
|
||||
**Report**: `/home/phil/Projects/starpunk/docs/reports/v1.1.0-implementation-report.md`
|
||||
**Implementation**:
|
||||
- SQLite FTS5 virtual table for search
|
||||
- Complete search UI with results page
|
||||
- API endpoint `/api/search`
|
||||
- Navigation search box integration
|
||||
- Security hardening (XSS prevention, query validation)
|
||||
- 41 new tests (API, integration, security)
|
||||
|
||||
#### 2. Custom Slugs via Micropub mp-slug ✅
|
||||
**Status**: COMPLETE
|
||||
**ADR**: ADR-035
|
||||
**Report**: `/home/phil/Projects/starpunk/docs/reports/v1.1.0-implementation-report.md`
|
||||
**Implementation**:
|
||||
- Micropub mp-slug property extraction
|
||||
- Slug validation and sanitization
|
||||
- Reserved slug protection
|
||||
- Sequential numbering for conflicts
|
||||
- Integration with notes.py
|
||||
|
||||
#### 3. Database Migration System Redesign ✅
|
||||
**Status**: COMPLETE
|
||||
**ADR**: ADR-033
|
||||
**Report**: `/home/phil/Projects/starpunk/docs/reports/v1.1.0-implementation-report.md`
|
||||
**Implementation**:
|
||||
- Renamed SCHEMA_SQL to INITIAL_SCHEMA_SQL
|
||||
- Clear documentation of baseline vs current schema
|
||||
- Improved migration system clarity
|
||||
- No functional changes (documentation improvement)
|
||||
|
||||
#### 4. RSS Feed Ordering Fix ✅
|
||||
**Status**: COMPLETE
|
||||
**ADR**: None (bug fix)
|
||||
**Report**: `/home/phil/Projects/starpunk/docs/reports/v1.1.0-implementation-report.md`
|
||||
**Implementation**:
|
||||
- Fixed feedgen order reversal bug
|
||||
- Added regression test
|
||||
- Newest posts now display first
|
||||
|
||||
#### 5. Custom Slug Extraction Bug Fix ✅
|
||||
**Status**: COMPLETE
|
||||
**ADR**: None (bug fix)
|
||||
**Implementation**:
|
||||
- Fixed mp-slug extraction from Micropub requests
|
||||
- Proper error handling for invalid slugs
|
||||
|
||||
## Technical Improvements
|
||||
|
||||
### Architecture Decision Records (ADRs)
|
||||
|
||||
| ADR | Title | Status | Notes |
|
||||
|-----|-------|--------|-------|
|
||||
| ADR-033 | Database Migration Redesign | IMPLEMENTED | Clear baseline schema |
|
||||
| ADR-034 | Full-Text Search | IMPLEMENTED | FTS5 with UI |
|
||||
| ADR-035 | Custom Slugs | IMPLEMENTED | mp-slug support |
|
||||
| ADR-036 | IndieAuth Token Verification Method | DOCUMENTED | Design decision |
|
||||
| ADR-039 | Micropub URL Construction Fix | IMPLEMENTED | v1.0.x fix |
|
||||
|
||||
### Test Coverage
|
||||
|
||||
- **New Tests Added**: 41 (search functionality)
|
||||
- **Total Tests**: 598
|
||||
- **Passing**: 588
|
||||
- **Known Issues**: 10 flaky timing tests (pre-existing, race condition tests)
|
||||
- **Coverage Areas**:
|
||||
- Search API validation
|
||||
- Search UI integration
|
||||
- Search security (XSS, SQL injection)
|
||||
- RSS feed ordering
|
||||
- Custom slug validation
|
||||
|
||||
## Files Changed
|
||||
|
||||
### New Files
|
||||
- `migrations/005_add_fts5_search.sql`
|
||||
- `starpunk/routes/search.py`
|
||||
- `starpunk/search.py`
|
||||
- `starpunk/slug_utils.py`
|
||||
- `templates/search.html`
|
||||
- `tests/test_search_api.py`
|
||||
- `tests/test_search_integration.py`
|
||||
- `tests/test_search_security.py`
|
||||
|
||||
### Modified Files
|
||||
- `starpunk/__init__.py` (FTS index population)
|
||||
- `starpunk/database.py` (SCHEMA_SQL rename)
|
||||
- `starpunk/feed.py` (order fix)
|
||||
- `starpunk/migrations.py` (comments)
|
||||
- `starpunk/notes.py` (custom_slug, FTS integration)
|
||||
- `starpunk/micropub.py` (mp-slug extraction)
|
||||
- `starpunk/routes/__init__.py` (search routes)
|
||||
- `templates/base.html` (search box)
|
||||
- `tests/test_feed.py` (regression test)
|
||||
|
||||
## Version History
|
||||
|
||||
### v1.1.0 (2025-11-25) - "SearchLight"
|
||||
- Added full-text search with FTS5
|
||||
- Added custom slug support via Micropub mp-slug
|
||||
- Fixed RSS feed ordering (newest first)
|
||||
- Redesigned migration system documentation
|
||||
- Fixed custom slug extraction bug
|
||||
|
||||
### v1.0.x Series
|
||||
- **v1.0.1** (2025-11-24): Fixed Micropub URL double-slash bug
|
||||
- **v1.0.0** (2025-11-24): Initial release with IndieAuth + Micropub
|
||||
|
||||
## Backwards Compatibility
|
||||
|
||||
✅ **100% Backwards Compatible**
|
||||
- No breaking API changes
|
||||
- Existing notes display correctly
|
||||
- Existing Micropub clients work unchanged
|
||||
- Database migrations handle all upgrade paths
|
||||
- RSS feeds remain valid
|
||||
|
||||
## Deferred to v1.2.0
|
||||
|
||||
Based on architectural review, the following items are deferred:
|
||||
|
||||
1. **Hierarchical Slugs** - Slugs with `/` for subdirectories
|
||||
2. **Search Configuration** - SEARCH_ENABLED flag
|
||||
3. **Enhanced Highlighting** - Better search term highlighting
|
||||
4. **Configurable Title Length** - Make 100-char limit configurable
|
||||
|
||||
## Release Metrics
|
||||
|
||||
- **Development Time**: ~12 hours (all phases)
|
||||
- **Lines of Code Added**: ~1,500
|
||||
- **Test Coverage**: Maintained >85%
|
||||
- **Performance**: Search queries <100ms
|
||||
- **Security**: XSS and SQL injection prevention
|
||||
|
||||
## Quality Assurance
|
||||
|
||||
### Validation Completed
|
||||
- ✅ All tests pass (except pre-existing flaky tests)
|
||||
- ✅ RSS feed validates
|
||||
- ✅ Micropub compliance maintained
|
||||
- ✅ IndieAuth functionality unchanged
|
||||
- ✅ HTML validation passes
|
||||
- ✅ Security tests pass
|
||||
|
||||
### Manual Testing Required
|
||||
- [ ] Browser search functionality
|
||||
- [ ] Micropub client with mp-slug
|
||||
- [ ] RSS reader validation
|
||||
- [ ] Production upgrade path
|
||||
|
||||
## Release Notes
|
||||
|
||||
### For Users
|
||||
|
||||
**New Features:**
|
||||
- 🔍 **Full-Text Search**: Find notes quickly with the new search box in navigation
|
||||
- 🔗 **Custom URLs**: Set custom slugs when publishing via Micropub clients
|
||||
- 📰 **RSS Fix**: Feed now correctly shows newest posts first
|
||||
|
||||
**Improvements:**
|
||||
- Better error messages for invalid slugs
|
||||
- Faster note lookups with search indexing
|
||||
- More robust database migration system
|
||||
|
||||
### For Developers
|
||||
|
||||
**Technical Changes:**
|
||||
- SQLite FTS5 integration for search
|
||||
- New slug validation utilities
|
||||
- Improved migration system documentation
|
||||
- 41 new tests for search functionality
|
||||
|
||||
**API Changes:**
|
||||
- New endpoint: `GET /api/search?q=query`
|
||||
- New Micropub property: `mp-slug` support
|
||||
- Search results page: `/search?q=query`
|
||||
|
||||
## Support and Documentation
|
||||
|
||||
- **Implementation Report**: `/docs/reports/v1.1.0-implementation-report.md`
|
||||
- **ADRs**: `/docs/decisions/ADR-033` through `ADR-036`
|
||||
- **Migration Guide**: Automatic - no manual steps required
|
||||
- **API Documentation**: Updated in `/docs/api/`
|
||||
|
||||
## Next Steps
|
||||
|
||||
### Immediate (v1.1.1)
|
||||
- Optional search configuration flags
|
||||
- Enhanced search highlighting
|
||||
- Performance monitoring setup
|
||||
|
||||
### Future (v1.2.0)
|
||||
- Hierarchical slugs with subdirectories
|
||||
- Webmentions support
|
||||
- Media attachments
|
||||
- Tag system
|
||||
|
||||
## Conclusion
|
||||
|
||||
StarPunk v1.1.0 "SearchLight" successfully delivers critical search functionality, custom URL support, and important bug fixes while maintaining 100% backwards compatibility. The release represents a significant improvement in usability and functionality for the IndieWeb CMS.
|
||||
|
||||
---
|
||||
|
||||
**Document Created**: 2025-11-25
|
||||
**Status**: COMPLETE - Released
|
||||
**Next Version**: v1.1.1 (patch) or v1.2.0 (minor)
|
||||
@@ -1,445 +0,0 @@
|
||||
# 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](/home/phil/Projects/starpunk/docs/projectplan/v1/implementation-plan.md)
|
||||
- [Architecture Overview](/home/phil/Projects/starpunk/docs/architecture/overview.md)
|
||||
|
||||
## 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**:
|
||||
```python
|
||||
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**:
|
||||
```python
|
||||
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](/home/phil/Projects/starpunk/docs/projectplan/v1/implementation-plan.md)
|
||||
- [Architecture Overview](/home/phil/Projects/starpunk/docs/architecture/overview.md)
|
||||
- [IndieWeb Principles](https://indieweb.org/principles)
|
||||
- [Micropub Specification](https://www.w3.org/TR/micropub/)
|
||||
- [Webmention Specification](https://www.w3.org/TR/webmention/)
|
||||
|
||||
---
|
||||
|
||||
## 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."
|
||||
@@ -1,219 +0,0 @@
|
||||
# StarPunk v1.1.0: Priority Work Items
|
||||
|
||||
## Overview
|
||||
|
||||
This document tracked HIGH PRIORITY work items for the v1.1.0 release. All critical items have been successfully completed.
|
||||
|
||||
**Target Release**: v1.1.0
|
||||
**Status**: COMPLETED ✅
|
||||
**Created**: 2025-11-24
|
||||
**Released**: 2025-11-25
|
||||
|
||||
## Critical Priority Items
|
||||
|
||||
All critical items were successfully completed for v1.1.0 release.
|
||||
|
||||
---
|
||||
|
||||
### 1. Database Migration System Redesign - Phase 2 ✅
|
||||
|
||||
**Priority**: CRITICAL
|
||||
**ADR**: ADR-033
|
||||
**Actual Effort**: ~2 hours
|
||||
**Status**: COMPLETE
|
||||
**Implementation**: Renamed SCHEMA_SQL to INITIAL_SCHEMA_SQL for clarity
|
||||
|
||||
#### Problem
|
||||
The current database initialization system fails when upgrading existing production databases because SCHEMA_SQL represents the current schema rather than the initial v0.1.0 baseline. This causes indexes to be created on columns that don't exist yet.
|
||||
|
||||
#### Solution
|
||||
Implement INITIAL_SCHEMA_SQL as designed in ADR-032 to represent the v0.1.0 baseline schema. All schema evolution will happen through migrations.
|
||||
|
||||
#### Implementation Tasks
|
||||
|
||||
1. **Create INITIAL_SCHEMA_SQL constant** (`database.py`)
|
||||
```python
|
||||
INITIAL_SCHEMA_SQL = """
|
||||
-- V0.1.0 baseline schema from commit a68fd57
|
||||
-- [Full SQL as documented in ADR-032]
|
||||
"""
|
||||
```
|
||||
|
||||
2. **Modify init_db() function** (`database.py`)
|
||||
- Add database existence check
|
||||
- Use INITIAL_SCHEMA_SQL for fresh databases
|
||||
- Run migrations for all databases
|
||||
- See ADR-032 for complete logic
|
||||
|
||||
3. **Add helper functions** (`database.py`)
|
||||
- `database_exists_with_tables()`: Check if database has existing tables
|
||||
- Update imports and error handling
|
||||
|
||||
4. **Update existing SCHEMA_SQL** (`database.py`)
|
||||
- Rename to CURRENT_SCHEMA_SQL
|
||||
- Mark as documentation-only (not used for initialization)
|
||||
- Add clear comments explaining purpose
|
||||
|
||||
#### Testing Requirements
|
||||
|
||||
- [ ] Test fresh database initialization (should create v0.1.0 schema then migrate)
|
||||
- [ ] Test upgrade from existing v1.0.0-rc.2 database
|
||||
- [ ] Test upgrade from v0.x.x databases if available
|
||||
- [ ] Verify all indexes created correctly
|
||||
- [ ] Verify no duplicate table/index errors
|
||||
- [ ] Test migration tracking (schema_migrations table)
|
||||
- [ ] Performance test for fresh install (all migrations)
|
||||
|
||||
#### Documentation Updates
|
||||
|
||||
- [ ] Update database.py docstrings
|
||||
- [ ] Add inline comments explaining dual schema constants
|
||||
- [ ] Update deployment documentation
|
||||
- [ ] Add production upgrade guide
|
||||
- [ ] Update CHANGELOG.md
|
||||
|
||||
#### Success Criteria
|
||||
|
||||
- Existing databases upgrade without errors
|
||||
- Fresh databases initialize correctly
|
||||
- All migrations run in proper order
|
||||
- No index creation errors
|
||||
- Clear upgrade path from any version
|
||||
|
||||
---
|
||||
|
||||
### 2. IndieAuth Provider Strategy Implementation
|
||||
|
||||
**Priority**: HIGH
|
||||
**ADR**: ADR-021 (if exists)
|
||||
**Estimated Effort**: 8-10 hours
|
||||
**Dependencies**: Database migration system working correctly
|
||||
**Risk**: Medium (external service dependencies)
|
||||
|
||||
#### Problem
|
||||
Current IndieAuth implementation may need updates based on production usage patterns and compliance requirements.
|
||||
|
||||
#### Implementation Notes
|
||||
- Review existing ADR-021-indieauth-provider-strategy.md
|
||||
- Implement any pending IndieAuth improvements
|
||||
- Ensure full spec compliance
|
||||
|
||||
---
|
||||
|
||||
## Medium Priority Items
|
||||
|
||||
These items SHOULD be completed for v1.1.0 if time permits.
|
||||
|
||||
### 3. Full-Text Search Implementation ✅
|
||||
|
||||
**Priority**: MEDIUM (Elevated to HIGH - implemented)
|
||||
**ADR**: ADR-034
|
||||
**Actual Effort**: ~7 hours (including complete UI)
|
||||
**Status**: COMPLETE
|
||||
**Implementation**: SQLite FTS5 with full UI and API
|
||||
|
||||
#### Implementation Approach
|
||||
- Use SQLite FTS5 extension
|
||||
- Create shadow FTS table for note content
|
||||
- Update on note create/update/delete
|
||||
- Add search_notes() function to notes.py
|
||||
|
||||
---
|
||||
|
||||
### 4. Migration System Testing Suite
|
||||
|
||||
**Priority**: MEDIUM
|
||||
**Estimated Effort**: 4-5 hours
|
||||
**Dependencies**: Item #1 (Migration redesign)
|
||||
**Risk**: Low
|
||||
|
||||
#### Test Coverage Needed
|
||||
- Migration ordering tests
|
||||
- Rollback simulation tests
|
||||
- Schema evolution tests
|
||||
- Performance benchmarks
|
||||
- CI/CD integration
|
||||
|
||||
---
|
||||
|
||||
## Implementation Order
|
||||
|
||||
1. **First**: Complete Database Migration System Redesign (Critical)
|
||||
2. **Second**: Add comprehensive migration tests
|
||||
3. **Third**: IndieAuth improvements (if needed)
|
||||
4. **Fourth**: Full-text search (if time permits)
|
||||
|
||||
## Release Checklist
|
||||
|
||||
Before releasing v1.1.0:
|
||||
|
||||
- [ ] All CRITICAL items complete
|
||||
- [ ] All tests passing
|
||||
- [ ] Documentation updated
|
||||
- [ ] CHANGELOG.md updated with all changes
|
||||
- [ ] Version bumped to 1.1.0
|
||||
- [ ] Migration guide written for production systems
|
||||
- [ ] Release notes prepared
|
||||
- [ ] Docker image tested with migrations
|
||||
|
||||
## Risk Mitigation
|
||||
|
||||
### Migration System Risks
|
||||
- **Risk**: Breaking existing databases
|
||||
- **Mitigation**: Comprehensive testing, backward compatibility, clear rollback procedures
|
||||
|
||||
### Performance Risks
|
||||
- **Risk**: Slow fresh installations (running all migrations)
|
||||
- **Mitigation**: Migration performance testing, potential migration squashing in future
|
||||
|
||||
### Deployment Risks
|
||||
- **Risk**: Production upgrade failures
|
||||
- **Mitigation**: Detailed upgrade guide, test on staging first, backup procedures
|
||||
|
||||
## Notes for Implementation
|
||||
|
||||
### For the Developer Implementing Item #1
|
||||
|
||||
1. **Start with ADR-032** for complete design details
|
||||
2. **Check git history** for original schema (commit a68fd57)
|
||||
3. **Test thoroughly** - this is critical infrastructure
|
||||
4. **Consider edge cases**:
|
||||
- Empty database
|
||||
- Partially migrated database
|
||||
- Corrupted migration tracking
|
||||
- Missing migration files
|
||||
|
||||
### Key Files to Modify
|
||||
|
||||
1. `/home/phil/Projects/starpunk/starpunk/database.py`
|
||||
- Add INITIAL_SCHEMA_SQL constant
|
||||
- Modify init_db() function
|
||||
- Add helper functions
|
||||
|
||||
2. `/home/phil/Projects/starpunk/tests/test_migrations.py`
|
||||
- Add new test cases for initial schema
|
||||
- Test upgrade paths
|
||||
|
||||
3. `/home/phil/Projects/starpunk/docs/architecture/database.md`
|
||||
- Document schema evolution strategy
|
||||
- Explain dual schema constants
|
||||
|
||||
## Success Metrics
|
||||
|
||||
- Zero database upgrade failures in production
|
||||
- Fresh installation time < 1 second
|
||||
- All tests passing
|
||||
- Clear documentation for future maintainers
|
||||
- Positive user feedback on stability
|
||||
|
||||
## References
|
||||
|
||||
- [ADR-031: Database Migration System Redesign](/home/phil/Projects/starpunk/docs/decisions/ADR-031-database-migration-system-redesign.md)
|
||||
- [ADR-032: Initial Schema SQL Implementation](/home/phil/Projects/starpunk/docs/decisions/ADR-032-initial-schema-sql-implementation.md)
|
||||
- [v1.1 Potential Features](/home/phil/Projects/starpunk/docs/projectplan/v1.1/potential-features.md)
|
||||
- [Migration Implementation Reports](/home/phil/Projects/starpunk/docs/reports/)
|
||||
|
||||
---
|
||||
|
||||
*Last Updated: 2025-11-24*
|
||||
*Version: 1.0.0-rc.2 → 1.1.0 (planned)*
|
||||
@@ -1,198 +0,0 @@
|
||||
# Syndication Features Specification
|
||||
|
||||
## Overview
|
||||
This document tracks the implementation of expanded syndication format support for StarPunk CMS, targeting v1.1.2 and v1.2.0 releases.
|
||||
|
||||
## Feature Set
|
||||
|
||||
### 1. ATOM Feed Support (v1.1.2)
|
||||
**Status**: Planned
|
||||
**Effort**: 2-4 hours
|
||||
**Priority**: High
|
||||
|
||||
#### Requirements
|
||||
- RFC 4287 compliance
|
||||
- Available at `/feed.atom` endpoint
|
||||
- Include all published notes
|
||||
- Support same filtering as RSS feed
|
||||
- Proper content encoding
|
||||
|
||||
#### Technical Approach
|
||||
- Leverage feedgen library's built-in ATOM support
|
||||
- Minimal code changes from RSS implementation
|
||||
- Share note iteration logic with RSS feed
|
||||
|
||||
#### Acceptance Criteria
|
||||
- [ ] Valid ATOM 1.0 feed generated
|
||||
- [ ] Passes W3C Feed Validator
|
||||
- [ ] Contains all RSS feed content
|
||||
- [ ] Auto-discovery link in HTML head
|
||||
- [ ] Content properly escaped/encoded
|
||||
- [ ] Unit tests with 100% coverage
|
||||
|
||||
### 2. JSON Feed Support (v1.1.2)
|
||||
**Status**: Planned
|
||||
**Effort**: 4-6 hours
|
||||
**Priority**: Medium
|
||||
|
||||
#### Requirements
|
||||
- JSON Feed v1.1 specification compliance
|
||||
- Available at `/feed.json` endpoint
|
||||
- Native JSON serialization
|
||||
- Support attachments for future media
|
||||
|
||||
#### Technical Approach
|
||||
- Direct serialization from Note model
|
||||
- No XML parsing/generation
|
||||
- Clean JSON structure
|
||||
- Optional fields for extensibility
|
||||
|
||||
#### JSON Feed Structure
|
||||
```json
|
||||
{
|
||||
"version": "https://jsonfeed.org/version/1.1",
|
||||
"title": "Site Name",
|
||||
"home_page_url": "https://example.com",
|
||||
"feed_url": "https://example.com/feed.json",
|
||||
"description": "Site description",
|
||||
"items": [
|
||||
{
|
||||
"id": "unique-id",
|
||||
"url": "https://example.com/note/slug",
|
||||
"content_html": "<p>HTML content</p>",
|
||||
"date_published": "2025-11-25T10:00:00Z",
|
||||
"date_modified": "2025-11-25T10:00:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Acceptance Criteria
|
||||
- [ ] Valid JSON Feed v1.1 output
|
||||
- [ ] Passes JSON Feed Validator
|
||||
- [ ] Proper HTML encoding in content_html
|
||||
- [ ] ISO 8601 date formatting
|
||||
- [ ] Auto-discovery link in HTML head
|
||||
- [ ] Unit tests with full coverage
|
||||
|
||||
### 3. Strict Microformats2 Support (v1.2.0)
|
||||
**Status**: Planned
|
||||
**Effort**: 10-16 hours
|
||||
**Priority**: High (IndieWeb core requirement)
|
||||
|
||||
#### Requirements
|
||||
- Complete h-entry markup
|
||||
- Author h-card implementation
|
||||
- h-feed on index pages
|
||||
- Backward compatible with existing CSS
|
||||
|
||||
#### Implementation Scope
|
||||
|
||||
##### h-entry (Enhanced)
|
||||
Current state:
|
||||
- ✅ h-entry class
|
||||
- ✅ e-content
|
||||
- ✅ dt-published
|
||||
- ✅ u-url
|
||||
|
||||
To add:
|
||||
- [ ] p-name (extracted title)
|
||||
- [ ] p-summary (excerpt generation)
|
||||
- [ ] p-author (embedded h-card)
|
||||
- [ ] p-category (when tags implemented)
|
||||
- [ ] u-uid (unique identifier)
|
||||
|
||||
##### h-card (New)
|
||||
- [ ] p-name (author name from config)
|
||||
- [ ] u-url (author URL from config)
|
||||
- [ ] u-photo (optional avatar)
|
||||
- [ ] p-note (optional bio)
|
||||
|
||||
##### h-feed (New)
|
||||
- [ ] h-feed wrapper on index
|
||||
- [ ] p-name (site title)
|
||||
- [ ] p-author (site-level h-card)
|
||||
- [ ] Nested h-entry items
|
||||
|
||||
#### Template Changes Required
|
||||
1. `base.html` - Add author h-card in header/footer
|
||||
2. `index.html` - Wrap notes in h-feed
|
||||
3. `note.html` - Complete h-entry properties
|
||||
4. New partial: `note_summary.html` for consistent markup
|
||||
|
||||
#### Acceptance Criteria
|
||||
- [ ] Passes microformats2 validator
|
||||
- [ ] Parseable by IndieWeb tools
|
||||
- [ ] XRay parser compatibility
|
||||
- [ ] CSS remains functional
|
||||
- [ ] No visual regression
|
||||
- [ ] Documentation of all mf2 classes used
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Feed Validation
|
||||
1. W3C Feed Validator for ATOM
|
||||
2. JSON Feed Validator for JSON
|
||||
3. Microformats2 parser for HTML
|
||||
|
||||
### Automated Tests
|
||||
- Unit tests for feed generation
|
||||
- Integration tests for endpoints
|
||||
- Validation tests using external validators
|
||||
- Regression tests for existing RSS
|
||||
|
||||
### Manual Testing
|
||||
- Multiple feed readers compatibility
|
||||
- IndieWeb tools parsing
|
||||
- Social readers integration
|
||||
|
||||
## Dependencies
|
||||
|
||||
### External Libraries
|
||||
- feedgen (existing) - ATOM support included
|
||||
- No new dependencies for JSON Feed
|
||||
- No new dependencies for microformats2
|
||||
|
||||
### Configuration
|
||||
- New config options for author info (h-card)
|
||||
- Feed URLs in auto-discovery links
|
||||
|
||||
## Migration Impact
|
||||
- None - all features are additive
|
||||
- Existing RSS feed unchanged
|
||||
- No database changes required
|
||||
|
||||
## Documentation Requirements
|
||||
1. Update user guide with feed URLs
|
||||
2. Document microformats2 markup
|
||||
3. Add feed discovery information
|
||||
4. Include validation instructions
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
### Low Risk
|
||||
- ATOM feed (uses existing library)
|
||||
- JSON Feed (simple serialization)
|
||||
|
||||
### Medium Risk
|
||||
- Microformats2 (template complexity)
|
||||
- CSS selector conflicts
|
||||
|
||||
### Mitigation
|
||||
- Incremental template changes
|
||||
- Thorough CSS testing
|
||||
- Use mf2 validators throughout
|
||||
|
||||
## Success Metrics
|
||||
- All feeds validate successfully
|
||||
- No performance degradation
|
||||
- Feed readers consume without errors
|
||||
- IndieWeb tools parse correctly
|
||||
- Zero visual regression in UI
|
||||
|
||||
## References
|
||||
- [RFC 4287 - ATOM](https://www.rfc-editor.org/rfc/rfc4287)
|
||||
- [JSON Feed v1.1](https://www.jsonfeed.org/version/1.1/)
|
||||
- [Microformats2](https://microformats.org/wiki/microformats2)
|
||||
- [IndieWeb h-entry](https://indieweb.org/h-entry)
|
||||
- [IndieWeb h-card](https://indieweb.org/h-card)
|
||||
@@ -1,222 +0,0 @@
|
||||
# StarPunk v1.X.X IndieWeb-Focused Release Options
|
||||
|
||||
*Created: 2025-11-28*
|
||||
*Status: Options for architect review*
|
||||
|
||||
Based on analysis of current implementation gaps and IndieWeb specifications, here are three genuinely different paths forward for full IndieWeb protocol support.
|
||||
|
||||
---
|
||||
|
||||
## Option A: v1.2.0 "Conversation" - Webmention & Reply Context
|
||||
|
||||
**Focus:** Enable two-way conversations between IndieWeb sites
|
||||
|
||||
**What's Missing Now:**
|
||||
- Zero Webmention support (no sending, no receiving)
|
||||
- No reply context display (when replying to others)
|
||||
- No backlinks/responses display
|
||||
- No notification system for mentions
|
||||
|
||||
**What You'll Get:**
|
||||
- **Webmention Sending** (W3C Webmention spec)
|
||||
- Automatic endpoint discovery via HTTP headers/HTML links
|
||||
- Send notifications when mentioning/replying to other sites
|
||||
- Queue system for reliable delivery with retries
|
||||
- **Webmention Receiving** (W3C Webmention spec)
|
||||
- Advertise endpoint in HTML and HTTP headers
|
||||
- Verify source mentions target
|
||||
- Store and display incoming mentions (likes, replies, reposts)
|
||||
- **Reply Context** (IndieWeb reply-context spec)
|
||||
- Fetch and display content you're replying to
|
||||
- Parse microformats2 from source
|
||||
- Cache reply contexts locally
|
||||
- **Response Display** (facepile pattern)
|
||||
- Show likes/reposts as compact avatars
|
||||
- Display full replies with author info
|
||||
- Separate responses by type
|
||||
|
||||
**IndieWeb Specs:**
|
||||
- W3C Webmention: https://www.w3.org/TR/webmention/
|
||||
- Reply-context: https://indieweb.org/reply-context
|
||||
- Response display: https://indieweb.org/responses
|
||||
- Facepile: https://indieweb.org/facepile
|
||||
|
||||
**Completion Criteria:**
|
||||
- Pass webmention.rocks test suite (21 tests)
|
||||
- Successfully send/receive with 3+ IndieWeb sites
|
||||
- Display reply contexts with proper h-cite markup
|
||||
- Show incoming responses grouped by type
|
||||
|
||||
**User Value:**
|
||||
Transform StarPunk from broadcast-only to conversational. Users can reply to other IndieWeb posts and see who's engaging with their content. Creates a decentralized comment system.
|
||||
|
||||
**Scope:** 8-10 weeks
|
||||
|
||||
---
|
||||
|
||||
## Option B: v1.3.0 "Studio" - Complete Micropub Media & Post Types
|
||||
|
||||
**Focus:** Full Micropub spec compliance with rich media and diverse post types
|
||||
|
||||
**What's Missing Now:**
|
||||
- No media endpoint (can't upload images/audio/video)
|
||||
- No update/delete via Micropub (create-only)
|
||||
- No syndication targets
|
||||
- Only supports notes (no articles, photos, bookmarks, etc.)
|
||||
- No query support beyond basic config
|
||||
|
||||
**What You'll Get:**
|
||||
- **Micropub Media Endpoint** (W3C Micropub spec section 3.7)
|
||||
- Accept multipart uploads for images/audio/video
|
||||
- Generate URLs for uploaded media
|
||||
- Return media URL to client for embedding
|
||||
- Basic image resizing/optimization
|
||||
- **Micropub Updates/Deletes** (W3C Micropub spec sections 3.3-3.4)
|
||||
- Replace/add/delete specific properties
|
||||
- Full post deletion support
|
||||
- JSON syntax for complex updates
|
||||
- **Post Type Discovery** (IndieWeb post-type-discovery)
|
||||
- Articles (with titles)
|
||||
- Photos (image-centric posts)
|
||||
- Bookmarks (link saving)
|
||||
- Likes (marking favorites)
|
||||
- Reposts (sharing others' content)
|
||||
- Audio/Video posts
|
||||
- **Syndication Targets** (Micropub syndicate-to)
|
||||
- Configure external targets (Mastodon, Twitter bridges)
|
||||
- POSSE implementation
|
||||
- Return syndication URLs
|
||||
|
||||
**IndieWeb Specs:**
|
||||
- W3C Micropub (complete): https://www.w3.org/TR/micropub/
|
||||
- Post Type Discovery: https://indieweb.org/post-type-discovery
|
||||
- POSSE: https://indieweb.org/POSSE
|
||||
|
||||
**Completion Criteria:**
|
||||
- Pass micropub.rocks full test suite (not just create)
|
||||
- Support all major post types with proper templates
|
||||
- Successfully syndicate to 2+ external services
|
||||
- Handle media uploads from mobile apps
|
||||
|
||||
**User Value:**
|
||||
Use any Micropub client (Indigenous, Quill, etc.) with full features. Post photos from your phone, save bookmarks, like posts, all through standard clients. Syndicate to social media automatically.
|
||||
|
||||
**Scope:** 10-12 weeks
|
||||
|
||||
---
|
||||
|
||||
## Option C: v1.4.0 "Identity" - Complete Microformats2 & IndieAuth Provider
|
||||
|
||||
**Focus:** Become a full IndieWeb identity provider and improve content markup
|
||||
|
||||
**What's Missing Now:**
|
||||
- Minimal h-entry markup (missing author, location, syndication)
|
||||
- No h-card on pages (no author identity)
|
||||
- No h-feed markup enhancements
|
||||
- No rel=me verification
|
||||
- Using external IndieAuth (not self-hosted)
|
||||
- No authorization endpoint
|
||||
- No token endpoint
|
||||
|
||||
**What You'll Get:**
|
||||
- **Complete h-entry Microformats2** (microformats2 spec)
|
||||
- Author h-card embedded in each post
|
||||
- Location (p-location with h-geo/h-adr)
|
||||
- Syndication links (u-syndication)
|
||||
- In-reply-to markup (u-in-reply-to)
|
||||
- Categories/tags (p-category)
|
||||
- **Author h-card** (microformats2 h-card)
|
||||
- Full profile page with h-card
|
||||
- Representative h-card on homepage
|
||||
- Contact info, bio, social links
|
||||
- rel=me links for verification
|
||||
- **Enhanced h-feed** (microformats2 h-feed)
|
||||
- Feed name and author
|
||||
- Pagination with rel=prev/next
|
||||
- Feed photo/summary
|
||||
- **IndieAuth Provider** (IndieAuth spec)
|
||||
- Authorization endpoint (login to other sites with your domain)
|
||||
- Token endpoint (issue access tokens)
|
||||
- Client registration support
|
||||
- Scope management
|
||||
- Token revocation interface
|
||||
|
||||
**IndieWeb Specs:**
|
||||
- Microformats2: http://microformats.org/wiki/microformats2
|
||||
- h-card: http://microformats.org/wiki/h-card
|
||||
- h-entry: http://microformats.org/wiki/h-entry
|
||||
- IndieAuth: https://indieauth.spec.indieweb.org/
|
||||
- rel=me: https://indieweb.org/rel-me
|
||||
|
||||
**Completion Criteria:**
|
||||
- Pass IndieWebify.me full validation
|
||||
- Successfully authenticate to 5+ IndieWeb services
|
||||
- Parse correctly in all major microformats2 parsers
|
||||
- Provide IndieAuth to other sites (eat your own dogfood)
|
||||
|
||||
**User Value:**
|
||||
Your site becomes your identity across the web. Log into any IndieWeb service with your domain. Rich markup makes your content parse perfectly everywhere. No dependency on external auth services.
|
||||
|
||||
**Scope:** 6-8 weeks
|
||||
|
||||
---
|
||||
|
||||
## Recommendation Rationale
|
||||
|
||||
Each option represents a fundamentally different IndieWeb capability:
|
||||
|
||||
- **Option A (Conversation)**: Makes StarPunk social and interactive
|
||||
- **Option B (Studio)**: Makes StarPunk a complete publishing platform
|
||||
- **Option C (Identity)**: Makes StarPunk an identity provider
|
||||
|
||||
All three are essential for "full IndieWeb support" but focus on different protocols:
|
||||
|
||||
- A focuses on **Webmention** (W3C Recommendation)
|
||||
- B focuses on **Micropub** completion (W3C Recommendation)
|
||||
- C focuses on **Microformats2** & **IndieAuth** (IndieWeb specs)
|
||||
|
||||
## Current Implementation Gaps Summary
|
||||
|
||||
Based on code analysis:
|
||||
|
||||
### Micropub (`starpunk/micropub.py`)
|
||||
✅ Create notes (basic)
|
||||
✅ Query config
|
||||
✅ Query source
|
||||
❌ Media endpoint
|
||||
❌ Updates (replace/add/delete)
|
||||
❌ Deletes
|
||||
❌ Syndication targets
|
||||
❌ Query for syndicate-to
|
||||
|
||||
### Microformats (templates)
|
||||
✅ Basic h-entry (content, published date, URL)
|
||||
✅ Basic h-feed wrapper
|
||||
❌ Author h-card
|
||||
❌ Complete h-entry properties
|
||||
❌ rel=me links
|
||||
❌ h-feed metadata
|
||||
|
||||
### Webmention
|
||||
❌ No implementation at all
|
||||
|
||||
### IndieAuth
|
||||
✅ Client (using indielogin.com)
|
||||
❌ No provider capability
|
||||
|
||||
### Post Types
|
||||
✅ Notes
|
||||
❌ Articles, photos, bookmarks, likes, reposts, etc.
|
||||
|
||||
---
|
||||
|
||||
## Decision Factors
|
||||
|
||||
Consider these when choosing:
|
||||
|
||||
1. **User Demand**: What are users asking for most?
|
||||
2. **Ecosystem Value**: Which adds most value to IndieWeb network?
|
||||
3. **Technical Dependencies**: Option C (Identity) might benefit A & B
|
||||
4. **Market Differentiation**: Which makes StarPunk unique?
|
||||
|
||||
All three options are genuinely different approaches to "full IndieWeb support" - the choice depends on priorities.
|
||||
@@ -1,155 +0,0 @@
|
||||
# StarPunk Next Release Options
|
||||
|
||||
After v1.1.2 "Syndicate" (Metrics + Multi-Format Feeds + Statistics Dashboard)
|
||||
|
||||
## Option A: v1.2.0 "Discover" - Discoverability & SEO Enhancement
|
||||
|
||||
**Focus:** Make your content findable by search engines and discoverable by IndieWeb tools, improving organic reach and community integration.
|
||||
|
||||
**User Benefit:** Your notes become easier to find through Google, properly parsed by IndieWeb tools, and better integrated with the broader web ecosystem. Solves the "I'm publishing but nobody can find me" problem.
|
||||
|
||||
**Key Features:**
|
||||
- **Microformats2 Enhancement** - Full h-entry, h-card, h-feed validation and enrichment with author info, categories, and reply contexts
|
||||
- **Structured Data Implementation** - Schema.org JSON-LD for articles, breadcrumbs, and person markup for rich snippets
|
||||
- **XML Sitemap Generation** - Dynamic sitemap.xml with lastmod dates, priority scores, and change frequencies
|
||||
- **OpenGraph & Twitter Cards** - Social media preview optimization with proper meta tags and image handling
|
||||
- **Webmention Discovery** - Add webmention endpoint discovery links (preparation for future receiving)
|
||||
- **Archive Pages** - Year/month archive pages with proper pagination and navigation
|
||||
- **Category/Tag System** - Simple tagging with category pages and tag clouds (backward compatible with existing notes)
|
||||
|
||||
**Technical Highlights:**
|
||||
- Microformats2 spec compliance validation with indiewebify.me
|
||||
- JSON-LD structured data for Google Rich Results
|
||||
- Sitemap protocol compliance with optional ping to search engines
|
||||
- Minimal implementation - tags stored in note metadata, no new tables
|
||||
- Progressive enhancement - existing notes work unchanged
|
||||
|
||||
**Scope:** Medium
|
||||
|
||||
**Dependencies:**
|
||||
- Existing RSS/ATOM/JSON Feed infrastructure for sitemap generation
|
||||
- Current URL routing for archive pages
|
||||
- Metrics instrumentation helps track search traffic
|
||||
|
||||
**Strategic Value:** Essential for growth - if people can't find your content, the best CMS is worthless. This positions StarPunk as SEO-friendly out of the box, competing with static site generators while maintaining IndieWeb principles.
|
||||
|
||||
---
|
||||
|
||||
## Option B: v1.2.0 "Control" - Publishing Workflow & Content Management
|
||||
|
||||
**Focus:** Professional publishing workflows with scheduling, drafts management, and bulk operations - treating your notes as a serious publishing platform.
|
||||
|
||||
**User Benefit:** Write when inspired, publish when strategic. Queue up content for consistent publishing, manage drafts effectively, and perform bulk operations efficiently. Solves the "I want to write now but publish later" problem.
|
||||
|
||||
**Key Features:**
|
||||
- **Scheduled Publishing** - Set future publish dates/times with automatic publishing via background worker
|
||||
- **Draft Versioning** - Save multiple draft versions with comparison view and restore capability
|
||||
- **Bulk Operations** - Select multiple notes for publish/unpublish/delete with confirmation
|
||||
- **Publishing Calendar** - Visual calendar showing scheduled posts, published posts, and gaps
|
||||
- **Auto-Save Drafts** - JavaScript-based auto-save every 30 seconds while editing
|
||||
- **Note Templates** - Create reusable templates for common post types (weekly update, link post, etc.)
|
||||
- **Quick Notes** - Minimal UI for rapid note creation (just a text box, like Twitter)
|
||||
- **Markdown Shortcuts** - Toolbar with common formatting buttons and keyboard shortcuts
|
||||
|
||||
**Technical Highlights:**
|
||||
- Background task runner (simple Python threading, no Celery needed)
|
||||
- Draft versions stored as JSON in a single column (no complex versioning tables)
|
||||
- Calendar view using existing metrics dashboard infrastructure
|
||||
- LocalStorage for auto-save (works offline)
|
||||
- Template system uses simple markdown files in data/templates/
|
||||
|
||||
**Scope:** Large
|
||||
|
||||
**Dependencies:**
|
||||
- Existing admin interface for UI components
|
||||
- Current note creation flow for templates
|
||||
- Metrics system helps track publishing patterns
|
||||
|
||||
**Strategic Value:** Transforms StarPunk from a simple notes publisher to a professional content management system. Appeals to serious bloggers and content creators who need workflow features but want IndieWeb simplicity.
|
||||
|
||||
---
|
||||
|
||||
## Option C: v1.1.3 "Shield" - Security Hardening & Privacy Controls
|
||||
|
||||
**Focus:** Enterprise-grade security hardening and privacy features, making StarPunk suitable for security-conscious users and sensitive content.
|
||||
|
||||
**User Benefit:** Peace of mind knowing your content is protected with multiple layers of security, comprehensive audit trails, and privacy controls. Solves the "I need to know my site is secure" problem.
|
||||
|
||||
**Key Features:**
|
||||
- **Two-Factor Authentication (2FA)** - TOTP support via authenticator apps with backup codes
|
||||
- **Comprehensive Audit Logging** - Track all actions: login attempts, note changes, settings modifications with who/what/when/where
|
||||
- **Rate Limiting** - Application-level rate limiting for auth endpoints, API calls, and feed access
|
||||
- **Content Security Policy (CSP) Level 2** - Strict CSP with nonces, report-uri, and upgrade-insecure-requests
|
||||
- **Session Security Hardening** - Fingerprinting, concurrent session limits, geographic anomaly detection
|
||||
- **Private Notes** - Password-protected notes with separate authentication (not in feeds)
|
||||
- **Automated Security Headers** - HSTS preload, X-Frame-Options, X-Content-Type-Options, Referrer-Policy
|
||||
- **Failed Login Tracking** - Lock accounts after N failed attempts with email notification
|
||||
|
||||
**Technical Highlights:**
|
||||
- PyOTP library for TOTP implementation (minimal dependency)
|
||||
- Audit logs in separate SQLite database for performance isolation
|
||||
- Rate limiting using in-memory token bucket algorithm
|
||||
- CSP nonce generation per request for inline scripts
|
||||
- GeoIP lite for geographic anomaly detection
|
||||
- bcrypt for private note passwords
|
||||
|
||||
**Scope:** Medium
|
||||
|
||||
**Dependencies:**
|
||||
- Existing auth system for 2FA integration
|
||||
- Current session management for hardening
|
||||
- Metrics buffer pattern reused for rate limiting
|
||||
|
||||
**Strategic Value:** Positions StarPunk as the security-first IndieWeb CMS. Critical differentiator for users who prioritize security and privacy. Many IndieWeb tools lack proper security features - this would make StarPunk stand out.
|
||||
|
||||
---
|
||||
|
||||
## Decision Matrix
|
||||
|
||||
| Aspect | Option A: "Discover" | Option B: "Control" | Option C: "Shield" |
|
||||
|--------|---------------------|--------------------|--------------------|
|
||||
| **User Appeal** | Bloggers wanting traffic | Power users, professionals | Security-conscious users |
|
||||
| **Complexity** | Medium - mostly templates | High - new UI patterns | Medium - mostly backend |
|
||||
| **Dependencies** | Few - builds on feeds | Some - needs background tasks | Minimal - largely independent |
|
||||
| **IndieWeb Value** | High - improves ecosystem | Medium - individual benefit | Low - not IndieWeb specific |
|
||||
| **Market Differentiation** | Medium - expected feature | High - rare in minimal CMSs | Very High - unique position |
|
||||
| **Implementation Risk** | Low - well understood | Medium - UI complexity | Low - standard patterns |
|
||||
| **Performance Impact** | Minimal | Medium (background tasks) | Minimal |
|
||||
| **Maintenance Burden** | Low | High (more features) | Medium (security updates) |
|
||||
|
||||
## Architectural Recommendations
|
||||
|
||||
### If Choosing Option A: "Discover"
|
||||
- Implement microformats2 validation as a separate module
|
||||
- Use template inheritance to minimize code duplication
|
||||
- Cache generated sitemaps using existing feed cache pattern
|
||||
- Consider making categories a simple JSON field initially
|
||||
|
||||
### If Choosing Option B: "Control"
|
||||
- Start with simple cron-like scheduler, not full job queue
|
||||
- Use existing MetricsBuffer pattern for background task tracking
|
||||
- Implement templates as markdown files with frontmatter
|
||||
- Consider feature flags to ship incrementally
|
||||
|
||||
### If Choosing Option C: "Shield"
|
||||
- Audit log must be in separate database for performance
|
||||
- Rate limiting should use existing metrics infrastructure
|
||||
- 2FA should be optional and backward compatible
|
||||
- Consider security.txt file for disclosure
|
||||
|
||||
## Recommendation
|
||||
|
||||
**Architect's Choice: Option A "Discover"**
|
||||
|
||||
Rationale:
|
||||
1. **Natural progression** - After feeds (syndication), discovery is the logical next step
|
||||
2. **Broad appeal** - Every user benefits from better SEO and discoverability
|
||||
3. **Standards-focused** - Aligns with StarPunk's commitment to web standards
|
||||
4. **Low risk** - Well-understood requirements with clear success metrics
|
||||
5. **Foundation for growth** - Enables future features like webmentions, reply contexts
|
||||
|
||||
Option B is compelling but introduces significant complexity that conflicts with StarPunk's minimalist philosophy. Option C, while valuable, serves a narrower audience and doesn't advance core IndieWeb goals.
|
||||
|
||||
---
|
||||
|
||||
*Generated: 2025-11-28*
|
||||
@@ -1,309 +0,0 @@
|
||||
# StarPunk V1 Project Plan
|
||||
|
||||
## Overview
|
||||
|
||||
This directory contains comprehensive planning documentation for StarPunk V1 implementation. These documents guide development from the current state (basic infrastructure) to a fully functional IndieWeb CMS.
|
||||
|
||||
## Planning Documents
|
||||
|
||||
### 1. [Implementation Plan](implementation-plan.md) (PRIMARY DOCUMENT)
|
||||
**Use this for**: Detailed, step-by-step implementation guidance
|
||||
|
||||
The comprehensive implementation roadmap organized into 10 phases:
|
||||
- **Phase 1-2**: Foundation (utilities, models, notes management)
|
||||
- **Phase 3-4**: Authentication and web interface
|
||||
- **Phase 5-6**: RSS feeds and Micropub
|
||||
- **Phase 7**: Optional REST API
|
||||
- **Phase 8**: Testing and quality assurance
|
||||
- **Phase 9**: Documentation
|
||||
- **Phase 10**: Release preparation
|
||||
|
||||
Each phase includes:
|
||||
- Specific tasks with checkboxes
|
||||
- Dependencies clearly marked
|
||||
- Estimated effort in hours
|
||||
- References to relevant ADRs and docs
|
||||
- Acceptance criteria for each feature
|
||||
- Testing requirements
|
||||
|
||||
**Start here** for implementation work.
|
||||
|
||||
---
|
||||
|
||||
### 2. [Quick Reference](quick-reference.md)
|
||||
**Use this for**: Fast lookups during development
|
||||
|
||||
A condensed reference guide containing:
|
||||
- **Implementation order** (strict dependency chain)
|
||||
- **Module dependency diagram**
|
||||
- **Critical path items** (what MUST be done)
|
||||
- **Complete file checklist** (35 files to create)
|
||||
- **Test coverage requirements**
|
||||
- **Configuration checklist** (required .env variables)
|
||||
- **Common development commands**
|
||||
- **Key design decisions** (quick ADR lookup)
|
||||
- **Success criteria** (how to know V1 is done)
|
||||
- **Troubleshooting** (common issues and fixes)
|
||||
|
||||
**Use this** when you need a quick answer without reading the full plan.
|
||||
|
||||
---
|
||||
|
||||
### 3. [Feature Scope](feature-scope.md)
|
||||
**Use this for**: Scope decisions and feature prioritization
|
||||
|
||||
Definitive document on what's in/out of scope for V1:
|
||||
- **IN SCOPE**: Complete feature matrix with justifications
|
||||
- Authentication & Authorization
|
||||
- Notes Management
|
||||
- Web Interface (Public & Admin)
|
||||
- Micropub Support
|
||||
- RSS Feed
|
||||
- Data Management
|
||||
- Security
|
||||
- Testing
|
||||
- Documentation
|
||||
|
||||
- **OUT OF SCOPE**: What to defer to V2
|
||||
- Multi-user support
|
||||
- Tags and categories
|
||||
- Media uploads
|
||||
- Webmentions
|
||||
- Advanced features
|
||||
- (50+ features explicitly deferred)
|
||||
|
||||
- **Feature Justification Framework**: How to evaluate new feature requests
|
||||
|
||||
- **Lines of Code Budget**: Maximum complexity targets per module
|
||||
|
||||
**Use this** when someone asks "Should we add feature X?" or when tempted to add "just one more thing."
|
||||
|
||||
---
|
||||
|
||||
## How to Use These Documents
|
||||
|
||||
### For Initial Planning
|
||||
1. Read **Implementation Plan** completely
|
||||
2. Review **Feature Scope** to understand boundaries
|
||||
3. Bookmark **Quick Reference** for daily use
|
||||
|
||||
### During Development
|
||||
1. Follow **Implementation Plan** phase by phase
|
||||
2. Check off tasks as completed
|
||||
3. Reference **Quick Reference** for commands and lookups
|
||||
4. Consult **Feature Scope** when scope questions arise
|
||||
|
||||
### For Daily Work
|
||||
1. **Quick Reference** is your daily companion
|
||||
2. **Implementation Plan** for detailed task guidance
|
||||
3. **Feature Scope** for scope decisions
|
||||
|
||||
---
|
||||
|
||||
## Current Project State
|
||||
|
||||
### Completed (Setup Phase)
|
||||
- ✓ Project structure created
|
||||
- ✓ Virtual environment with uv
|
||||
- ✓ Dependencies installed (6 core packages)
|
||||
- ✓ Database schema defined and initialized
|
||||
- ✓ Configuration management (config.py)
|
||||
- ✓ Basic Flask app structure
|
||||
- ✓ Documentation framework (ADRs, architecture)
|
||||
- ✓ Git repository initialized
|
||||
|
||||
### Ready to Implement
|
||||
- [ ] Phase 1: Core utilities and models
|
||||
- [ ] Phase 2: Notes management (CRUD)
|
||||
- [ ] Phase 3: Authentication (IndieLogin)
|
||||
- [ ] Phase 4: Web interface (templates + routes)
|
||||
- [ ] Phase 5: RSS feed generation
|
||||
- [ ] Phase 6: Micropub endpoint
|
||||
- [ ] Phase 7: Optional REST API
|
||||
- [ ] Phase 8: Testing and QA
|
||||
- [ ] Phase 9: Documentation
|
||||
- [ ] Phase 10: Release
|
||||
|
||||
---
|
||||
|
||||
## Key Metrics
|
||||
|
||||
### Estimated Effort
|
||||
- **Total**: 40-60 hours of focused development
|
||||
- **Timeline**: 3-4 weeks at 15-20 hours/week
|
||||
- **Files to Create**: ~35 files (code + tests + docs)
|
||||
- **Lines of Code**: ~2,500-3,700 total (app + tests)
|
||||
|
||||
### Success Criteria
|
||||
- [ ] All features in scope implemented
|
||||
- [ ] Test coverage >80%
|
||||
- [ ] All validators pass (HTML, RSS, Microformats, Micropub)
|
||||
- [ ] Documentation complete
|
||||
- [ ] Deployable to production
|
||||
- [ ] Performance targets met (<300ms responses)
|
||||
|
||||
---
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Recommended Approach
|
||||
1. **Work in phases** - Complete Phase 1 before Phase 2
|
||||
2. **Test as you go** - Write tests alongside features
|
||||
3. **Document continuously** - Update docs as you implement
|
||||
4. **Commit frequently** - Small, focused commits
|
||||
5. **Run validators** - Check standards compliance early and often
|
||||
|
||||
### Phase Completion Checklist
|
||||
Before moving to next phase, ensure:
|
||||
- [ ] All tasks in current phase completed
|
||||
- [ ] All tests for phase passing
|
||||
- [ ] Code formatted (black) and linted (flake8)
|
||||
- [ ] Documentation updated
|
||||
- [ ] Changes committed to git
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Prerequisites
|
||||
- Python 3.11+
|
||||
- uv package manager
|
||||
- Git
|
||||
- Text editor
|
||||
- Web browser
|
||||
|
||||
### External Services
|
||||
- IndieLogin.com (for authentication)
|
||||
- W3C validators (for testing)
|
||||
- Micropub.rocks (for testing)
|
||||
- IndieWebify.me (for testing)
|
||||
|
||||
---
|
||||
|
||||
## Standards Compliance
|
||||
|
||||
StarPunk V1 must comply with:
|
||||
|
||||
| Standard | Specification | Validation Tool |
|
||||
|----------|--------------|-----------------|
|
||||
| HTML5 | W3C HTML5 | validator.w3.org |
|
||||
| RSS 2.0 | RSS Board | validator.w3.org/feed |
|
||||
| Microformats2 | microformats.org | indiewebify.me |
|
||||
| Micropub | micropub.spec.indieweb.org | micropub.rocks |
|
||||
| IndieAuth | www.w3.org/TR/indieauth | Manual testing |
|
||||
| OAuth 2.0 | oauth.net/2 | Via IndieLogin |
|
||||
|
||||
All validators must pass before V1 release.
|
||||
|
||||
---
|
||||
|
||||
## Reference Documentation
|
||||
|
||||
### Project Documentation
|
||||
- [Architecture Overview](/home/phil/Projects/starpunk/docs/architecture/overview.md)
|
||||
- [Technology Stack](/home/phil/Projects/starpunk/docs/architecture/technology-stack.md)
|
||||
- [Project Structure](/home/phil/Projects/starpunk/docs/design/project-structure.md)
|
||||
- [Python Coding Standards](/home/phil/Projects/starpunk/docs/standards/python-coding-standards.md)
|
||||
|
||||
### Architecture Decision Records (ADRs)
|
||||
- [ADR-001: Python Web Framework](/home/phil/Projects/starpunk/docs/decisions/ADR-001-python-web-framework.md)
|
||||
- [ADR-002: Flask Extensions](/home/phil/Projects/starpunk/docs/decisions/ADR-002-flask-extensions.md)
|
||||
- [ADR-003: Frontend Technology](/home/phil/Projects/starpunk/docs/decisions/ADR-003-frontend-technology.md)
|
||||
- [ADR-004: File-Based Storage](/home/phil/Projects/starpunk/docs/decisions/ADR-004-file-based-note-storage.md)
|
||||
- [ADR-005: IndieLogin Authentication](/home/phil/Projects/starpunk/docs/decisions/ADR-005-indielogin-authentication.md)
|
||||
- [ADR-006: Python Virtual Environment](/home/phil/Projects/starpunk/docs/decisions/ADR-006-python-virtual-environment-uv.md)
|
||||
|
||||
### External Standards
|
||||
- [Micropub Specification](https://micropub.spec.indieweb.org/)
|
||||
- [IndieAuth Specification](https://www.w3.org/TR/indieauth/)
|
||||
- [Microformats2](http://microformats.org/wiki/microformats2)
|
||||
- [RSS 2.0 Specification](https://www.rssboard.org/rss-specification)
|
||||
- [IndieLogin API](https://indielogin.com/api)
|
||||
|
||||
---
|
||||
|
||||
## Questions and Support
|
||||
|
||||
### Architecture Questions
|
||||
Consult the **Architect Agent** (.claude/agents/architect.md) for:
|
||||
- Technology choices
|
||||
- Design patterns
|
||||
- Architectural decisions
|
||||
- Standards interpretation
|
||||
|
||||
### Implementation Questions
|
||||
Refer to:
|
||||
- **Implementation Plan** for detailed task guidance
|
||||
- **ADRs** for rationale behind decisions
|
||||
- **Architecture docs** for system design
|
||||
- **External specs** for standards details
|
||||
|
||||
### Scope Questions
|
||||
Check:
|
||||
- **Feature Scope** document for in/out of scope decisions
|
||||
- **ADRs** for architectural boundaries
|
||||
- Project philosophy: "When in doubt, leave it out"
|
||||
|
||||
---
|
||||
|
||||
## Updates and Maintenance
|
||||
|
||||
These planning documents are **living documents**:
|
||||
|
||||
### When to Update
|
||||
- After completing each phase (check off tasks)
|
||||
- When discovering new insights during implementation
|
||||
- When making scope decisions (add to Feature Scope)
|
||||
- When architectural changes occur (create new ADR)
|
||||
|
||||
### How to Update
|
||||
1. Update relevant document(s)
|
||||
2. Add "Last Updated" date
|
||||
3. Commit changes with descriptive message
|
||||
4. Ensure consistency across all planning docs
|
||||
|
||||
### Version History
|
||||
- **2025-11-18**: Initial V1 project plan created
|
||||
- Created implementation-plan.md (10 phases, ~35 files)
|
||||
- Created quick-reference.md (daily developer guide)
|
||||
- Created feature-scope.md (in/out of scope)
|
||||
- Created README.md (this file)
|
||||
|
||||
---
|
||||
|
||||
## Getting Started
|
||||
|
||||
**Ready to start implementing?**
|
||||
|
||||
1. **Read** [Implementation Plan](implementation-plan.md) completely
|
||||
2. **Review** [Feature Scope](feature-scope.md) to understand boundaries
|
||||
3. **Bookmark** [Quick Reference](quick-reference.md) for daily use
|
||||
4. **Start with Phase 1** - Core utilities and models
|
||||
5. **Work methodically** through each phase
|
||||
6. **Test continuously** - don't defer testing
|
||||
7. **Document as you go** - update docs with implementation
|
||||
8. **Stay focused** - resist scope creep, defer to V2
|
||||
|
||||
**Good luck building StarPunk V1!**
|
||||
|
||||
Remember: "Every line of code must justify its existence. When in doubt, leave it out."
|
||||
|
||||
---
|
||||
|
||||
## Contact and Feedback
|
||||
|
||||
For questions, issues, or suggestions about these planning documents:
|
||||
|
||||
1. Review the relevant document first
|
||||
2. Check ADRs for architectural decisions
|
||||
3. Consult external specs for standards questions
|
||||
4. Update documents with new insights
|
||||
|
||||
**Project Philosophy**: Simple, focused, standards-compliant. Build the minimal viable IndieWeb CMS. Ship V1. Then iterate.
|
||||
|
||||
---
|
||||
|
||||
**Project Plan Created**: 2025-11-18
|
||||
**Last Updated**: 2025-11-18
|
||||
**Status**: Ready for Implementation
|
||||
**Next Step**: Begin Phase 1 - Core Utilities and Models
|
||||
@@ -1,485 +0,0 @@
|
||||
# StarPunk V1 Dependencies Diagram
|
||||
|
||||
## Module Implementation Order
|
||||
|
||||
This diagram shows the dependency relationships between all StarPunk V1 modules. Modules at the top have no dependencies and must be implemented first. Each level depends on all levels above it.
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ LEVEL 0: Already Complete (Infrastructure) │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ config.py │ │ database.py │ │ __init__.py │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ Loads .env │ │ SQLite DB │ │ create_app │ │
|
||||
│ │ variables │ │ schema │ │ factory │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ LEVEL 1: Foundation (No Dependencies) │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||||
│ │ utils.py │ │
|
||||
│ │ │ │
|
||||
│ │ • generate_slug() • atomic_file_write() │ │
|
||||
│ │ • content_hash() • date_formatting() │ │
|
||||
│ │ • file_path_helpers() • path_validation() │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||||
│ │ templates/ (all 9 files) │ │
|
||||
│ │ │ │
|
||||
│ │ • base.html • admin/base.html │ │
|
||||
│ │ • index.html • admin/login.html │ │
|
||||
│ │ • note.html • admin/dashboard.html │ │
|
||||
│ │ • feed.xml • admin/new.html │ │
|
||||
│ │ • admin/edit.html │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||||
│ │ static/css/style.css │ │
|
||||
│ │ │ │
|
||||
│ │ • ~200 lines of CSS │ │
|
||||
│ │ • Mobile-first responsive design │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ LEVEL 2: Data Models (Depends on Level 1) │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||||
│ │ models.py │ │
|
||||
│ │ │ │
|
||||
│ │ • Note (from_row, to_dict, content, html, permalink) │ │
|
||||
│ │ • Session (from_row, is_expired, is_valid) │ │
|
||||
│ │ • Token (from_row, is_expired, has_scope) │ │
|
||||
│ │ • AuthState (from_row, is_expired) │ │
|
||||
│ │ │ │
|
||||
│ │ Dependencies: utils.py (uses slug generation, etc.) │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ LEVEL 3: Core Features (Depends on Levels 1-2) │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌────────────────────────────┐ ┌────────────────────────────┐│
|
||||
│ │ notes.py │ │ auth.py ││
|
||||
│ │ │ │ ││
|
||||
│ │ • create_note() │ │ • generate_state() ││
|
||||
│ │ • get_note() │ │ • verify_state() ││
|
||||
│ │ • list_notes() │ │ • create_session() ││
|
||||
│ │ • update_note() │ │ • validate_session() ││
|
||||
│ │ • delete_note() │ │ • initiate_login() ││
|
||||
│ │ │ │ • handle_callback() ││
|
||||
│ │ Dependencies: │ │ • require_auth() ││
|
||||
│ │ - utils.py │ │ • logout() ││
|
||||
│ │ - models.py │ │ ││
|
||||
│ │ - database.py │ │ Dependencies: ││
|
||||
│ │ │ │ - models.py ││
|
||||
│ │ │ │ - database.py ││
|
||||
│ │ │ │ - httpx (IndieLogin API) ││
|
||||
│ └────────────────────────────┘ └────────────────────────────┘│
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ LEVEL 4: Web Routes (Depends on Levels 1-3) │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||||
│ │ routes/public.py │ │
|
||||
│ │ │ │
|
||||
│ │ • GET / (homepage, list notes) │ │
|
||||
│ │ • GET /note/<slug> (note permalink) │ │
|
||||
│ │ │ │
|
||||
│ │ Dependencies: notes.py, models.py, templates/ │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||||
│ │ routes/admin.py │ │
|
||||
│ │ │ │
|
||||
│ │ • GET /admin/login (login form) │ │
|
||||
│ │ • POST /admin/login (initiate OAuth) │ │
|
||||
│ │ • GET /auth/callback (OAuth callback) │ │
|
||||
│ │ • GET /admin (dashboard) │ │
|
||||
│ │ • GET /admin/new (create form) │ │
|
||||
│ │ • POST /admin/new (create note) │ │
|
||||
│ │ • GET /admin/edit/<slug>(edit form) │ │
|
||||
│ │ • POST /admin/edit/<slug>(update note) │ │
|
||||
│ │ • POST /admin/delete/<slug>(delete note) │ │
|
||||
│ │ • POST /admin/logout (logout) │ │
|
||||
│ │ │ │
|
||||
│ │ Dependencies: auth.py, notes.py, templates/admin/ │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ LEVEL 5: API Features (Depends on Levels 1-3) │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌────────────────────────────┐ ┌────────────────────────────┐│
|
||||
│ │ feed.py │ │ micropub.py ││
|
||||
│ │ │ │ ││
|
||||
│ │ • generate_rss_feed() │ │ • POST /api/micropub ││
|
||||
│ │ - Query published notes │ │ (create h-entry) ││
|
||||
│ │ - Generate RSS XML │ │ • GET /api/micropub ││
|
||||
│ │ - Format dates RFC-822 │ │ (query config/source) ││
|
||||
│ │ - CDATA-wrap content │ │ • validate_token() ││
|
||||
│ │ │ │ • check_scope() ││
|
||||
│ │ Dependencies: │ │ • parse_micropub() ││
|
||||
│ │ - notes.py │ │ ││
|
||||
│ │ - feedgen library │ │ Dependencies: ││
|
||||
│ │ │ │ - auth.py (token val) ││
|
||||
│ │ │ │ - notes.py (create) ││
|
||||
│ │ │ │ - models.py ││
|
||||
│ └────────────────────────────┘ └────────────────────────────┘│
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ LEVEL 6: Additional Routes (Depends on Level 5) │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||||
│ │ routes/api.py (OPTIONAL for V1) │ │
|
||||
│ │ │ │
|
||||
│ │ • GET /api/notes (list published) │ │
|
||||
│ │ • POST /api/notes (create, requires auth) │ │
|
||||
│ │ • GET /api/notes/<slug> (get single) │ │
|
||||
│ │ • PUT /api/notes/<slug> (update, requires auth) │ │
|
||||
│ │ • DELETE /api/notes/<slug> (delete, requires auth) │ │
|
||||
│ │ │ │
|
||||
│ │ Dependencies: auth.py, notes.py, feed.py │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||||
│ │ Feed Route (added to public.py) │ │
|
||||
│ │ │ │
|
||||
│ │ • GET /feed.xml (RSS feed) │ │
|
||||
│ │ │ │
|
||||
│ │ Dependencies: feed.py │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ LEVEL 7: Testing (Depends on All Above) │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
|
||||
│ │ test_utils.py │ │ test_models.py │ │ test_notes.py │ │
|
||||
│ └────────────────┘ └────────────────┘ └────────────────┘ │
|
||||
│ │
|
||||
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
|
||||
│ │ test_auth.py │ │ test_feed.py │ │test_micropub.py│ │
|
||||
│ └────────────────┘ └────────────────┘ └────────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||||
│ │ test_integration.py │ │
|
||||
│ │ │ │
|
||||
│ │ • End-to-end user flows │ │
|
||||
│ │ • File/database sync verification │ │
|
||||
│ │ • Cross-module integration tests │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ LEVEL 8: Validation & Documentation (Depends on Complete App) │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌────────────────────────────────────────────────────────┐ │
|
||||
│ │ Standards Validation │ │
|
||||
│ │ │ │
|
||||
│ │ • W3C HTML Validator (templates) │ │
|
||||
│ │ • W3C Feed Validator (/feed.xml) │ │
|
||||
│ │ • IndieWebify.me (Microformats) │ │
|
||||
│ │ • Micropub.rocks (Micropub endpoint) │ │
|
||||
│ └────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌────────────────────────────────────────────────────────┐ │
|
||||
│ │ Security Testing │ │
|
||||
│ │ │ │
|
||||
│ │ • CSRF protection • XSS prevention │ │
|
||||
│ │ • SQL injection • Path traversal │ │
|
||||
│ │ • Auth/authz • Security headers │ │
|
||||
│ └────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌────────────────────────────────────────────────────────┐ │
|
||||
│ │ Documentation │ │
|
||||
│ │ │ │
|
||||
│ │ • README.md (updated) • docs/user-guide.md │ │
|
||||
│ │ • docs/deployment.md • docs/api.md │ │
|
||||
│ │ • CONTRIBUTING.md • Inline docstrings │ │
|
||||
│ └────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Critical Path
|
||||
|
||||
The **critical path** (minimum features for working system):
|
||||
|
||||
```
|
||||
utils.py → models.py → notes.py → auth.py → routes/admin.py + routes/public.py
|
||||
↓
|
||||
feed.py → /feed.xml route
|
||||
↓
|
||||
micropub.py → /api/micropub route
|
||||
↓
|
||||
Integration tests → Standards validation → V1 RELEASE
|
||||
```
|
||||
|
||||
Everything else can be done in parallel or deferred.
|
||||
|
||||
---
|
||||
|
||||
## Parallel Work Opportunities
|
||||
|
||||
These items can be worked on in parallel (no dependencies between them):
|
||||
|
||||
### Group A: Foundation (can do simultaneously)
|
||||
- `utils.py`
|
||||
- `templates/` (all 9 templates)
|
||||
- `static/css/style.css`
|
||||
|
||||
### Group B: After models.py (can do simultaneously)
|
||||
- `notes.py`
|
||||
- `auth.py`
|
||||
|
||||
### Group C: After Level 3 (can do simultaneously)
|
||||
- `feed.py`
|
||||
- `micropub.py`
|
||||
- `routes/public.py`
|
||||
- `routes/admin.py`
|
||||
|
||||
### Group D: Tests (can write alongside features)
|
||||
- Unit tests for each module
|
||||
- Integration tests after features complete
|
||||
|
||||
---
|
||||
|
||||
## Module Relationships Matrix
|
||||
|
||||
| Module | Depends On | Used By |
|
||||
|--------|-----------|---------|
|
||||
| `config.py` | None | All modules (via Flask app.config) |
|
||||
| `database.py` | None | notes.py, auth.py, micropub.py |
|
||||
| `utils.py` | None | models.py, notes.py, feed.py |
|
||||
| `models.py` | utils.py | notes.py, auth.py, micropub.py, routes/* |
|
||||
| `notes.py` | utils.py, models.py, database.py | routes/*, feed.py, micropub.py |
|
||||
| `auth.py` | models.py, database.py, httpx | routes/admin.py, micropub.py |
|
||||
| `feed.py` | notes.py, feedgen | routes/public.py |
|
||||
| `micropub.py` | auth.py, notes.py, models.py | routes/api.py |
|
||||
| `routes/public.py` | notes.py, feed.py, templates/ | __init__.py (blueprint) |
|
||||
| `routes/admin.py` | auth.py, notes.py, templates/admin/ | __init__.py (blueprint) |
|
||||
| `routes/api.py` | auth.py, notes.py, micropub.py | __init__.py (blueprint) |
|
||||
|
||||
---
|
||||
|
||||
## External Dependencies
|
||||
|
||||
### Python Packages (from requirements.txt)
|
||||
```
|
||||
Flask ──────────→ All route modules
|
||||
markdown ───────→ models.py (render content to HTML)
|
||||
feedgen ────────→ feed.py (generate RSS XML)
|
||||
httpx ──────────→ auth.py (call IndieLogin API)
|
||||
python-dotenv ──→ config.py (load .env file)
|
||||
pytest ─────────→ All test modules
|
||||
```
|
||||
|
||||
### External Services
|
||||
```
|
||||
indielogin.com ─→ auth.py (OAuth authentication)
|
||||
W3C Validators ─→ Testing phase (standards validation)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Note Creation Flow
|
||||
```
|
||||
User/Micropub Client
|
||||
↓
|
||||
routes/admin.py OR micropub.py
|
||||
↓
|
||||
notes.create_note()
|
||||
↓
|
||||
utils.generate_slug()
|
||||
utils.atomic_file_write() ──→ data/notes/YYYY/MM/slug.md
|
||||
utils.content_hash()
|
||||
↓
|
||||
database.py (insert note record)
|
||||
↓
|
||||
models.Note object
|
||||
↓
|
||||
Return to caller
|
||||
```
|
||||
|
||||
### Authentication Flow
|
||||
```
|
||||
User
|
||||
↓
|
||||
routes/admin.py (login form)
|
||||
↓
|
||||
auth.initiate_login()
|
||||
↓
|
||||
Redirect to indielogin.com
|
||||
↓
|
||||
User authenticates
|
||||
↓
|
||||
Callback to routes/admin.py
|
||||
↓
|
||||
auth.handle_callback()
|
||||
↓
|
||||
httpx.post() to indielogin.com
|
||||
↓
|
||||
auth.create_session()
|
||||
↓
|
||||
database.py (insert session)
|
||||
↓
|
||||
Set cookie, redirect to /admin
|
||||
```
|
||||
|
||||
### RSS Feed Flow
|
||||
```
|
||||
Request to /feed.xml
|
||||
↓
|
||||
routes/public.py
|
||||
↓
|
||||
feed.generate_rss_feed()
|
||||
↓
|
||||
notes.list_notes(published_only=True)
|
||||
↓
|
||||
database.py (query published notes)
|
||||
↓
|
||||
Read file content for each note
|
||||
↓
|
||||
feedgen library (build RSS XML)
|
||||
↓
|
||||
Return XML with headers
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Checklist by Level
|
||||
|
||||
### Level 0: Infrastructure ✓
|
||||
- [x] config.py
|
||||
- [x] database.py
|
||||
- [x] __init__.py
|
||||
|
||||
### Level 1: Foundation
|
||||
- [ ] utils.py
|
||||
- [ ] All 9 templates
|
||||
- [ ] style.css
|
||||
|
||||
### Level 2: Data Models
|
||||
- [ ] models.py
|
||||
|
||||
### Level 3: Core Features
|
||||
- [ ] notes.py
|
||||
- [ ] auth.py
|
||||
|
||||
### Level 4: Web Routes
|
||||
- [ ] routes/public.py
|
||||
- [ ] routes/admin.py
|
||||
|
||||
### Level 5: API Features
|
||||
- [ ] feed.py
|
||||
- [ ] micropub.py
|
||||
|
||||
### Level 6: Additional Routes
|
||||
- [ ] routes/api.py (optional)
|
||||
- [ ] /feed.xml route
|
||||
|
||||
### Level 7: Testing
|
||||
- [ ] test_utils.py
|
||||
- [ ] test_models.py
|
||||
- [ ] test_notes.py
|
||||
- [ ] test_auth.py
|
||||
- [ ] test_feed.py
|
||||
- [ ] test_micropub.py
|
||||
- [ ] test_integration.py
|
||||
|
||||
### Level 8: Validation & Docs
|
||||
- [ ] Standards validation
|
||||
- [ ] Security testing
|
||||
- [ ] Documentation updates
|
||||
|
||||
---
|
||||
|
||||
## Estimated Effort by Level
|
||||
|
||||
| Level | Components | Hours | Cumulative |
|
||||
|-------|-----------|-------|------------|
|
||||
| 0 | Infrastructure | 0 (done) | 0 |
|
||||
| 1 | Foundation | 5-7 | 5-7 |
|
||||
| 2 | Data Models | 3-4 | 8-11 |
|
||||
| 3 | Core Features | 11-14 | 19-25 |
|
||||
| 4 | Web Routes | 7-9 | 26-34 |
|
||||
| 5 | API Features | 9-12 | 35-46 |
|
||||
| 6 | Additional | 3-4 | 38-50 |
|
||||
| 7 | Testing | 9-12 | 47-62 |
|
||||
| 8 | Validation | 5-7 | 52-69 |
|
||||
|
||||
**Total**: 52-69 hours (~2-3 weeks full-time, 4-5 weeks part-time)
|
||||
|
||||
---
|
||||
|
||||
## Quick Decision Guide
|
||||
|
||||
**"Can I work on X yet?"**
|
||||
|
||||
1. Find X in the diagram above
|
||||
2. Check what level it's in
|
||||
3. All levels above must be complete first
|
||||
4. Items in same level can be done in parallel
|
||||
|
||||
**"What should I implement next?"**
|
||||
|
||||
1. Find the lowest incomplete level
|
||||
2. Choose any item from that level
|
||||
3. Implement it completely (code + tests + docs)
|
||||
4. Check it off
|
||||
5. Repeat
|
||||
|
||||
**"I'm blocked on Y, what else can I do?"**
|
||||
|
||||
1. Look for items in the same level as Y
|
||||
2. Those can be done in parallel
|
||||
3. Or start on tests for completed modules
|
||||
4. Or work on templates/CSS (always parallelizable)
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- [Implementation Plan](implementation-plan.md) - Detailed tasks for each module
|
||||
- [Quick Reference](quick-reference.md) - Fast lookup guide
|
||||
- [Feature Scope](feature-scope.md) - What's in/out of scope
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-11-18
|
||||
@@ -1,407 +0,0 @@
|
||||
# StarPunk V1 Feature Scope
|
||||
|
||||
## Purpose
|
||||
|
||||
This document clearly defines what is IN SCOPE and OUT OF SCOPE for StarPunk V1. This helps maintain focus and prevents scope creep while implementing the minimal viable IndieWeb CMS.
|
||||
|
||||
---
|
||||
|
||||
## V1 Core Philosophy
|
||||
|
||||
"Every line of code must justify its existence. When in doubt, leave it out."
|
||||
|
||||
V1 is intentionally minimal. The goal is a working, standards-compliant IndieWeb CMS that does ONE thing well: publish short notes with maximum simplicity and data ownership.
|
||||
|
||||
---
|
||||
|
||||
## IN SCOPE for V1
|
||||
|
||||
### Authentication & Authorization
|
||||
|
||||
| Feature | Status | Priority | Implementation |
|
||||
|---------|--------|----------|----------------|
|
||||
| IndieLogin.com OAuth flow | IN SCOPE | REQUIRED | ADR-005 |
|
||||
| Session-based admin auth | IN SCOPE | REQUIRED | 30-day sessions |
|
||||
| Single authorized user (ADMIN_ME) | IN SCOPE | REQUIRED | Config-based |
|
||||
| Secure session cookies | IN SCOPE | REQUIRED | HttpOnly, Secure, SameSite |
|
||||
| CSRF protection (state tokens) | IN SCOPE | REQUIRED | OAuth state param |
|
||||
| Logout functionality | IN SCOPE | REQUIRED | Delete session |
|
||||
| Micropub bearer tokens | IN SCOPE | REQUIRED | For API access |
|
||||
|
||||
**Why**: Authentication is core requirement for admin access and IndieWeb compliance.
|
||||
|
||||
---
|
||||
|
||||
### Notes Management
|
||||
|
||||
| Feature | Status | Priority | Implementation |
|
||||
|---------|--------|----------|----------------|
|
||||
| Create note (markdown) | IN SCOPE | REQUIRED | Web form + Micropub |
|
||||
| Read note (single) | IN SCOPE | REQUIRED | By slug |
|
||||
| List notes (all/published) | IN SCOPE | REQUIRED | Paginated |
|
||||
| Update note | IN SCOPE | REQUIRED | Web form |
|
||||
| Delete note | IN SCOPE | REQUIRED | Soft delete |
|
||||
| Published/draft status | IN SCOPE | REQUIRED | Boolean flag |
|
||||
| Timestamps (created, updated) | IN SCOPE | REQUIRED | Automatic |
|
||||
| Unique slugs (URL-safe) | IN SCOPE | REQUIRED | Auto-generated |
|
||||
| File-based storage (markdown) | IN SCOPE | REQUIRED | ADR-004 |
|
||||
| Database metadata | IN SCOPE | REQUIRED | SQLite |
|
||||
| File/DB sync | IN SCOPE | REQUIRED | Atomic operations |
|
||||
| Content hash (integrity) | IN SCOPE | REQUIRED | SHA-256 |
|
||||
|
||||
**Why**: Notes are the core entity. File+DB hybrid provides portability + performance.
|
||||
|
||||
---
|
||||
|
||||
### Web Interface (Public)
|
||||
|
||||
| Feature | Status | Priority | Implementation |
|
||||
|---------|--------|----------|----------------|
|
||||
| Homepage (note list) | IN SCOPE | REQUIRED | Reverse chronological |
|
||||
| Note permalink page | IN SCOPE | REQUIRED | Individual note view |
|
||||
| Responsive design | IN SCOPE | REQUIRED | Mobile-first CSS |
|
||||
| Semantic HTML5 | IN SCOPE | REQUIRED | Valid markup |
|
||||
| Microformats2 markup | IN SCOPE | REQUIRED | h-entry, h-card, h-feed |
|
||||
| RSS feed auto-discovery | IN SCOPE | REQUIRED | Link rel="alternate" |
|
||||
| Basic CSS styling | IN SCOPE | REQUIRED | ~200 lines |
|
||||
| Server-side rendering | IN SCOPE | REQUIRED | Jinja2 templates |
|
||||
|
||||
**Why**: Public interface is how notes are consumed. Microformats are IndieWeb requirement.
|
||||
|
||||
---
|
||||
|
||||
### Web Interface (Admin)
|
||||
|
||||
| Feature | Status | Priority | Implementation |
|
||||
|---------|--------|----------|----------------|
|
||||
| Login page | IN SCOPE | REQUIRED | IndieLogin form |
|
||||
| Admin dashboard | IN SCOPE | REQUIRED | List all notes |
|
||||
| Create note form | IN SCOPE | REQUIRED | Markdown textarea |
|
||||
| Edit note form | IN SCOPE | REQUIRED | Pre-filled form |
|
||||
| Delete note button | IN SCOPE | REQUIRED | With confirmation |
|
||||
| Logout button | IN SCOPE | REQUIRED | Clear session |
|
||||
| Flash messages (errors/success) | IN SCOPE | REQUIRED | User feedback |
|
||||
| Protected routes (@require_auth) | IN SCOPE | REQUIRED | Auth decorator |
|
||||
|
||||
**Why**: Admin interface is essential for creating/managing notes without external tools.
|
||||
|
||||
---
|
||||
|
||||
### Micropub Support
|
||||
|
||||
| Feature | Status | Priority | Implementation |
|
||||
|---------|--------|----------|----------------|
|
||||
| Micropub endpoint (/api/micropub) | IN SCOPE | REQUIRED | POST + GET |
|
||||
| Create h-entry (note) | IN SCOPE | REQUIRED | JSON + form-encoded |
|
||||
| Query config (q=config) | IN SCOPE | REQUIRED | Return capabilities |
|
||||
| Query source (q=source) | IN SCOPE | REQUIRED | Return note by URL |
|
||||
| Bearer token authentication | IN SCOPE | REQUIRED | Authorization header |
|
||||
| Scope validation (create/post) | IN SCOPE | REQUIRED | Check token scope |
|
||||
| Endpoint discovery (link rel) | IN SCOPE | REQUIRED | In HTML head |
|
||||
| Micropub spec compliance | IN SCOPE | REQUIRED | Pass micropub.rocks |
|
||||
|
||||
**Why**: Micropub is core IndieWeb standard. Enables publishing from external clients.
|
||||
|
||||
---
|
||||
|
||||
### RSS Feed
|
||||
|
||||
| Feature | Status | Priority | Implementation |
|
||||
|---------|--------|----------|----------------|
|
||||
| RSS 2.0 feed (/feed.xml) | IN SCOPE | REQUIRED | Valid XML |
|
||||
| All published notes | IN SCOPE | REQUIRED | Limit 50 most recent |
|
||||
| Valid RSS structure | IN SCOPE | REQUIRED | Pass W3C validator |
|
||||
| RFC-822 date format | IN SCOPE | REQUIRED | pubDate element |
|
||||
| CDATA-wrapped content | IN SCOPE | REQUIRED | Rendered HTML |
|
||||
| Feed metadata (title, link, desc) | IN SCOPE | REQUIRED | From config |
|
||||
| Cache-Control headers | IN SCOPE | REQUIRED | 5 minute cache |
|
||||
|
||||
**Why**: RSS is core requirement for syndication. Standard feed format.
|
||||
|
||||
---
|
||||
|
||||
### Data Management
|
||||
|
||||
| Feature | Status | Priority | Implementation |
|
||||
|---------|--------|----------|----------------|
|
||||
| SQLite database | IN SCOPE | REQUIRED | Single file |
|
||||
| Database schema (4 tables) | IN SCOPE | REQUIRED | notes, sessions, tokens, auth_state |
|
||||
| Database indexes | IN SCOPE | REQUIRED | For performance |
|
||||
| Markdown files on disk | IN SCOPE | REQUIRED | Year/month structure |
|
||||
| Atomic file writes | IN SCOPE | REQUIRED | Temp + rename |
|
||||
| Backup via file copy | IN SCOPE | REQUIRED | User can copy data/ |
|
||||
| Configuration via .env | IN SCOPE | REQUIRED | python-dotenv |
|
||||
|
||||
**Why**: Hybrid storage gives portability + performance. Simple backup strategy.
|
||||
|
||||
---
|
||||
|
||||
### Security
|
||||
|
||||
| Feature | Status | Priority | Implementation |
|
||||
|---------|--------|----------|----------------|
|
||||
| HTTPS required (production) | IN SCOPE | REQUIRED | Via reverse proxy |
|
||||
| SQL injection prevention | IN SCOPE | REQUIRED | Parameterized queries |
|
||||
| XSS prevention | IN SCOPE | REQUIRED | Markdown sanitization |
|
||||
| CSRF protection | IN SCOPE | REQUIRED | State tokens |
|
||||
| Path traversal prevention | IN SCOPE | REQUIRED | Path validation |
|
||||
| Security headers | IN SCOPE | REQUIRED | CSP, X-Frame-Options, etc |
|
||||
| Secure cookie flags | IN SCOPE | REQUIRED | HttpOnly, Secure, SameSite |
|
||||
| Session expiry | IN SCOPE | REQUIRED | 30 days |
|
||||
|
||||
**Why**: Security is non-negotiable. Basic protections are essential.
|
||||
|
||||
---
|
||||
|
||||
### Testing
|
||||
|
||||
| Feature | Status | Priority | Implementation |
|
||||
|---------|--------|----------|----------------|
|
||||
| Unit tests (pytest) | IN SCOPE | REQUIRED | >80% coverage |
|
||||
| Integration tests | IN SCOPE | REQUIRED | Key user flows |
|
||||
| Mock external services | IN SCOPE | REQUIRED | IndieLogin, etc |
|
||||
| Test fixtures (conftest.py) | IN SCOPE | REQUIRED | Shared setup |
|
||||
| HTML validation | IN SCOPE | REQUIRED | W3C validator |
|
||||
| RSS validation | IN SCOPE | REQUIRED | W3C feed validator |
|
||||
| Microformats validation | IN SCOPE | REQUIRED | IndieWebify.me |
|
||||
| Micropub validation | IN SCOPE | REQUIRED | micropub.rocks |
|
||||
|
||||
**Why**: Tests ensure reliability. Validation ensures standards compliance.
|
||||
|
||||
---
|
||||
|
||||
### Documentation
|
||||
|
||||
| Feature | Status | Priority | Implementation |
|
||||
|---------|--------|----------|----------------|
|
||||
| README.md | IN SCOPE | REQUIRED | Installation, usage |
|
||||
| Architecture docs | IN SCOPE | REQUIRED | Already complete |
|
||||
| ADRs (Architecture decisions) | IN SCOPE | REQUIRED | Already complete |
|
||||
| User guide | IN SCOPE | REQUIRED | How to use |
|
||||
| Deployment guide | IN SCOPE | REQUIRED | Production setup |
|
||||
| API documentation | IN SCOPE | REQUIRED | Micropub + REST |
|
||||
| Code documentation (docstrings) | IN SCOPE | REQUIRED | All functions |
|
||||
|
||||
**Why**: Documentation is code. Essential for users and maintainers.
|
||||
|
||||
---
|
||||
|
||||
## OUT OF SCOPE for V1
|
||||
|
||||
### Deferred to V2 or Later
|
||||
|
||||
| Feature | Status | Reason | Consider for V2? |
|
||||
|---------|--------|--------|------------------|
|
||||
| Multi-user support | OUT OF SCOPE | V1 is single-user | Maybe V2 |
|
||||
| User management | OUT OF SCOPE | Not needed for single user | Maybe V2 |
|
||||
| Tags/categories | OUT OF SCOPE | Keep it simple | Yes V2 |
|
||||
| Full-text search | OUT OF SCOPE | Can grep files | Yes V2 |
|
||||
| Media uploads (images) | OUT OF SCOPE | Notes are text-only | Yes V2 |
|
||||
| Media management | OUT OF SCOPE | No media in V1 | Yes V2 |
|
||||
| Update/delete via Micropub | OUT OF SCOPE | Create only is sufficient | Yes V2 |
|
||||
| Webmentions (send) | OUT OF SCOPE | Future feature | Yes V2 |
|
||||
| Webmentions (receive) | OUT OF SCOPE | Future feature | Yes V2 |
|
||||
| Syndication targets (POSSE) | OUT OF SCOPE | Manual syndication | Yes V2 |
|
||||
| Reply-context | OUT OF SCOPE | Simple notes only | Maybe V2 |
|
||||
| Like/repost support | OUT OF SCOPE | h-entry notes only | Maybe V2 |
|
||||
| Custom post types | OUT OF SCOPE | Just notes | Maybe V2 |
|
||||
| Frontmatter in files | OUT OF SCOPE | Pure markdown | Maybe V2 |
|
||||
| Git integration | OUT OF SCOPE | User can add manually | Maybe V2 |
|
||||
| Media endpoint (Micropub) | OUT OF SCOPE | No media support | Yes V2 |
|
||||
| Database migrations | OUT OF SCOPE | Fresh install only | Yes V2 |
|
||||
| Import from other systems | OUT OF SCOPE | Manual import | Yes V2 |
|
||||
| Export functionality | OUT OF SCOPE | Just copy files | Maybe V2 |
|
||||
| Themes/customization | OUT OF SCOPE | One simple theme | No |
|
||||
| Plugins/extensions | OUT OF SCOPE | No plugin system | No |
|
||||
| Admin user roles | OUT OF SCOPE | Single admin only | No |
|
||||
| Rate limiting (app-level) | OUT OF SCOPE | Use reverse proxy | No |
|
||||
| Caching (Redis/Memcached) | OUT OF SCOPE | Simple in-memory | Maybe V2 |
|
||||
| Multiple databases | OUT OF SCOPE | SQLite only | No |
|
||||
| Email notifications | OUT OF SCOPE | No notifications | Maybe V2 |
|
||||
| Scheduled posts | OUT OF SCOPE | Manual publish | Maybe V2 |
|
||||
| Draft autosave | OUT OF SCOPE | Manual save | Maybe V2 |
|
||||
| Revision history | OUT OF SCOPE | Use git if needed | Maybe V2 |
|
||||
| Markdown preview (real-time) | OPTIONAL V1 | Enhancement only | Low priority |
|
||||
| Dark mode toggle | OUT OF SCOPE | CSS only | Maybe V2 |
|
||||
| Mobile app | OUT OF SCOPE | Use Micropub clients | No |
|
||||
| Desktop app | OUT OF SCOPE | Web interface | No |
|
||||
| Self-hosted IndieAuth | OUT OF SCOPE | Use indielogin.com | Maybe V2 |
|
||||
| Token endpoint | OUT OF SCOPE | External IndieAuth | Maybe V2 |
|
||||
| Metrics/analytics | OUT OF SCOPE | Use reverse proxy logs | Maybe V2 |
|
||||
| Comments | OUT OF SCOPE | Use webmentions (V2) | Maybe V2 |
|
||||
| OpenGraph meta tags | OUT OF SCOPE | Microformats enough | Maybe V2 |
|
||||
| Twitter cards | OUT OF SCOPE | Not needed | Maybe V2 |
|
||||
| Sitemap.xml | OUT OF SCOPE | Small site, not needed | Maybe V2 |
|
||||
| robots.txt | OUT OF SCOPE | User can add | Maybe V2 |
|
||||
| Custom domains (multi-site) | OUT OF SCOPE | Single instance | No |
|
||||
| CDN integration | OUT OF SCOPE | Static files local | Maybe V2 |
|
||||
| Backups (automated) | OUT OF SCOPE | Manual copy | Maybe V2 |
|
||||
| Monitoring/alerting | OUT OF SCOPE | Use external tools | No |
|
||||
|
||||
**Why Defer**: These features add complexity without adding essential value for V1. The goal is a minimal, working system. Additional features can be added after V1 proves the core concept.
|
||||
|
||||
---
|
||||
|
||||
## Borderline Features (Decide During Implementation)
|
||||
|
||||
These features are on the fence. Implement only if trivial, defer if any complexity.
|
||||
|
||||
| Feature | Status | Decision Criteria |
|
||||
|---------|--------|-------------------|
|
||||
| Markdown preview (JS) | OPTIONAL | If <50 lines of code, include. Otherwise defer. |
|
||||
| JSON REST API | OPTIONAL | If admin interface uses it, include. Otherwise defer. |
|
||||
| Note search | OUT OF SCOPE | Too complex. User can grep files. |
|
||||
| Feed caching | OPTIONAL | If easy with Flask-Caching, include. Otherwise defer. |
|
||||
| Orphan detection | OUT OF SCOPE | Too complex for V1. Manual recovery. |
|
||||
| Email fallback auth | OUT OF SCOPE | IndieLogin only. Keep it simple. |
|
||||
|
||||
---
|
||||
|
||||
## Feature Justification Framework
|
||||
|
||||
When considering a feature for V1, ask:
|
||||
|
||||
### 1. Is it required for core functionality?
|
||||
- Can create, read, update, delete notes? ✓ REQUIRED
|
||||
- Can authenticate and access admin? ✓ REQUIRED
|
||||
- Can publish via Micropub? ✓ REQUIRED (IndieWeb spec)
|
||||
- Can syndicate via RSS? ✓ REQUIRED (Spec requirement)
|
||||
- Everything else? → Consider deferring
|
||||
|
||||
### 2. Is it required for standards compliance?
|
||||
- IndieAuth? ✓ REQUIRED
|
||||
- Micropub? ✓ REQUIRED
|
||||
- Microformats2? ✓ REQUIRED
|
||||
- RSS 2.0? ✓ REQUIRED
|
||||
- Everything else? → Consider deferring
|
||||
|
||||
### 3. Is it required for security?
|
||||
- Authentication? ✓ REQUIRED
|
||||
- CSRF protection? ✓ REQUIRED
|
||||
- SQL injection prevention? ✓ REQUIRED
|
||||
- XSS prevention? ✓ REQUIRED
|
||||
- Everything else? → Consider case by case
|
||||
|
||||
### 4. Does it add significant complexity?
|
||||
- Adds >100 LOC? → Probably defer
|
||||
- Adds dependencies? → Probably defer
|
||||
- Adds database tables? → Probably defer
|
||||
- Adds external services? → Probably defer
|
||||
|
||||
### 5. Can it be added later without breaking changes?
|
||||
- Yes? → DEFER to V2
|
||||
- No? → Consider including (but scrutinize)
|
||||
|
||||
---
|
||||
|
||||
## V1 Success Criteria
|
||||
|
||||
V1 is successful if a user can:
|
||||
|
||||
1. ✓ Install and configure StarPunk in <15 minutes
|
||||
2. ✓ Authenticate with their IndieWeb identity
|
||||
3. ✓ Create a note via web interface
|
||||
4. ✓ See the note on the public homepage
|
||||
5. ✓ Access the note at a permanent URL
|
||||
6. ✓ Edit and delete notes
|
||||
7. ✓ Publish via a Micropub client (e.g., Quill)
|
||||
8. ✓ Subscribe to updates via RSS
|
||||
9. ✓ Back up their data by copying a directory
|
||||
10. ✓ Migrate to another server by copying files
|
||||
|
||||
**What V1 is NOT**:
|
||||
- Not a full-featured blog platform (use WordPress)
|
||||
- Not a social network (use Mastodon)
|
||||
- Not a CMS for large sites (use Django)
|
||||
- Not a photo gallery (use Pixelfed)
|
||||
- Not a link blog (build that in V2)
|
||||
|
||||
**What V1 IS**:
|
||||
- A minimal note-publishing system
|
||||
- IndieWeb-compliant
|
||||
- User owns their data
|
||||
- Simple enough to understand completely
|
||||
- Extensible foundation for V2
|
||||
|
||||
---
|
||||
|
||||
## Lines of Code Budget
|
||||
|
||||
To maintain simplicity, we set maximum LOC targets:
|
||||
|
||||
| Module | Target LOC | Maximum LOC | Actual LOC |
|
||||
|--------|-----------|-------------|------------|
|
||||
| utils.py | 100 | 150 | TBD |
|
||||
| models.py | 150 | 200 | TBD |
|
||||
| notes.py | 300 | 400 | TBD |
|
||||
| auth.py | 200 | 300 | TBD |
|
||||
| feed.py | 100 | 150 | TBD |
|
||||
| micropub.py | 250 | 350 | TBD |
|
||||
| routes/public.py | 100 | 150 | TBD |
|
||||
| routes/admin.py | 200 | 300 | TBD |
|
||||
| routes/api.py | 150 | 200 | TBD |
|
||||
| **Total Application** | **~1,550** | **~2,200** | TBD |
|
||||
| **Total Tests** | **~1,000** | **~1,500** | TBD |
|
||||
| **Grand Total** | **~2,550** | **~3,700** | TBD |
|
||||
|
||||
**If a module exceeds maximum**: Refactor or defer features.
|
||||
|
||||
---
|
||||
|
||||
## V2 Feature Ideas (Future)
|
||||
|
||||
Good ideas for after V1 ships:
|
||||
|
||||
### High Priority for V2
|
||||
- Tags and categories
|
||||
- Full-text search
|
||||
- Media uploads and management
|
||||
- Update/delete via Micropub
|
||||
- Webmentions (send and receive)
|
||||
- POSSE syndication
|
||||
- Database migrations
|
||||
|
||||
### Medium Priority for V2
|
||||
- Multiple post types (articles, photos, etc.)
|
||||
- Reply context
|
||||
- Revision history
|
||||
- Scheduled posts
|
||||
- Import from other platforms
|
||||
- Better admin dashboard (stats, charts)
|
||||
|
||||
### Low Priority for V2+
|
||||
- Self-hosted IndieAuth
|
||||
- Themes
|
||||
- Plugins
|
||||
- Multi-user support
|
||||
|
||||
---
|
||||
|
||||
## Scope Change Process
|
||||
|
||||
If a feature is proposed during V1 development:
|
||||
|
||||
1. **Check this document** - Is it already in/out of scope?
|
||||
2. **Apply justification framework** - Does it meet criteria?
|
||||
3. **Estimate complexity** - How many LOC? New dependencies?
|
||||
4. **Consider deferral** - Can it wait for V2?
|
||||
5. **Document decision** - Update this document
|
||||
6. **Get approval** - Architect must approve scope changes
|
||||
|
||||
**Default answer**: "Great idea! Let's add it to the V2 backlog."
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**IN SCOPE**: Core note CRUD, IndieAuth, Micropub, RSS, basic web interface, security essentials, tests, docs
|
||||
|
||||
**OUT OF SCOPE**: Everything else (tags, search, media, multi-user, fancy features)
|
||||
|
||||
**Philosophy**: Ship a minimal, working, standards-compliant V1. Then iterate.
|
||||
|
||||
**Remember**: "When in doubt, leave it out."
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-11-18
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,339 +0,0 @@
|
||||
# StarPunk V1 Quick Reference
|
||||
|
||||
## Implementation Order (Dependency-Based)
|
||||
|
||||
This is the strict dependency order for implementing StarPunk V1. Each item depends on all items above it.
|
||||
|
||||
### Layer 1: Foundation (No Dependencies)
|
||||
1. `starpunk/utils.py` - Utility functions
|
||||
2. `starpunk/models.py` - Data models
|
||||
3. `templates/` - All HTML templates (can be done in parallel)
|
||||
4. `static/css/style.css` - Styling (can be done in parallel)
|
||||
|
||||
### Layer 2: Core Features (Depends on Layer 1)
|
||||
5. `starpunk/notes.py` - Notes CRUD operations (depends on utils, models)
|
||||
6. `starpunk/auth.py` - Authentication (depends on models)
|
||||
|
||||
### Layer 3: Web Interface (Depends on Layers 1-2)
|
||||
7. `starpunk/routes/public.py` - Public routes (depends on notes)
|
||||
8. `starpunk/routes/admin.py` - Admin routes (depends on auth, notes)
|
||||
|
||||
### Layer 4: Additional Features (Depends on Layers 1-2)
|
||||
9. `starpunk/feed.py` - RSS feed generation (depends on notes)
|
||||
10. `starpunk/micropub.py` - Micropub endpoint (depends on auth, notes)
|
||||
|
||||
### Layer 5: API Routes (Depends on Layers 1-4)
|
||||
11. `starpunk/routes/api.py` - REST API (optional, depends on auth, notes)
|
||||
|
||||
### Layer 6: Testing (Depends on All Above)
|
||||
12. Unit tests for each module
|
||||
13. Integration tests
|
||||
14. Standards validation
|
||||
15. Security testing
|
||||
|
||||
### Layer 7: Documentation (Depends on Complete Implementation)
|
||||
16. User documentation
|
||||
17. Deployment guide
|
||||
18. API documentation
|
||||
|
||||
---
|
||||
|
||||
## Module Dependencies
|
||||
|
||||
```
|
||||
database.py (already complete)
|
||||
config.py (already complete)
|
||||
↓
|
||||
utils.py → models.py
|
||||
↓ ↓
|
||||
↓ notes.py ← auth.py
|
||||
↓ ↓ ↓
|
||||
↓ feed.py micropub.py
|
||||
↓ ↓ ↓
|
||||
└─→ routes/public.py
|
||||
↓
|
||||
routes/admin.py (also depends on auth.py)
|
||||
↓
|
||||
routes/api.py (optional)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Critical Path Items
|
||||
|
||||
These features MUST be implemented for a functional V1:
|
||||
|
||||
### Tier 1: Absolutely Required
|
||||
- [ ] `utils.py` - Can't create notes without slug generation
|
||||
- [ ] `models.py` - Everything uses these data structures
|
||||
- [ ] `notes.py` - Core functionality
|
||||
- [ ] `auth.py` - Required for admin access
|
||||
- [ ] `routes/admin.py` - Required to create notes via web
|
||||
- [ ] `routes/public.py` - Required to view notes
|
||||
|
||||
### Tier 2: Required for IndieWeb Compliance
|
||||
- [ ] `feed.py` - RSS is required per specs
|
||||
- [ ] `micropub.py` - Micropub is required per specs
|
||||
- [ ] Microformats in templates - Required per specs
|
||||
|
||||
### Tier 3: Nice to Have
|
||||
- [ ] `routes/api.py` - Bonus JSON API (not required)
|
||||
- [ ] `static/js/preview.js` - Enhancement only
|
||||
- [ ] Media uploads - Can defer to V2
|
||||
|
||||
---
|
||||
|
||||
## File Checklist
|
||||
|
||||
### Python Modules (9 files)
|
||||
- [x] `starpunk/__init__.py` (complete)
|
||||
- [x] `starpunk/config.py` (complete)
|
||||
- [x] `starpunk/database.py` (complete)
|
||||
- [ ] `starpunk/utils.py` (implement in Phase 1)
|
||||
- [ ] `starpunk/models.py` (implement in Phase 1)
|
||||
- [ ] `starpunk/notes.py` (implement in Phase 2)
|
||||
- [ ] `starpunk/auth.py` (implement in Phase 3)
|
||||
- [ ] `starpunk/feed.py` (implement in Phase 5)
|
||||
- [ ] `starpunk/micropub.py` (implement in Phase 6)
|
||||
|
||||
### Route Blueprints (3 files)
|
||||
- [ ] `starpunk/routes/__init__.py` (create in Phase 4)
|
||||
- [ ] `starpunk/routes/public.py` (implement in Phase 4)
|
||||
- [ ] `starpunk/routes/admin.py` (implement in Phase 4)
|
||||
- [ ] `starpunk/routes/api.py` (optional, Phase 7)
|
||||
|
||||
### Templates (9 files)
|
||||
- [ ] `templates/base.html`
|
||||
- [ ] `templates/index.html`
|
||||
- [ ] `templates/note.html`
|
||||
- [ ] `templates/admin/base.html`
|
||||
- [ ] `templates/admin/login.html`
|
||||
- [ ] `templates/admin/dashboard.html`
|
||||
- [ ] `templates/admin/new.html`
|
||||
- [ ] `templates/admin/edit.html`
|
||||
- [ ] `templates/feed.xml`
|
||||
|
||||
### Static Files (2 files)
|
||||
- [ ] `static/css/style.css` (required)
|
||||
- [ ] `static/js/preview.js` (optional)
|
||||
|
||||
### Test Files (9 files)
|
||||
- [x] `tests/__init__.py` (complete)
|
||||
- [x] `tests/conftest.py` (complete)
|
||||
- [ ] `tests/test_utils.py`
|
||||
- [ ] `tests/test_models.py`
|
||||
- [ ] `tests/test_notes.py`
|
||||
- [ ] `tests/test_auth.py`
|
||||
- [ ] `tests/test_feed.py`
|
||||
- [ ] `tests/test_micropub.py`
|
||||
- [ ] `tests/test_integration.py`
|
||||
|
||||
### Documentation Files
|
||||
- [ ] Update `README.md` (Phase 9)
|
||||
- [ ] `docs/architecture/deployment.md` (Phase 9)
|
||||
- [ ] `docs/user-guide.md` (Phase 9)
|
||||
- [ ] `docs/api.md` (Phase 9)
|
||||
- [ ] `CONTRIBUTING.md` (Phase 9)
|
||||
|
||||
**Total Files to Create**: ~35 files
|
||||
|
||||
---
|
||||
|
||||
## Test Coverage Requirements
|
||||
|
||||
### Unit Tests (>90% coverage)
|
||||
- `test_utils.py` → `utils.py`
|
||||
- `test_models.py` → `models.py`
|
||||
- `test_notes.py` → `notes.py`
|
||||
- `test_auth.py` → `auth.py`
|
||||
- `test_feed.py` → `feed.py`
|
||||
- `test_micropub.py` → `micropub.py`
|
||||
|
||||
### Integration Tests (major flows)
|
||||
- Login → Create Note → View Note → Edit → Delete
|
||||
- Micropub → Publish → View on Site
|
||||
- RSS Feed Updates
|
||||
|
||||
### Standards Validation (manual/automated)
|
||||
- W3C HTML Validator
|
||||
- W3C Feed Validator
|
||||
- IndieWebify.me (Microformats)
|
||||
- Micropub.rocks (Micropub compliance)
|
||||
|
||||
### Security Testing
|
||||
- CSRF protection
|
||||
- SQL injection prevention
|
||||
- XSS prevention
|
||||
- Path traversal prevention
|
||||
- Authentication/authorization
|
||||
|
||||
---
|
||||
|
||||
## Configuration Checklist
|
||||
|
||||
### Required .env Variables
|
||||
```bash
|
||||
# CRITICAL - Must set these
|
||||
SESSION_SECRET=<generate with: python3 -c "import secrets; print(secrets.token_hex(32))">
|
||||
ADMIN_ME=https://your-website.com
|
||||
|
||||
# Important
|
||||
SITE_URL=http://localhost:5000
|
||||
SITE_NAME=My StarPunk Site
|
||||
SITE_AUTHOR=Your Name
|
||||
|
||||
# Optional (have defaults)
|
||||
SITE_DESCRIPTION=
|
||||
SESSION_LIFETIME=30
|
||||
INDIELOGIN_URL=https://indielogin.com
|
||||
DATA_PATH=./data
|
||||
NOTES_PATH=./data/notes
|
||||
DATABASE_PATH=./data/starpunk.db
|
||||
FLASK_ENV=development
|
||||
FLASK_DEBUG=1
|
||||
LOG_LEVEL=INFO
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Development Commands
|
||||
|
||||
```bash
|
||||
# Activate virtual environment
|
||||
source /home/phil/Projects/starpunk/.venv/bin/activate
|
||||
|
||||
# Run development server
|
||||
flask --app app.py run --debug
|
||||
|
||||
# Run tests
|
||||
pytest
|
||||
|
||||
# Run tests with coverage
|
||||
pytest --cov=starpunk --cov-report=html
|
||||
|
||||
# Format code
|
||||
black starpunk/ tests/
|
||||
|
||||
# Lint code
|
||||
flake8 starpunk/ tests/
|
||||
|
||||
# Type check
|
||||
mypy starpunk/
|
||||
|
||||
# Install dependencies
|
||||
uv pip install -r requirements.txt
|
||||
|
||||
# Install dev dependencies
|
||||
uv pip install -r requirements-dev.txt
|
||||
|
||||
# Create database
|
||||
python -c "from starpunk.database import init_db; init_db()"
|
||||
|
||||
# Run specific test file
|
||||
pytest tests/test_notes.py
|
||||
|
||||
# Run specific test
|
||||
pytest tests/test_notes.py::test_create_note
|
||||
|
||||
# Check test coverage
|
||||
pytest --cov=starpunk --cov-report=term-missing
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Design Decisions Reference
|
||||
|
||||
Quick lookup for architectural decisions:
|
||||
|
||||
| Decision | ADR | Key Choice |
|
||||
|----------|-----|------------|
|
||||
| Web Framework | ADR-001 | Flask (minimal, no magic) |
|
||||
| Dependencies | ADR-002 | 6 packages only (Flask, markdown, feedgen, httpx, python-dotenv, pytest) |
|
||||
| Frontend | ADR-003 | Server-side rendering, minimal JS |
|
||||
| Storage | ADR-004 | Hybrid: Files for content, DB for metadata |
|
||||
| Authentication | ADR-005 | IndieLogin.com (delegated OAuth) |
|
||||
| Virtual Env | ADR-006 | uv package manager, Python 3.11+ |
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
### V1 is complete when:
|
||||
- [ ] Can create notes via web interface
|
||||
- [ ] Can authenticate with IndieLogin.com
|
||||
- [ ] Can view published notes on public site
|
||||
- [ ] Can publish via Micropub client
|
||||
- [ ] RSS feed is valid and updates
|
||||
- [ ] All tests pass (>80% coverage)
|
||||
- [ ] All validators pass (HTML, RSS, Microformats, Micropub)
|
||||
- [ ] Documentation is complete
|
||||
- [ ] Deployable to production
|
||||
|
||||
### Performance Targets
|
||||
- [ ] API responses < 100ms
|
||||
- [ ] Page renders < 200ms
|
||||
- [ ] RSS generation < 300ms
|
||||
- [ ] Memory usage < 100MB
|
||||
|
||||
### Quality Targets
|
||||
- [ ] Test coverage > 80%
|
||||
- [ ] No security vulnerabilities
|
||||
- [ ] Valid HTML5
|
||||
- [ ] Valid RSS 2.0
|
||||
- [ ] Valid Microformats2
|
||||
- [ ] Micropub spec compliant
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting Common Issues
|
||||
|
||||
### Database locked errors
|
||||
- Close all database connections
|
||||
- Check if another process has lock
|
||||
- Restart Flask app
|
||||
|
||||
### IndieLogin fails
|
||||
- Check ADMIN_ME is set correctly
|
||||
- Verify internet connection to indielogin.com
|
||||
- Check state token hasn't expired (5 min limit)
|
||||
|
||||
### File not found errors
|
||||
- Check DATA_PATH exists
|
||||
- Check file permissions (need write access)
|
||||
- Check year/month directories created
|
||||
|
||||
### Import errors
|
||||
- Ensure virtual environment activated
|
||||
- Run `uv pip install -r requirements.txt`
|
||||
- Check PYTHONPATH if needed
|
||||
|
||||
### Tests fail
|
||||
- Check database initialized
|
||||
- Check test fixtures in conftest.py
|
||||
- Ensure test isolation (no shared state)
|
||||
|
||||
---
|
||||
|
||||
## Quick Links
|
||||
|
||||
### Documentation
|
||||
- [Full Implementation Plan](implementation-plan.md)
|
||||
- [Architecture Overview](/home/phil/Projects/starpunk/docs/architecture/overview.md)
|
||||
- [Technology Stack](/home/phil/Projects/starpunk/docs/architecture/technology-stack.md)
|
||||
|
||||
### External Specs
|
||||
- [Micropub Spec](https://micropub.spec.indieweb.org/)
|
||||
- [IndieAuth Spec](https://www.w3.org/TR/indieauth/)
|
||||
- [Microformats2](http://microformats.org/wiki/microformats2)
|
||||
- [RSS 2.0 Spec](https://www.rssboard.org/rss-specification)
|
||||
|
||||
### Tools
|
||||
- [W3C HTML Validator](https://validator.w3.org/)
|
||||
- [W3C Feed Validator](https://validator.w3.org/feed/)
|
||||
- [IndieWebify.me](https://indiewebify.me/)
|
||||
- [Micropub.rocks](https://micropub.rocks/)
|
||||
- [Quill (Micropub Client)](https://quill.p3k.io/)
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-11-18
|
||||
Reference in New Issue
Block a user