diff --git a/backend/AGENTS.md b/backend/AGENTS.md new file mode 100644 index 0000000..0ddff3b --- /dev/null +++ b/backend/AGENTS.md @@ -0,0 +1,52 @@ +# Backend Agent Guide + +## Scope + +These instructions apply to work under `backend/`. Preserve the dependency +direction: routes and middleware call controllers; controllers call services; +services own domain rules and call repositories or integrations; repositories +own persistence queries. Services must not read Express `req` or write `res`. + +## Commands + +Run from `backend/`: + +```sh +npm run dev +npm test +npm test -- tests/api-videos.test.js +``` + +The test runner is Node's built-in serial runner. API tests use MongoDB Memory +Server by default. If `MONGODB_URI_TEST` is configured, tests drop that +database; only use a disposable test database. + +## Guardrails + +- Never commit `.env`, credentials, tokens, service-account JSON, or production + data. Environment variables are validated in `src/config/env.js`; update + `.env.example` and `docs/SETUP.md` when adding configuration. +- Keep Zod request validation in `src/middlewares/validators/` and business + rules in services. Use shared response and `AppError` helpers. +- Verify file contents from signatures, not supplied MIME types. Route uploads + through the storage service and preserve cleanup for partially completed + multi-file operations. +- MongoDB stores domain records and opaque storage references; media bytes + belong to configured storage drivers. Preserve visibility checks for + metadata and media routes. +- Redis is optional Upstash. Cache failures should be logged and fall back to + the authoritative database/storage path. Keep cache values small and apply + explicit TTLs. +- Update `src/docs/openapi.js`, `docs/API.md`, tests, and relevant architecture + docs when changing endpoints or behavior. Do not silently change append-only + submission or account-data retention behavior. + +## References + +- [Backend docs index](docs/README.md) +- [Setup and environment](docs/SETUP.md) +- [API contract](docs/API.md) +- [Architecture](docs/ARCHITECTURE.md) +- [Module reference](docs/MODULE-REFERENCE.md) +- [Design decisions](docs/design-docs/ARCHITECTURE-DECISIONS.md) +- [Test-case inventory](docs/TEST-CASES.md) diff --git a/backend/README.md b/backend/README.md index db35d6a..e31caac 100644 --- a/backend/README.md +++ b/backend/README.md @@ -47,9 +47,10 @@ business rules. `src/services/initialization.js` initializes MongoDB, storage, and the configured admin idempotently; `server.js` is the standalone and Vercel entry point. -Read the full references: [API](docs/API.md), -[architecture](docs/ARCHITECTURE.md), [setup](docs/SETUP.md), and -[test-case inventory](docs/TEST-CASES.md). +Read the [documentation index](docs/README.md), [API](docs/API.md), +[architecture](docs/ARCHITECTURE.md), [module reference](docs/MODULE-REFERENCE.md), +[setup](docs/SETUP.md), [design decisions](docs/design-docs/ARCHITECTURE-DECISIONS.md), +and [test-case inventory](docs/TEST-CASES.md). ## Responses diff --git a/backend/docs/API.md b/backend/docs/API.md index 61f9419..3ff9dcf 100644 --- a/backend/docs/API.md +++ b/backend/docs/API.md @@ -82,7 +82,7 @@ All paths below are relative to `/api/v1`. | GET | `/videos/:id` | Public or admin | Read a visible video. | | GET | `/videos/:id/file` | Public or admin | Stream a visible video, including byte-range requests. | | GET | `/videos/:id/poster` | Public or admin | Stream a visible video's poster, if present. | -| POST | `/videos` | Admin | Upload a reference video and optional poster. | +| POST | `/videos` | Admin | Upload a reference video or register a direct HTTPS video URL; URL sources require a poster. | | PATCH | `/videos/:id` | Admin | Update a video, including status or category. | | DELETE | `/videos/:id` | Admin | Delete a reference video and its base files; submissions remain. | | GET | `/demo-video` | Public | Read the current public demo-video metadata or `null`. | @@ -117,12 +117,13 @@ Authentication and profile request schemas are defined in client-supplied roles are ignored. Profile updates accept supported `connections` fields for GitHub and LinkedIn; `null` disconnects a connection. -The video and demo-video upload routes use `multipart/form-data`: +The video and demo-video creation routes use `multipart/form-data`: | Field | Video | Demo video | | --- | --- | --- | -| `video` | Required video file | Required video file | -| `poster` | Optional image file | Not accepted | +| `video` | Optional video file; provide this or `videoUrl`, but not both | Required video file | +| `videoUrl` | Optional direct HTTPS MP4/WebM URL; provide this or `video`, but not both | Not accepted | +| `poster` | Optional for uploaded files; required with `videoUrl` | Not accepted | | `title` | Required title | Required title | | `categoryId` | Optional category ID | Not accepted | | `status` | Optional video status | Not accepted | @@ -147,7 +148,15 @@ Uploads are bounded by `MAX_VIDEO_UPLOAD_MB` and `MAX_RECORDING_UPLOAD_MB` (defaults: 90 MB and 100 MB). Video signatures are checked as MP4, WebM, or MOV. Poster signatures are checked as JPEG, PNG, or WebP; posters must not exceed 2 MB. The browser-provided MIME type is not treated as -proof of file content. +proof of file content. External URLs must point directly to media playable in a +native HTML `