Skip to content

Commit b10d90b

Browse files
Merge pull request #29 from muhammadali-imran/main
v1.0.8 and v1.0.5
2 parents fd2cbc2 + fed6925 commit b10d90b

46 files changed

Lines changed: 1310 additions & 338 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎backend/AGENTS.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Backend Agent Guide
2+
3+
## Scope
4+
5+
These instructions apply to work under `backend/`. Preserve the dependency
6+
direction: routes and middleware call controllers; controllers call services;
7+
services own domain rules and call repositories or integrations; repositories
8+
own persistence queries. Services must not read Express `req` or write `res`.
9+
10+
## Commands
11+
12+
Run from `backend/`:
13+
14+
```sh
15+
npm run dev
16+
npm test
17+
npm test -- tests/api-videos.test.js
18+
```
19+
20+
The test runner is Node's built-in serial runner. API tests use MongoDB Memory
21+
Server by default. If `MONGODB_URI_TEST` is configured, tests drop that
22+
database; only use a disposable test database.
23+
24+
## Guardrails
25+
26+
- Never commit `.env`, credentials, tokens, service-account JSON, or production
27+
data. Environment variables are validated in `src/config/env.js`; update
28+
`.env.example` and `docs/SETUP.md` when adding configuration.
29+
- Keep Zod request validation in `src/middlewares/validators/` and business
30+
rules in services. Use shared response and `AppError` helpers.
31+
- Verify file contents from signatures, not supplied MIME types. Route uploads
32+
through the storage service and preserve cleanup for partially completed
33+
multi-file operations.
34+
- MongoDB stores domain records and opaque storage references; media bytes
35+
belong to configured storage drivers. Preserve visibility checks for
36+
metadata and media routes.
37+
- Redis is optional Upstash. Cache failures should be logged and fall back to
38+
the authoritative database/storage path. Keep cache values small and apply
39+
explicit TTLs.
40+
- Update `src/docs/openapi.js`, `docs/API.md`, tests, and relevant architecture
41+
docs when changing endpoints or behavior. Do not silently change append-only
42+
submission or account-data retention behavior.
43+
44+
## References
45+
46+
- [Backend docs index](docs/README.md)
47+
- [Setup and environment](docs/SETUP.md)
48+
- [API contract](docs/API.md)
49+
- [Architecture](docs/ARCHITECTURE.md)
50+
- [Module reference](docs/MODULE-REFERENCE.md)
51+
- [Design decisions](docs/design-docs/ARCHITECTURE-DECISIONS.md)
52+
- [Test-case inventory](docs/TEST-CASES.md)

‎backend/README.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -47,9 +47,10 @@ business rules.
4747
`src/services/initialization.js` initializes MongoDB, storage, and the configured
4848
admin idempotently; `server.js` is the standalone and Vercel entry point.
4949

50-
Read the full references: [API](docs/API.md),
51-
[architecture](docs/ARCHITECTURE.md), [setup](docs/SETUP.md), and
52-
[test-case inventory](docs/TEST-CASES.md).
50+
Read the [documentation index](docs/README.md), [API](docs/API.md),
51+
[architecture](docs/ARCHITECTURE.md), [module reference](docs/MODULE-REFERENCE.md),
52+
[setup](docs/SETUP.md), [design decisions](docs/design-docs/ARCHITECTURE-DECISIONS.md),
53+
and [test-case inventory](docs/TEST-CASES.md).
5354

5455
## Responses
5556

‎backend/docs/API.md‎

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,7 @@ All paths below are relative to `/api/v1`.
8282
| GET | `/videos/:id` | Public or admin | Read a visible video. |
8383
| GET | `/videos/:id/file` | Public or admin | Stream a visible video, including byte-range requests. |
8484
| GET | `/videos/:id/poster` | Public or admin | Stream a visible video's poster, if present. |
85-
| POST | `/videos` | Admin | Upload a reference video and optional poster. |
85+
| POST | `/videos` | Admin | Upload a reference video or register a direct HTTPS video URL; URL sources require a poster. |
8686
| PATCH | `/videos/:id` | Admin | Update a video, including status or category. |
8787
| DELETE | `/videos/:id` | Admin | Delete a reference video and its base files; submissions remain. |
8888
| 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
117117
client-supplied roles are ignored. Profile updates accept supported `connections`
118118
fields for GitHub and LinkedIn; `null` disconnects a connection.
119119

120-
The video and demo-video upload routes use `multipart/form-data`:
120+
The video and demo-video creation routes use `multipart/form-data`:
121121

122122
| Field | Video | Demo video |
123123
| --- | --- | --- |
124-
| `video` | Required video file | Required video file |
125-
| `poster` | Optional image file | Not accepted |
124+
| `video` | Optional video file; provide this or `videoUrl`, but not both | Required video file |
125+
| `videoUrl` | Optional direct HTTPS MP4/WebM URL; provide this or `video`, but not both | Not accepted |
126+
| `poster` | Optional for uploaded files; required with `videoUrl` | Not accepted |
126127
| `title` | Required title | Required title |
127128
| `categoryId` | Optional category ID | Not accepted |
128129
| `status` | Optional video status | Not accepted |
@@ -147,7 +148,15 @@ Uploads are bounded by `MAX_VIDEO_UPLOAD_MB` and
147148
`MAX_RECORDING_UPLOAD_MB` (defaults: 90 MB and 100 MB). Video signatures are
148149
checked as MP4, WebM, or MOV. Poster signatures are checked as JPEG, PNG, or WebP;
149150
posters must not exceed 2 MB. The browser-provided MIME type is not treated as
150-
proof of file content.
151+
proof of file content. External URLs must point directly to media playable in a
152+
native HTML `<video>` element; YouTube and other watch-page URLs are not
153+
supported. The URL is stored in MongoDB. Its poster image is stored through the
154+
configured `STORAGE_DRIVER` and streamed from the API.
155+
156+
Poster responses use a private five-minute browser cache. When Upstash Redis is
157+
configured, the backend also caches poster file metadata for five minutes; it
158+
does not cache poster image bytes. Redis errors are logged and fall back to
159+
reading metadata from the configured storage driver.
151160

152161
## Contact, rate limits, and access restrictions
153162

‎backend/docs/MODULE-REFERENCE.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Backend module reference
2+
3+
For system startup, request flow, and persistence details, see
4+
[ARCHITECTURE.md](ARCHITECTURE.md). This page maps common changes to their
5+
implementation layers.
6+
7+
| Concern | Primary modules | Notes |
8+
| --- | --- | --- |
9+
| App composition and startup | `server.js`, `src/app.js`, `src/services/initialization.js` | App composition is importable without binding a listener; initialization is shared and idempotent. |
10+
| Routes and access policy | `src/routes/`, `src/middlewares/authenticate.js`, `src/middlewares/requireRole.js` | Route definitions compose auth and validation middleware. |
11+
| Request validation | `src/middlewares/validators/`, `src/middlewares/validate.js` | Zod schemas validate bodies, params, and queries. |
12+
| HTTP response/error boundary | `src/controllers/`, `src/utils/response.js`, `src/middlewares/errorHandler.js` | Controllers adapt HTTP; services should throw `AppError` for expected failures. |
13+
| Domain behavior | `src/services/` | Enforce permissions, visibility, retention, cooldown, and multi-step workflows here. |
14+
| MongoDB persistence | `src/models/`, `src/repositories/` | Schemas define serialization/indexes; repositories encapsulate queries. |
15+
| Video library | `src/models/Video.js`, `src/services/videoService.js`, `src/routes/videoRoutes.js` | Supports stored uploads and direct HTTPS video URLs; posters are stored files. |
16+
| File storage | `src/services/storage/`, `src/utils/sendFile.js` | Local and Google Drive drivers; `sendFile` handles byte ranges and headers. |
17+
| Redis cache | `src/services/cache/upstashRedis.js`, feature service | Optional Upstash Redis REST client. Feature services own key naming, TTL, validation, and fallback logging. |
18+
| Authentication and consent | `src/services/authService.js`, `src/controllers/authController.js`, auth validators | Signup does not activate until the current consent is accepted. |
19+
| Submissions and archive | `src/services/submissionService.js`, `src/repositories/submissionRepo.js` | Submission records are append-only; archive storage is selected independently. |
20+
| API specification | `src/docs/openapi.js`, `docs/API.md` | Update both with route, schema, or response changes. |
21+
| Tests | `tests/*.test.js` | API-level suites plus focused service, filesystem, and utility suites. |
22+
23+
## Typical request path
24+
25+
```text
26+
route -> middleware -> controller -> service -> repository/model
27+
-> storage/provider integration
28+
```
29+
30+
Keep domain policy in services and persistence mechanics in repositories or
31+
storage drivers. Preserve error propagation and log provider/cache failures
32+
using the established logger.
33+
34+
## Validation checklist
35+
36+
For behavior changes, add focused tests at the service layer and API boundary
37+
where practical. Run the relevant test file, then `npm test` for broader
38+
changes. API and storage test setup is described in
39+
[SETUP.md](SETUP.md) and the [test-case inventory](TEST-CASES.md).

‎backend/docs/README.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Backend documentation
2+
3+
- [Setup](SETUP.md): local configuration, environment variables, and
4+
deployment.
5+
- [API](API.md): endpoint access, request/response behavior, and limits.
6+
- [Architecture](ARCHITECTURE.md): startup, request flow, persistence, storage,
7+
and security controls.
8+
- [Module reference](MODULE-REFERENCE.md): where to implement backend changes.
9+
- [Design decisions](design-docs/ARCHITECTURE-DECISIONS.md): current
10+
architecture choices and trade-offs.
11+
- [Test-case inventory](TEST-CASES.md): API and unit test coverage.
Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Backend architecture decisions
2+
3+
This is a record of current choices and their trade-offs, not a dated changelog.
4+
5+
## Keep HTTP, domain, and persistence responsibilities separate
6+
7+
**Decision:** Express routes compose middleware; controllers adapt HTTP inputs
8+
and responses; services enforce domain rules; repositories encapsulate
9+
MongoDB queries.
10+
11+
**Reason and trade-off:** The same business behavior can be tested without an
12+
HTTP request, and API response formatting stays at the boundary. New features
13+
must be threaded through several layers rather than placing all logic in a
14+
route handler.
15+
16+
**Implementation:** `src/routes/`, `src/controllers/`, `src/services/`, and
17+
`src/repositories/`.
18+
19+
## Store media bytes outside MongoDB
20+
21+
**Decision:** MongoDB stores metadata and opaque `{ driver, key }` file
22+
references. Local and Google Drive drivers provide file storage and streaming.
23+
Reference-video URLs may also be direct HTTPS media URLs; those URLs are stored
24+
as video metadata while their poster remains a stored file.
25+
26+
**Reason and trade-off:** Database documents remain small and storage can be
27+
switched or separated by intent. External URLs avoid copying video bytes but
28+
depend on the remote host's availability and browser media/CORS behavior.
29+
30+
**Implementation:** `src/models/Video.js`, `src/models/storedFile.js`,
31+
`src/services/storage/`, and `src/services/videoService.js`.
32+
33+
## Preserve byte-range media streaming
34+
35+
**Decision:** Stored video endpoints support HTTP Range requests; the storage
36+
driver exposes streams for requested byte ranges.
37+
38+
**Reason and trade-off:** Browsers use range access for seeking and native
39+
playback. Storage drivers must preserve inclusive range semantics, MIME type,
40+
and file size.
41+
42+
**Implementation:** `src/utils/sendFile.js` and
43+
`src/services/storage/`.
44+
45+
## Treat contributor submissions as append-only records
46+
47+
**Decision:** Accepted submission records and archived recording bytes are
48+
retained when an account or base video is deleted. A separate contact request
49+
allows the team to review recording/data deletion.
50+
51+
**Reason and trade-off:** Contribution history and released model provenance
52+
remain stable. This increases responsibility for retention and requires an
53+
explicit process for deletion requests.
54+
55+
**Implementation:** `src/services/submissionService.js`,
56+
`src/services/userService.js`, and `src/services/contactService.js`.
57+
58+
## Make external integrations optional and failure-tolerant where safe
59+
60+
**Decision:** Local file storage works without Google Drive; Redis caching is
61+
optional; transient cache failures fall back to authoritative reads. Cache
62+
values have explicit expirations and do not contain poster image bytes.
63+
64+
**Reason and trade-off:** Local development and core reads do not require every
65+
provider to be configured. Cache outages can increase storage/database work,
66+
but should not make cached data appear authoritative.
67+
68+
**Implementation:** `src/config/env.js`, `src/services/cache/upstashRedis.js`,
69+
`src/services/publicStatsService.js`, and `src/services/videoService.js`.
70+
71+
## Put access and validation at the server boundary
72+
73+
**Decision:** Route guards, authentication, Zod validation, role checks, file
74+
signature checks, rate limits, and origin checks are enforced server-side.
75+
Client-side restrictions improve UX but are not security controls.
76+
77+
**Reason and trade-off:** API callers are not limited to the first-party UI.
78+
Routes and services must retain visibility checks even when the client already
79+
filters data.
80+
81+
**Implementation:** `src/routes/`, `src/middlewares/`, and `src/services/`.

‎backend/docs/design-docs/README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Backend design documents
2+
3+
These documents record current architectural decisions and their trade-offs.
4+
They complement the [architecture guide](../ARCHITECTURE.md) and do not replace
5+
the implementation or API contract. Update a decision when the behavior or
6+
trade-off changes; do not infer undocumented history.
7+
8+
- [Architecture decisions](ARCHITECTURE-DECISIONS.md)

‎backend/package-lock.json‎

Lines changed: 2 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎backend/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "backend",
3-
"version": "1.0.4",
3+
"version": "1.0.5",
44
"description": "SignPakCommons API: Express, Node.js and MongoDB",
55
"main": "server.js",
66
"scripts": {

‎backend/src/controllers/videoController.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,5 +20,5 @@ export const videoController = {
2020
update: asyncHandler(async (req, res) => ok(res, await videoService.update(req.params.id, req.body))),
2121
remove: asyncHandler(async (req, res) => { await videoService.remove(req.params.id); noContent(res) }),
2222
file: asyncHandler(async (req, res) => sendFile(req, res, await videoService.getFile(req.params.id, req.user))),
23-
poster: asyncHandler(async (req, res) => sendFile(req, res, await videoService.getPoster(req.params.id, req.user))),
23+
poster: asyncHandler(async (req, res) => sendFile(req, res, await videoService.getPoster(req.params.id, req.user), { cache: 'private, max-age=300' })),
2424
}

0 commit comments

Comments
 (0)