-
Notifications
You must be signed in to change notification settings - Fork 0
UX Strategy
Origin: First real-world beta feedback (TrueNAS user, 2026-03-13) revealed that MapArr's one-size-fits-all analysis approach doesn't serve all users well. This document captures the persona model, UI strategy, and the API integration vision that emerged from the design session.
Motivation: "I pasted the error. Give me the fix."
They hit an import failure in Sonarr/Radarr, googled it, found MapArr. They want the answer, not the education. Every second spent reading explanations is a second they're not watching their show.
- Arrives via paste flow almost exclusively
- Wants a single button that solves their problem
- Doesn't care about path philosophy or TRaSH Guides
- Success = error goes away
What MapArr must do: Big green button. Fix the thing. Confirm it's fixed. Done.
Motivation: "My setup works. I just need this one issue fixed."
They have a running setup -- often on a NAS, often "weird" by TRaSH standards, often evolved over months or years. They know enough to be dangerous. They don't want MapArr to restructure everything; they want it to respect what works and fix what doesn't.
The TrueNAS user who triggered this design is a perfect example: NAS datasets at /mnt/truenas/TV, paths that MapArr correctly flagged as mismatched, but the suggestion to mkdir -p and restructure was misleading for NAS mounts that already exist.
- Arrives via either pathway
- Wants targeted fixes, not full restructure
- Gets frustrated by suggestions that ignore their existing infrastructure
- Values RPM Wizard highly -- gives them the specific mapping without restructure
- Success = their specific problem is solved, everything else is left alone
What MapArr must do: Acknowledge what works. Offer the minimum change. Never imply their setup is "wrong" when it's just "different."
Motivation: "I want to do it the right way."
They're setting up fresh or willing to restructure. They read TRaSH Guides. They want MapArr's full analysis with corrected YAML, mkdir suggestions, the works. MapArr's current default behaviour suits them well.
- Often arrives via pipeline/browse flow
- Wants the full picture: every conflict, every recommendation
- Happy to restructure paths to follow best practices
- Values educational explanations
- Success = a clean, compliant setup
What MapArr must do: Full analysis, corrected YAML, mkdir suggestions. The current experience, essentially.
The strategy cards approach (big green button + targeted fix + full compliance cards on the results screen) was replaced by a simpler model: let the user self-select at the front door, not after analysis.
MapArr serves two fundamentally different needs:
- Left door: "My house is on fire." Put it out. Now. Don't tell me about building codes.
- Right door: "I'm building a house." Install sprinklers and smoke detectors so fires never happen.
The entire UX pivots on one question at the entry point:
What brings you here?
[I have an error] [Analyze my stack]
- Left door = Firefighter + Pragmatist path. Paste your error, get the fix. No dashboard, no stack grid, no restructure suggestions. Just the answer.
- Right door = Architect path. Full pipeline dashboard, stack health scores, corrected YAML, TRaSH compliance. The current MapArr experience.
- No persona detection needed -- the user tells you who they are with one click
- No NAS-aware messaging logic on the left -- the Firefighter path just gives the RPM answer, never shows restructure suggestions
- No strategy cards complexity -- the fork happens before analysis, not after
- Paste flow and pipeline stop competing -- they're separate journeys from the start
- Onboarding IS the product -- that first screen is the onboarding
The left door isn't a dead end -- it's the start of a journey:
- User enters left door, pastes error, gets RPM fix in 30 seconds
- After fix: gentle nudge -- "Fixed! Want to see your full stack health?"
- User clicks through, discovers the dashboard, sees other issues they didn't know about
- They're now an Architect -- and they walked themselves there
Nobody got told to restructure. Nobody was confused by options. They entered through the fire door, solved their problem, and received nudges along the way toward becoming the fire chief who deploys smoke detectors and sprinkler systems so they don't need firefighters.
This model enables a two-wave launch from one codebase:
Launch 1: "Paste your error, get the fix"
- Market only the left door
- Maximum virality, minimum intimidation
- The r/sonarr crowd googling "import failed path does not exist" at 11pm
Launch 2: "Now see your whole stack"
- Reveal the right door -- full dashboard, pipeline analysis, stack health
- Same app, same Docker image. Existing users just see a new option
- Two waves of attention, zero fragmentation
NAS-aware messaging applies to the Architect path (right door) where full analysis runs. When paths contain NAS indicators (truenas, nas, nfs, smb, cifs, mnt/, dataset-like structures):
-
Skip
mkdir -psuggestions (mount points, not directories to create) - Soften restructure language ("Your NAS paths work differently -- here's how to bridge them")
- Prefer RPM/targeted fixes over volume restructure
- Acknowledge dataset/share boundary structures
The left door doesn't need NAS awareness -- it just gives the fix without commentary.
MapArr currently analyzes compose files and tells you what's wrong. But the dream -- the original motivation for the entire product -- is to fix it for you. With API access to Sonarr/Radarr, MapArr can:
-
Read download client configurations (
GET /api/v3/downloadclient) -
Read existing remote path mappings (
GET /api/v3/remotepathmapping) -
Read import history to detect failures (
GET /api/v3/history) - Detect the exact mismatch between download client paths and library paths
-
Add the correct remote path mapping via API (
POST /api/v3/remotepathmapping)
This transforms MapArr from "here's what's wrong" to "I fixed it."
MapArr reads compose YAML
-> identifies path conflict between Sonarr and SABnzbd
-> calls Sonarr API: what download client paths do you see?
-> calls Sonarr API: what remote path mappings exist?
-> calculates the missing mapping
-> presents: "Add this mapping? [Yes]"
-> calls Sonarr API: POST the mapping
-> confirms: "Done. Your next import will work."
For API integration, MapArr needs API keys. The onboarding becomes:
- First run: "Which arr apps do you use?" (checkboxes: Sonarr, Radarr, Lidarr, etc.)
- For each selected: "Paste your API key" (with link to where to find it in Settings > General)
- MapArr validates each key with a test call
- Keys stored in MapArr config (not in compose files)
This is a one-time setup. After that, MapArr has full read/write access to the arr ecosystem.
| App | Endpoint | Purpose |
|---|---|---|
| Sonarr/Radarr | GET /api/v3/downloadclient |
What download clients are configured |
| Sonarr/Radarr | GET /api/v3/remotepathmapping |
Current RPM entries |
| Sonarr/Radarr | POST /api/v3/remotepathmapping |
Add new RPM entry |
| Sonarr/Radarr | GET /api/v3/history |
Import success/failure records |
| Sonarr/Radarr | GET /api/v3/rootfolder |
Configured library paths |
| Sonarr/Radarr | GET /api/v3/system/status |
Version, OS, paths |
| SABnzbd | GET /api?mode=get_config |
Download paths, categories |
| qBittorrent | GET /api/v2/app/preferences |
Save paths |
- Automatic import failure detection: Poll Sonarr/Radarr history for recent failures, correlate with known path mismatches
- One-click RPM fix: Calculate and apply the correct remote path mapping
- Proactive alerting: "Sonarr just failed an import. I can see why -- want me to fix it?"
- Download client config validation: Compare what the arr app thinks the download path is vs what's actually mounted
- Cross-app consistency check: Ensure all arr apps have consistent RPM entries
| Phase | What | When |
|---|---|---|
| Beta (current) | Ship with current UI, gather feedback | v1.5.x |
| v1.7 | Two-door landing page, left door = paste/fix, right door = dashboard | Near term |
| v2.0 | API integration -- left door upgrades to "connect your arrs, I'll fix it" | Headline release |
| v2.x | Monitoring/watch mode -- smoke detectors, proactive alerting | Post-launch |
These extend the principles in Design Decisions:
- Two doors, one building. The Firefighter and the Architect enter differently but use the same engine. One codebase, one Docker image, two experiences.
- You win either way. The left door fixes your problem. The right door prevents future problems. Neither is wrong.
- Respect what works. If a NAS user's paths are functional, don't tell them to restructure. Offer the bridge (RPM) instead of the demolition.
- The left door earns the right door. Fix someone's fire first. Then offer them smoke detectors. Never lead with "your house needs rewiring."
- API integration is opt-in. MapArr works fully without API keys. Keys upgrade the left door from "here's what to fix" to "I fixed it for you."
- Explain when asked, act when told. Left door defaults to action. Right door defaults to education. Both end with a working setup.