340 lines
8.9 KiB
Markdown
340 lines
8.9 KiB
Markdown
# 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
|