phil/StarPunk

Fork 0

Files

Phil Skentelbery a68fd570c7 that initial commit

2025-11-18 19:21:31 -07:00

8.9 KiB

Raw Blame History

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)

starpunk/utils.py - Utility functions
starpunk/models.py - Data models
templates/ - All HTML templates (can be done in parallel)
static/css/style.css - Styling (can be done in parallel)

Layer 2: Core Features (Depends on Layer 1)

starpunk/notes.py - Notes CRUD operations (depends on utils, models)
starpunk/auth.py - Authentication (depends on models)

Layer 3: Web Interface (Depends on Layers 1-2)

starpunk/routes/public.py - Public routes (depends on notes)
starpunk/routes/admin.py - Admin routes (depends on auth, notes)

Layer 4: Additional Features (Depends on Layers 1-2)

starpunk/feed.py - RSS feed generation (depends on notes)
starpunk/micropub.py - Micropub endpoint (depends on auth, notes)

Layer 5: API Routes (Depends on Layers 1-4)

starpunk/routes/api.py - REST API (optional, depends on auth, notes)

Layer 6: Testing (Depends on All Above)

Unit tests for each module
Integration tests
Standards validation
Security testing

Layer 7: Documentation (Depends on Complete Implementation)

User documentation
Deployment guide
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)

starpunk/__init__.py (complete)
starpunk/config.py (complete)
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)

tests/__init__.py (complete)
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

# 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

# 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

External Specs

Tools

Last Updated: 2025-11-18

8.9 KiB Raw Blame History