phil/StarPunk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

that initial commit

Browse Source
This commit is contained in:
Phil Skentelbery
2025-11-18 19:21:31 -07:00
commit a68fd570c7
69 changed files with 31070 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

309
docs/projectplan/v1/README.md Normal file
View File

@@ -0,0 +1,309 @@
# 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 | indieauth.spec.indieweb.org | 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://indieauth.spec.indieweb.org/)
- [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

485
docs/projectplan/v1/dependencies-diagram.md Normal file
View File

@@ -0,0 +1,485 @@
# 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

407
docs/projectplan/v1/feature-scope.md Normal file
View 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

1252
docs/projectplan/v1/implementation-plan.md Normal file
View File

File diff suppressed because it is too large Load Diff

339
docs/projectplan/v1/quick-reference.md Normal file
View File

@@ -0,0 +1,339 @@
# 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://indieauth.spec.indieweb.org/)
- [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