Atomic Archivist (AsimoAudio)

1

Mobile-first React + Vite app for streaming Asimov audio tracks.

Local development

Prerequisites: Node.js 20+

npm install
npm run dev

App runs on http://localhost:3000.

Production checks

npm run lint
npm run build

Deploy to GitHub Pages

This repo includes a GitHub Pages deployment workflow.

One-time GitHub setup

1. In GitHub, open Settings → Pages.
2. Under Build and deployment, set Source to GitHub Actions.
3. Ensure your default deploy branch is main.

Deploy flow

• Push to main.
• Workflow .github/workflows/deploy-pages.yml builds and deploys dist/.
• The workflow sets VITE_BASE_PATH from the repository name (/${repo}/) automatically, so forks deploy with their own base path.

PWA install (mobile)

The app is installable as a Progressive Web App:

• Android (Chrome): open site → tap Install.
• iOS (Safari): Share → Add to Home Screen.

Included PWA assets:

• public/manifest.webmanifest
• public/sw.js
• public/icons/*

Mobile troubleshooting

• Audio won’t play: tap play again (mobile browsers may require user interaction).
• Slow network/buffering: wait for stream recovery; retry if an error appears.
• Direct URL 404 on GitHub Pages: SPA fallback is handled by public/404.html.
• PWA doesn’t update: close app and reload once online to refresh service worker cache.

Environment and secrets policy

• This frontend build does not require runtime secrets.
• Do not expose API keys in client bundles.
• Keep .env* files local and uncommitted (except .env.example).

Release checklist

• npm run lint
• npm run build
• Validate on Android Chrome
• Validate on iOS Safari
• Verify install to home screen works
• Verify audio playback, buffering, and retry behavior on mobile data
• Merge to main and confirm GitHub Pages deploy succeeds