phil/StarPunk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
v0.6.1
StarPunk/docs/projectplan/v1
History
Phil Skentelbery 0cca8169ce feat: Implement Phase 4 Web Interface with bugfixes (v0.5.2) 
## Phase 4: Web Interface Implementation

Implemented complete web interface with public and admin routes,
templates, CSS, and development authentication.

### Core Features

**Public Routes**:
- Homepage with recent published notes
- Note permalinks with microformats2
- Server-side rendering (Jinja2)

**Admin Routes**:
- Login via IndieLogin
- Dashboard with note management
- Create, edit, delete notes
- Protected with @require_auth decorator

**Development Authentication**:
- Dev login bypass for local testing (DEV_MODE only)
- Security safeguards per ADR-011
- Returns 404 when disabled

**Templates & Frontend**:
- Base layouts (public + admin)
- 8 HTML templates with microformats2
- Custom responsive CSS (114 lines)
- Error pages (404, 500)

### Bugfixes (v0.5.1 → v0.5.2)

1. **Cookie collision fix (v0.5.1)**:
   - Renamed auth cookie from "session" to "starpunk_session"
   - Fixed redirect loop between dev login and admin dashboard
   - Flask's session cookie no longer conflicts with auth

2. **HTTP 404 error handling (v0.5.1)**:
   - Update route now returns 404 for nonexistent notes
   - Delete route now returns 404 for nonexistent notes
   - Follows ADR-012 HTTP Error Handling Policy
   - Pattern consistency across all admin routes

3. **Note model enhancement (v0.5.2)**:
   - Exposed deleted_at field from database schema
   - Enables soft deletion verification in tests
   - Follows ADR-013 transparency principle

### Architecture

**New ADRs**:
- ADR-011: Development Authentication Mechanism
- ADR-012: HTTP Error Handling Policy
- ADR-013: Expose deleted_at Field in Note Model

**Standards Compliance**:
- Uses uv for Python environment
- Black formatted, Flake8 clean
- Follows git branching strategy
- Version incremented per versioning strategy

### Test Results

- 405/406 tests passing (99.75%)
- 87% code coverage
- All security tests passing
- Manual testing confirmed working

### Documentation

- Complete implementation reports in docs/reports/
- Architecture reviews in docs/reviews/
- Design documents in docs/design/
- CHANGELOG updated for v0.5.2

### Files Changed

**New Modules**:
- starpunk/dev_auth.py
- starpunk/routes/ (public, admin, auth, dev_auth)

**Templates**: 10 files (base, pages, admin, errors)
**Static**: CSS and optional JavaScript
**Tests**: 4 test files for routes and templates
**Docs**: 20+ architectural and implementation documents

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-18 23:01:53 -07:00
..
dependencies-diagram.md
that initial commit
2025-11-18 19:21:31 -07:00
feature-scope.md
that initial commit
2025-11-18 19:21:31 -07:00
implementation-plan.md
feat: Implement Phase 4 Web Interface with bugfixes (v0.5.2)
2025-11-18 23:01:53 -07:00
quick-reference.md
that initial commit
2025-11-18 19:21:31 -07:00
README.md
that initial commit
2025-11-18 19:21:31 -07:00

README.md

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 (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

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

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 Decision Records (ADRs)

External Standards

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 completely
  2. Review Feature Scope to understand boundaries
  3. Bookmark Quick Reference 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

Reference in New Issue View Git Blame Copy Permalink