add AGENTS docs
This commit is contained in:
43
AGENTS.md
Normal file
43
AGENTS.md
Normal file
@@ -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
|
||||||
|
```
|
||||||
|
|
||||||
215
docs/ui-ux-handoff.md
Normal file
215
docs/ui-ux-handoff.md
Normal file
@@ -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: <channel-slug>?token=<generated-stream-key>
|
||||||
|
```
|
||||||
|
|
||||||
|
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.
|
||||||
|
```
|
||||||
|
|
||||||
Reference in New Issue
Block a user