User journey: Priya writes and publishes a Rymflux plugin
From discovering Rymflux to having a working plugin installed and verified.
User journey: Priya writes and publishes a Rymflux plugin
Metadata
- Persona: Priya — the plugin developer
- Scenario: Write a plugin for an existing music service API in Go
- Stage: Adoption (developer ecosystem)
- Frequency: Once per plugin, with periodic updates
Journey stages
| # | Stage | User action | Touchpoint | Emotion | Docs touch |
|---|---|---|---|---|---|
| 1 | Learn about plugin system | Priya finds Rymflux’s plugin documentation. Reads the overview and protocol spec | Website or docs site | 🟢 Clear, language-agnostic, well-structured | Plugin overview, protocol spec |
| 2 | Set up project | Priya creates a directory plugins/jamendo/, initializes a Go module, copies the hello-world example |
Local dev environment | 🟢 Example in Go exists, minimal boilerplate | Plugin developer guide, hello-world example |
| 3 | Write manifest | Priya creates plugin.toml with id, name, version, entry point, capabilities |
Text editor | 🟢 Simple, self-explanatory | Manifest reference |
| 4 | Implement search | Priya implements the search method in Go: reads JSON-RPC request from stdin, calls Jamendo API, returns standardized JSON |
Terminal, Go code | 🟡 Straightforward — the protocol is simple; API integration is the real work | Protocol reference, data model spec |
| 5 | Implement stream | Priya implements the stream method: accepts a content ID, returns a stream URL |
Terminal, Go code | 🟢 Same pattern as search | Streaming section of protocol spec |
| 6 | Test with conformance tool | Priya runs the conformance validator against her compiled binary. Finds a field name mismatch | Terminal | 🟡 Validator catches the issue with a clear error message | Conformance tool docs |
| 7 | Fix and retest | Priya fixes the field name, recompiles, re-runs validator. All tests pass | Terminal | 🟢 Quick fix, validator confirms | — |
| 8 | Install and verify | Priya copies the jamendo/ directory to ~/.rymflux/plugins/, launches Rymflux, opens Music Room, searches for a test query |
App | 🟢 Plugin content appears in the Music Room seamlessly | Plugin installation guide |
| 9 | Debug an edge case | A user reports that search for accented characters fails. Priya enables verbose logging, sees the raw request, identifies the encoding issue | App logs, terminal | 🟡 Logging is sufficient to debug without the app’s source code | Plugin debugging guide |
| 10 | Publish | Priya pushes the plugin to GitHub, adds a README with install instructions. Community finds and uses it | GitHub | 🟢 Published successfully | Publishing guide |
Pain points
- Stage 2 (Set up project): If no hello-world example exists in Go, Priya spends extra time figuring out the JSON-RPC framing. Mitigation: provide examples in 2-3 languages.
- Stage 6 (Test with conformance tool): If the conformance tool does not exist, Priya must run the full app to test. Slow iteration cycle. Mitigation: conformance validator is a v1 deliverable (see FR-PLUGIN-3 lifecycle).
- Stage 9 (Debug): If plugin logs are not surfaced or are hard to access, debugging becomes guesswork. Mitigation: stdout/stderr capture and
plugin healthcommand (see scope.md). - Stage 10 (Publish): There is no plugin registry or app store in v1. Users must copy directories manually. This limits discoverability. Mitigation: v1 accepts this as a trade-off; document manual install clearly.
Opportunities
| Stage | Opportunity | Doc type needed | Priority |
|---|---|---|---|
| 1 | Protocol spec with complete JSON schemas, not prose | Reference | H |
| 2 | Minimal hello-world plugin in Go and Python | Tutorial | H |
| 5 | Streaming section with both URL and pipe mode examples | Reference | H |
| 6 | Standalone conformance validator CLI tool | Tool docs | H |
| 8 | Clear troubleshooting for common install issues | Troubleshooting | M |
| 9 | Plugin logging and diagnostics guide | Reference | M |
Success criteria
- Priya can write a working plugin in under one hour (aspirational, see KPIs)
- Priya can test the plugin with a conformance validator without running the app
- Plugin is installable by copying a directory (no build step on the user’s machine)
- Plugin content appears in the Music Room without any app configuration
- Plugin published on GitHub with community install instructions
Related
- Persona: Priya — the plugin developer
- User stories: Register a content-source plugin, Stream audio from a plugin
- Functional requirements: FR-PLUGIN-1 through FR-PLUGIN-6, FR-REF-1
- Non-functional: NFR-SEC-1 through NFR-SEC-4, NFR-COMPAT-2