that initial commit
This commit is contained in:
407
docs/projectplan/v1/feature-scope.md
Normal file
407
docs/projectplan/v1/feature-scope.md
Normal file
@@ -0,0 +1,407 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user