# 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