29 KiB
29 KiB
StarPunk V1 Dependencies Diagram
Module Implementation Order
This diagram shows the dependency relationships between all StarPunk V1 modules. Modules at the top have no dependencies and must be implemented first. Each level depends on all levels above it.
┌─────────────────────────────────────────────────────────────────┐
│ LEVEL 0: Already Complete (Infrastructure) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ config.py │ │ database.py │ │ __init__.py │ │
│ │ │ │ │ │ │ │
│ │ Loads .env │ │ SQLite DB │ │ create_app │ │
│ │ variables │ │ schema │ │ factory │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
│
↓
┌─────────────────────────────────────────────────────────────────┐
│ LEVEL 1: Foundation (No Dependencies) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ utils.py │ │
│ │ │ │
│ │ • generate_slug() • atomic_file_write() │ │
│ │ • content_hash() • date_formatting() │ │
│ │ • file_path_helpers() • path_validation() │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ templates/ (all 9 files) │ │
│ │ │ │
│ │ • base.html • admin/base.html │ │
│ │ • index.html • admin/login.html │ │
│ │ • note.html • admin/dashboard.html │ │
│ │ • feed.xml • admin/new.html │ │
│ │ • admin/edit.html │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ static/css/style.css │ │
│ │ │ │
│ │ • ~200 lines of CSS │ │
│ │ • Mobile-first responsive design │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
│
↓
┌─────────────────────────────────────────────────────────────────┐
│ LEVEL 2: Data Models (Depends on Level 1) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ models.py │ │
│ │ │ │
│ │ • Note (from_row, to_dict, content, html, permalink) │ │
│ │ • Session (from_row, is_expired, is_valid) │ │
│ │ • Token (from_row, is_expired, has_scope) │ │
│ │ • AuthState (from_row, is_expired) │ │
│ │ │ │
│ │ Dependencies: utils.py (uses slug generation, etc.) │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
│
↓
┌─────────────────────────────────────────────────────────────────┐
│ LEVEL 3: Core Features (Depends on Levels 1-2) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────┐ ┌────────────────────────────┐│
│ │ notes.py │ │ auth.py ││
│ │ │ │ ││
│ │ • create_note() │ │ • generate_state() ││
│ │ • get_note() │ │ • verify_state() ││
│ │ • list_notes() │ │ • create_session() ││
│ │ • update_note() │ │ • validate_session() ││
│ │ • delete_note() │ │ • initiate_login() ││
│ │ │ │ • handle_callback() ││
│ │ Dependencies: │ │ • require_auth() ││
│ │ - utils.py │ │ • logout() ││
│ │ - models.py │ │ ││
│ │ - database.py │ │ Dependencies: ││
│ │ │ │ - models.py ││
│ │ │ │ - database.py ││
│ │ │ │ - httpx (IndieLogin API) ││
│ └────────────────────────────┘ └────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────────┘
│
↓
┌─────────────────────────────────────────────────────────────────┐
│ LEVEL 4: Web Routes (Depends on Levels 1-3) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ routes/public.py │ │
│ │ │ │
│ │ • GET / (homepage, list notes) │ │
│ │ • GET /note/<slug> (note permalink) │ │
│ │ │ │
│ │ Dependencies: notes.py, models.py, templates/ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ routes/admin.py │ │
│ │ │ │
│ │ • GET /admin/login (login form) │ │
│ │ • POST /admin/login (initiate OAuth) │ │
│ │ • GET /auth/callback (OAuth callback) │ │
│ │ • GET /admin (dashboard) │ │
│ │ • GET /admin/new (create form) │ │
│ │ • POST /admin/new (create note) │ │
│ │ • GET /admin/edit/<slug>(edit form) │ │
│ │ • POST /admin/edit/<slug>(update note) │ │
│ │ • POST /admin/delete/<slug>(delete note) │ │
│ │ • POST /admin/logout (logout) │ │
│ │ │ │
│ │ Dependencies: auth.py, notes.py, templates/admin/ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
│
↓
┌─────────────────────────────────────────────────────────────────┐
│ LEVEL 5: API Features (Depends on Levels 1-3) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────┐ ┌────────────────────────────┐│
│ │ feed.py │ │ micropub.py ││
│ │ │ │ ││
│ │ • generate_rss_feed() │ │ • POST /api/micropub ││
│ │ - Query published notes │ │ (create h-entry) ││
│ │ - Generate RSS XML │ │ • GET /api/micropub ││
│ │ - Format dates RFC-822 │ │ (query config/source) ││
│ │ - CDATA-wrap content │ │ • validate_token() ││
│ │ │ │ • check_scope() ││
│ │ Dependencies: │ │ • parse_micropub() ││
│ │ - notes.py │ │ ││
│ │ - feedgen library │ │ Dependencies: ││
│ │ │ │ - auth.py (token val) ││
│ │ │ │ - notes.py (create) ││
│ │ │ │ - models.py ││
│ └────────────────────────────┘ └────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────────┘
│
↓
┌─────────────────────────────────────────────────────────────────┐
│ LEVEL 6: Additional Routes (Depends on Level 5) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ routes/api.py (OPTIONAL for V1) │ │
│ │ │ │
│ │ • GET /api/notes (list published) │ │
│ │ • POST /api/notes (create, requires auth) │ │
│ │ • GET /api/notes/<slug> (get single) │ │
│ │ • PUT /api/notes/<slug> (update, requires auth) │ │
│ │ • DELETE /api/notes/<slug> (delete, requires auth) │ │
│ │ │ │
│ │ Dependencies: auth.py, notes.py, feed.py │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Feed Route (added to public.py) │ │
│ │ │ │
│ │ • GET /feed.xml (RSS feed) │ │
│ │ │ │
│ │ Dependencies: feed.py │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
│
↓
┌─────────────────────────────────────────────────────────────────┐
│ LEVEL 7: Testing (Depends on All Above) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
│ │ test_utils.py │ │ test_models.py │ │ test_notes.py │ │
│ └────────────────┘ └────────────────┘ └────────────────┘ │
│ │
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
│ │ test_auth.py │ │ test_feed.py │ │test_micropub.py│ │
│ └────────────────┘ └────────────────┘ └────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ test_integration.py │ │
│ │ │ │
│ │ • End-to-end user flows │ │
│ │ • File/database sync verification │ │
│ │ • Cross-module integration tests │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
│
↓
┌─────────────────────────────────────────────────────────────────┐
│ LEVEL 8: Validation & Documentation (Depends on Complete App) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Standards Validation │ │
│ │ │ │
│ │ • W3C HTML Validator (templates) │ │
│ │ • W3C Feed Validator (/feed.xml) │ │
│ │ • IndieWebify.me (Microformats) │ │
│ │ • Micropub.rocks (Micropub endpoint) │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Security Testing │ │
│ │ │ │
│ │ • CSRF protection • XSS prevention │ │
│ │ • SQL injection • Path traversal │ │
│ │ • Auth/authz • Security headers │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Documentation │ │
│ │ │ │
│ │ • README.md (updated) • docs/user-guide.md │ │
│ │ • docs/deployment.md • docs/api.md │ │
│ │ • CONTRIBUTING.md • Inline docstrings │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Critical Path
The critical path (minimum features for working system):
utils.py → models.py → notes.py → auth.py → routes/admin.py + routes/public.py
↓
feed.py → /feed.xml route
↓
micropub.py → /api/micropub route
↓
Integration tests → Standards validation → V1 RELEASE
Everything else can be done in parallel or deferred.
Parallel Work Opportunities
These items can be worked on in parallel (no dependencies between them):
Group A: Foundation (can do simultaneously)
utils.pytemplates/(all 9 templates)static/css/style.css
Group B: After models.py (can do simultaneously)
notes.pyauth.py
Group C: After Level 3 (can do simultaneously)
feed.pymicropub.pyroutes/public.pyroutes/admin.py
Group D: Tests (can write alongside features)
- Unit tests for each module
- Integration tests after features complete
Module Relationships Matrix
| Module | Depends On | Used By |
|---|---|---|
config.py |
None | All modules (via Flask app.config) |
database.py |
None | notes.py, auth.py, micropub.py |
utils.py |
None | models.py, notes.py, feed.py |
models.py |
utils.py | notes.py, auth.py, micropub.py, routes/* |
notes.py |
utils.py, models.py, database.py | routes/*, feed.py, micropub.py |
auth.py |
models.py, database.py, httpx | routes/admin.py, micropub.py |
feed.py |
notes.py, feedgen | routes/public.py |
micropub.py |
auth.py, notes.py, models.py | routes/api.py |
routes/public.py |
notes.py, feed.py, templates/ | init.py (blueprint) |
routes/admin.py |
auth.py, notes.py, templates/admin/ | init.py (blueprint) |
routes/api.py |
auth.py, notes.py, micropub.py | init.py (blueprint) |
External Dependencies
Python Packages (from requirements.txt)
Flask ──────────→ All route modules
markdown ───────→ models.py (render content to HTML)
feedgen ────────→ feed.py (generate RSS XML)
httpx ──────────→ auth.py (call IndieLogin API)
python-dotenv ──→ config.py (load .env file)
pytest ─────────→ All test modules
External Services
indielogin.com ─→ auth.py (OAuth authentication)
W3C Validators ─→ Testing phase (standards validation)
Data Flow
Note Creation Flow
User/Micropub Client
↓
routes/admin.py OR micropub.py
↓
notes.create_note()
↓
utils.generate_slug()
utils.atomic_file_write() ──→ data/notes/YYYY/MM/slug.md
utils.content_hash()
↓
database.py (insert note record)
↓
models.Note object
↓
Return to caller
Authentication Flow
User
↓
routes/admin.py (login form)
↓
auth.initiate_login()
↓
Redirect to indielogin.com
↓
User authenticates
↓
Callback to routes/admin.py
↓
auth.handle_callback()
↓
httpx.post() to indielogin.com
↓
auth.create_session()
↓
database.py (insert session)
↓
Set cookie, redirect to /admin
RSS Feed Flow
Request to /feed.xml
↓
routes/public.py
↓
feed.generate_rss_feed()
↓
notes.list_notes(published_only=True)
↓
database.py (query published notes)
↓
Read file content for each note
↓
feedgen library (build RSS XML)
↓
Return XML with headers
Implementation Checklist by Level
Level 0: Infrastructure ✓
- config.py
- database.py
- init.py
Level 1: Foundation
- utils.py
- All 9 templates
- style.css
Level 2: Data Models
- models.py
Level 3: Core Features
- notes.py
- auth.py
Level 4: Web Routes
- routes/public.py
- routes/admin.py
Level 5: API Features
- feed.py
- micropub.py
Level 6: Additional Routes
- routes/api.py (optional)
- /feed.xml route
Level 7: Testing
- test_utils.py
- test_models.py
- test_notes.py
- test_auth.py
- test_feed.py
- test_micropub.py
- test_integration.py
Level 8: Validation & Docs
- Standards validation
- Security testing
- Documentation updates
Estimated Effort by Level
| Level | Components | Hours | Cumulative |
|---|---|---|---|
| 0 | Infrastructure | 0 (done) | 0 |
| 1 | Foundation | 5-7 | 5-7 |
| 2 | Data Models | 3-4 | 8-11 |
| 3 | Core Features | 11-14 | 19-25 |
| 4 | Web Routes | 7-9 | 26-34 |
| 5 | API Features | 9-12 | 35-46 |
| 6 | Additional | 3-4 | 38-50 |
| 7 | Testing | 9-12 | 47-62 |
| 8 | Validation | 5-7 | 52-69 |
Total: 52-69 hours (~2-3 weeks full-time, 4-5 weeks part-time)
Quick Decision Guide
"Can I work on X yet?"
- Find X in the diagram above
- Check what level it's in
- All levels above must be complete first
- Items in same level can be done in parallel
"What should I implement next?"
- Find the lowest incomplete level
- Choose any item from that level
- Implement it completely (code + tests + docs)
- Check it off
- Repeat
"I'm blocked on Y, what else can I do?"
- Look for items in the same level as Y
- Those can be done in parallel
- Or start on tests for completed modules
- Or work on templates/CSS (always parallelizable)
References
- Implementation Plan - Detailed tasks for each module
- Quick Reference - Fast lookup guide
- Feature Scope - What's in/out of scope
Last Updated: 2025-11-18