diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..2357d6c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,43 @@ +# Codex Agent Handoff + +This repo is a Laravel/Inertia React live streaming platform called Nyone. + +For updating UI/UX, start by reading: + +- `docs/ui-ux-handoff.md` +- `resources/js/pages/welcome.tsx` +- `resources/js/pages/dashboard.tsx` +- `resources/js/pages/channels/show.tsx` +- `resources/js/pages/admin/dashboard.tsx` +- `resources/js/components/app-header.tsx` +- `resources/js/components/app-sidebar.tsx` + +## Project Shape + +- Backend: Laravel 13, Fortify auth, Inertia, PostgreSQL intended for production, SQLite currently used in local `.env`. +- Frontend: React 19, TypeScript, Tailwind CSS 4, Radix UI primitives, lucide-react icons, hls.js. +- Streaming: MediaMTX receives OBS RTMP, validates publish requests via Laravel, serves HLS, and calls lifecycle hooks. +- Key user flows: public live directory, creator studio, channel watch page with chat/follow, basic admin moderation. + +## Design Work Rules + +- Focus on UI/UX in `resources/js` and `resources/css/app.css`. +- Keep the existing Laravel routes/controllers/models unless a UI change requires a small prop shape addition. +- Use existing UI primitives from `resources/js/components/ui`. +- Use lucide icons for controls. +- Avoid decorative landing-page marketing. The first screen should remain the live product experience. +- Keep operational/tooling files intact unless explicitly asked: `deploy/`, `routes/`, migrations, MediaMTX integration. +- Generated Wayfinder files live in `resources/js/actions`, `resources/js/routes`, and `resources/js/wayfinder`; do not hand-edit them. + +## Verify Before Handing Back + +Use the available Herd/Node binaries on this machine: + +```powershell +& 'C:\Users\meghdad\.config\herd\bin\php84\php.exe' artisan test +& 'C:\Users\meghdad\.config\herd\bin\nvm\v25.2.1\npm.cmd' run format:check +& 'C:\Users\meghdad\.config\herd\bin\nvm\v25.2.1\npm.cmd' run lint:check +& 'C:\Users\meghdad\.config\herd\bin\nvm\v25.2.1\npm.cmd' run types:check +& 'C:\Users\meghdad\.config\herd\bin\nvm\v25.2.1\npm.cmd' run build +``` + diff --git a/docs/ui-ux-handoff.md b/docs/ui-ux-handoff.md new file mode 100644 index 0000000..86bad9b --- /dev/null +++ b/docs/ui-ux-handoff.md @@ -0,0 +1,215 @@ +# Nyone UI/UX Handoff + +## Product Summary + +Nyone is a self-hosted live streaming platform MVP. + +Users can: + +- Register/login. +- Create exactly one creator channel. +- Generate/rotate a private OBS stream key. +- Prepare a broadcast with a title and optional VOD recording. +- Stream from OBS to MediaMTX using RTMP. +- Watch public live channels through HLS. +- Chat and follow channels when logged in. +- Use a basic admin panel for live stream/channel moderation. + +The design should feel like an actual streaming product, not a Laravel starter page or marketing homepage. Prioritize the viewer watch experience, creator studio clarity, and readable dense controls. + +## Current Stack + +- Laravel 13 + Fortify auth. +- Inertia React 19 + TypeScript. +- Tailwind CSS 4. +- Radix UI primitives under `resources/js/components/ui`. +- lucide-react icons. +- hls.js player wrapper at `resources/js/components/video-player.tsx`. +- Wayfinder route/action files are generated under `resources/js/actions`, `resources/js/routes`, and `resources/js/wayfinder`. + +Do not manually edit generated Wayfinder files. They regenerate during `npm run build`. + +## Important Frontend Files + +- `resources/js/pages/welcome.tsx`: public live directory and logged-out entry point. +- `resources/js/pages/dashboard.tsx`: creator studio for channel setup, OBS details, stream key rotation, broadcast creation, recent broadcasts. +- `resources/js/pages/channels/show.tsx`: channel watch page, HLS player, channel meta, follow, VOD list, chat panel. +- `resources/js/pages/admin/dashboard.tsx`: basic admin moderation dashboard. +- `resources/js/components/app-header.tsx`: authenticated layout header navigation. +- `resources/js/components/app-sidebar.tsx`: authenticated sidebar navigation. +- `resources/js/components/video-player.tsx`: HLS/native playback wrapper. +- `resources/js/types/streaming.ts`: frontend DTO types from controllers. +- `resources/css/app.css`: global Tailwind/theme layer. + +## Backend Props And Routes + +The UI currently receives arrays and objects from these controllers: + +- `HomeController`: `liveChannels`, `categories`, `canRegister`. +- `CreatorDashboardController`: `channel`, `plainStreamKey`, `streaming`, `categories`, `recentBroadcasts`. +- `ChannelController`: `channel`, `currentBroadcast`, `vods`, `chatMessages`, `isFollowing`. +- `AdminDashboardController`: `stats`, `liveBroadcasts`, `channels`. + +Useful routes currently used by UI: + +- `GET /` +- `GET /dashboard` +- `POST /creator/channel` +- `PATCH /creator/channel` +- `POST /creator/stream-key/rotate` +- `POST /creator/broadcasts` +- `POST /creator/broadcasts/{broadcast}/stop` +- `GET /channels/{slug}` +- `POST /channels/{slug}/follow` +- `DELETE /channels/{slug}/follow` +- `POST /channels/{slug}/chat` +- `GET /admin` + +Small backend prop additions are acceptable if they directly improve UI, such as image URLs, richer broadcast state labels, or structured empty-state data. Avoid unrelated backend refactors during a UI pass. + +## Current UX State + +The current UI is functional but first-pass: + +- Live directory has basic hero text, filters, and cards. +- Creator studio is form-heavy and needs stronger visual hierarchy. +- Watch page works but needs better theatre mode, chat density, offline state, VOD presentation, and responsive layout. +- Admin page is utilitarian and acceptable as a secondary priority. +- Branding is minimal: Nyone name plus simple play logo. +- No polished thumbnail/banner/avatar upload flow yet. +- Chat is currently persisted by form submission, not realtime. +- Viewer count is stored but not realtime/presence-driven. + +## Recommended UI/UX Priorities + +1. Channel watch page: + - Make the player the clear primary surface. + - Improve live/offline states. + - Make chat usable on desktop and mobile. + - Add better channel header/meta and follow affordance. + - Add responsive layout: video first, collapsible or below-player chat on smaller screens. + +2. Creator studio: + - Separate setup states: no channel, channel exists, pending broadcast, live broadcast. + - Make OBS setup copy actions unmistakable. + - Make stream key warning and rotation behavior clear. + - Improve broadcast creation and current live session controls. + +3. Live directory: + - Replace generic cards with stream-like cards. + - Improve search/category filtering layout. + - Add high-quality empty/offline states. + - Keep first viewport focused on live content, not marketing. + +4. Navigation and shell: + - Make Live, Studio, Admin navigation consistent. + - Reduce starter-kit residue. + - Ensure dark/light modes both look intentional. + +## Design Constraints + +- Build actual product screens, not a landing page. +- Use icons for controls where clear. +- Cards should be compact, max `rounded-md`; avoid large decorative card stacks. +- Avoid purple/blue gradient-heavy, beige-only, and generic SaaS hero styling. +- Avoid decorative blobs/orbs. +- Do not use SVG illustration as the main visual. +- Text must fit on mobile; do not use viewport-scaled fonts. +- Do not nest cards inside cards. +- Keep layouts dense enough for repeated creator/admin use. + +## Local Development + +The project has dependencies installed in this workspace. The local `.env` currently uses SQLite. + +Useful commands: + +```powershell +cd C:\Users\meghdad\PhpstormProjects\nyone + +& 'C:\Users\meghdad\.config\herd\bin\php84\php.exe' artisan migrate --seed +& 'C:\Users\meghdad\.config\herd\bin\nvm\v25.2.1\npm.cmd' run dev -- --host 127.0.0.1 --port 5173 +``` + +PHP built-in server command used successfully: + +```powershell +cd C:\Users\meghdad\PhpstormProjects\nyone\public + +& 'C:\Users\meghdad\.config\herd\bin\php84\php.exe' -S 127.0.0.1:8001 ..\vendor\laravel\framework\src\Illuminate\Foundation\resources\server.php +``` + +Local app URL: + +```text +http://127.0.0.1:8001 +``` + +Seeded users: + +```text +test@example.com / password +admin@example.com / password +``` + +## Streaming And Deployment Context + +Current `.env` values relevant to streaming: + +```env +APP_URL=https://nyone.net +STREAMING_RTMP_INGEST_URL=rtmp://nyone.net:19935 +STREAMING_HLS_PUBLIC_URL=https://nyone-hls.net +MEDIAMTX_SHARED_SECRET=change-this-secret +``` + +MediaMTX current files: + +- `deploy/mediamtx.yml`: currently points auth/hooks to `https://nyone.net`. +- `deploy/mediamtx.home.yml`: points auth/hooks to `https://nyone.net`. + +Known mismatch: + +- `.env` currently points the app at `nyone.net`, while `deploy/mediamtx.yml` points MediaMTX hooks at `nyone.net`. +- Before live testing, decide which domain is active and align `.env`, `deploy/mediamtx.yml`, and Nginx config. + +MediaMTX ports currently configured: + +- RTMP: `:19935` +- HLS: `:19988` + +OBS should use: + +```text +Server: rtmp://nyone.net:19935 +Stream Key: ?token= +``` + +There is no need for Nginx TCP proxy for RTMP if port `19935` is open directly. Nginx is still useful for Laravel HTTPS and HLS HTTPS proxy. + +## Verification + +Run these before handing back UI work: + +```powershell +& 'C:\Users\meghdad\.config\herd\bin\php84\php.exe' artisan test +& 'C:\Users\meghdad\.config\herd\bin\nvm\v25.2.1\npm.cmd' run format:check +& 'C:\Users\meghdad\.config\herd\bin\nvm\v25.2.1\npm.cmd' run lint:check +& 'C:\Users\meghdad\.config\herd\bin\nvm\v25.2.1\npm.cmd' run types:check +& 'C:\Users\meghdad\.config\herd\bin\nvm\v25.2.1\npm.cmd' run build +``` + +Last known successful verification from previous implementation: + +- `artisan test`: 49 passing. +- `format:check`: clean. +- `lint:check`: clean. +- `types:check`: clean. +- `build`: successful, with Vite chunk-size warnings due app/HLS bundles. + +## Suggested First Prompt For Next Session + +```text +Read AGENTS.md and docs/ui-ux-handoff.md. Focus only on improving Nyone's UI/UX. Start with the channel watch page and creator studio, keep backend changes minimal, and verify with tests/typecheck/build. +``` +