16 KiB
16 KiB
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:
- ✓ Install and configure StarPunk in <15 minutes
- ✓ Authenticate with their IndieWeb identity
- ✓ Create a note via web interface
- ✓ See the note on the public homepage
- ✓ Access the note at a permanent URL
- ✓ Edit and delete notes
- ✓ Publish via a Micropub client (e.g., Quill)
- ✓ Subscribe to updates via RSS
- ✓ Back up their data by copying a directory
- ✓ 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:
- Check this document - Is it already in/out of scope?
- Apply justification framework - Does it meet criteria?
- Estimate complexity - How many LOC? New dependencies?
- Consider deferral - Can it wait for V2?
- Document decision - Update this document
- 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