310 lines
9.6 KiB
Markdown
310 lines
9.6 KiB
Markdown
# 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
|