arcana-fx/BUILD_BRIEF.md

Build a deployable Docker Compose webapp named Arcana FX.

Purpose:

• D&D effects soundboard now; future control surface for lights/effects later.
• Frontend dashboard with tiles for audio effects. Pressing a tile tells backend to play that audio through Home Assistant.

Source audio:

• Filestash public share URL: https://files.fisoft.eu/s/FHBaJ8Z
• Put that URL and share id in config/config.json.
• The Filestash API flow discovered externally:
  1. POST https://files.fisoft.eu/api/share/FHBaJ8Z/proof with header X-Requested-With: XmlHttpRequest. It returns JSON with path /DnD/Audio/ and sets proof cookie.
  2. List directories with GET https://files.fisoft.eu/api/files/ls?path=&share=FHBaJ8Z with same header and proof cookie. Root path is '/'. Results contain files/directories.
  3. Stream/download file with GET https://files.fisoft.eu/api/files/cat?path=&share=FHBaJ8Z with proof cookie.
• Backend should cache/list recursive audio effects. Accept .mp3 .ogg .flac .wav .m4a. Ignore desktop.ini. Prefer not to preload/download all audio.
• Backend must expose an intranet media proxy endpoint for a selected path, e.g. /media?path=..., because Home Assistant needs a URL it can fetch. The backend should fetch from Filestash with its proof cookie and stream it.

Home Assistant:

• URL from env: HA_URL=http://192.168.33.33:8123
• Token from env only, never frontend and do not commit it.
• Allowed media player entity must be hardcoded/config-limited to media_player.audio_test_media_player.
• Backend service should expose only narrow endpoints: list effects, play a selected known effect path, stop optional. It must not accept arbitrary HA service/entity calls.
• Play implementation should call POST /api/services/media_player/play_media with entity_id media_player.audio_test_media_player, media_content_id as PUBLIC_BASE_URL + /media?path=..., media_content_type audio/mpeg or audio/ogg etc.

Deployment:

• Use docker-compose.yml, not raw docker run.
• Expose app on host port 8091.
• Frontend can be served by backend or nginx; keep simple. Backend service must be separate logical component/code from frontend speaker controls.
• Include Dockerfile, package files, README.
• Add health endpoint.
• Include .env.example but not .env.

Frontend:

• Creative dark fantasy control-room style.
• Search, category filters, status messages.
• Tiles should show name/category/path/type.
• Add future-light-control placeholders visibly but disabled/coming soon.

Tech preference:

• Use Node.js/Express backend and static frontend unless you have a better simple choice.
• Keep dependencies minimal.
• Include basic validation and error handling.