Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

01 — Product Overview (Files Module)

Source of truth: src/modules/files/ (implemented), src/shared/storage/storage-provider.ts, src/infrastructure/storage/, studylyon-blueprint/02-Architecture/STORAGE_ARCHITECTURE.md (planned direction). Shared conventions: 00-shared/01_Product_Overview, 00-shared/07_API_Conventions.

1. What it is

The Files module is the platform's object-storage gateway: upload, list, download, and delete binary files (documents, images, exports) while keeping all business logic provider-agnostic. Storage is behind a single StorageProvider interface; the active driver is chosen by STORAGE_DRIVER at boot (src/infrastructure/storage/storage.module.ts:11-22).

2. Scope

In scope (implemented)Not in scope (gaps, tracked below)
Single-file multipart uploadThumbnail generation (schema fields only)
Metadata persistence (filename, mimeType, size, storageKey)Signed-URL download path (provider methods exist, unused by service)
Buffered download + delete (storage + metadata)Pagination / search / filters on list
Tenant-scoped CRUD via BaseRepositoryFile sharing, versioning, folders UI
RBAC-permission decorators on all routesStreaming / Range requests (whole file buffered in RAM)

3. PRD native-app exclusion (flagged)

00-shared/12_Assumptions_&_Open_Questions.md:12 — the PRD (PRODUCT_REQUIREMENTS_DOCUMENT.md:144) puts native mobile apps out of Phase 1; roadmap Phase 3 is a read-only companion. These specs follow the house convention: a full client is specified (forward-looking), so all Flutter-facing docs in this folder describe screens the backend endpoints already support. All analytics are (proposed); push/QR affordances are (forward-looking); anything not yet implemented server-side is (planned).

4. Key facts (from source)

  • Routes: POST /api/v1/files/upload, GET /api/v1/files, GET /api/v1/files/:id, GET /api/v1/files/:id/download, DELETE /api/v1/files/:id (files.controller.ts:29-71).
  • Permissions: file.read, file.upload, file.delete (src/modules/rbac/permissions.constants.ts:86-88). No file.update / file.share.
  • Every record is tenant-scoped via TenantContextService.requireTenantId() (files.service.ts:28) and soft-delete filtered by BaseRepository (repositories/file.repository.ts:9-15).
  • Storage key convention: R2 uses <tenantId>/<uuid>--<originalName> (r2.provider.ts:39); local disk uses storage/<tenantId>/<uuid>--<originalName> (local-storage.provider.ts:24-27); blueprint recommends sl/{tenantId}/{type}/{uuid} (STORAGE_ARCHITECTURE.md:34, (planned) alignment).
  • No size limit, no MIME allowlist, no TTL/expiry anywhere in code. Upload accepts any buffer Multer accepts; mimetype is client-supplied (files.service.ts:32-33).
  • Delete = storage object delete + metadata soft-delete (files.service.ts:66-70).

5. Goals

  1. Reliable attach/download of school documents from any module screen.
  2. Tenant isolation by construction (repository scoping + provider key prefix).
  3. Provider swap without module changes (DI token STORAGE_PROVIDER, storage-provider.ts:2).

6. Non-goals (ponytail)

  • No folders/buckets UI, no preview generation, no dedupe, no virus scan (add when a module demands them). Thumbnails/etag fields exist in schema (file.schema.ts:27-43) but are never populated — (forward-looking).

7. Planned roadmap (from docs/IMPLEMENTATION_PLAN.md)

  • R2 provider hardening incl. R2_PUBLIC_URL config (Phase 1.1, IMPLEMENTATION_PLAN.md:32; R2_PUBLIC_URL absent from src/config/env.ts today) (planned).
  • Data retention / soft-delete cleanup jobs — 3-day tier noted globally (IMPLEMENTATION_PLAN.md:176) (planned).
  • Signed-URL download and TTL cleanup (STORAGE_ARCHITECTURE.md:44,66) (planned).