|
| 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/`. |
0 commit comments