---
id: SVC-PFM-MTD-files
title: Files Service Module
product_area: platform
module: metadata
repository: services-platform
source_module: modules/files
revision: 1
status: draft
design_intent: confirmed
origin: PLAT-M10 plan approved by Andrew 2026-10-19 with D1 to D4 (services-platform:docs/milestones/PLAT-M10-image-and-file-fields.md,
  In Progress); R2-ARCH-002 v2.0 (Andrew, 2026-10-22) for the publication column
implementation_evidence: partially-observed
inference: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
owns: []
does_not_own:
- Each record owner’s asset binding owns permanent content and lifecycle.
- The referenced uploads bucket remains outside this module’s provisioning.
- Metadata owns property definitions; upload issuance is an attachment facet.
operations:
- operation_id: getFilesHealth
  intent: Return the Files build identity and health response.
  access: public
  permission: 'none: the shared health route, named explicitly'
  realises:
  - CAP-PFM-MTD-007
  published_to_submissions: 'not published: Operational health checks have no intake binding.'
- operation_id: issueFileUpload
  intent: Authorize and record short-lived staging for a declared attachment, then return its signed upload contract.
  access: console
  permission: platform.files.upload
  realises:
  - CAP-PFM-MTD-007
  published_to_submissions: 'not published: This staff maintenance operation has no Submissions binding.'
events: []
jobs: []
integrations:
- system: Upload storage (Rhythm 1.0's uploads bucket)
  direction: outbound
  contract: Storage receives PUT requests with signed type, byte count and uploader/issue metadata under a temporary
    key.
- system: Owning saves' asset pipeline
  direction: outbound
  contract: The asset pipeline reads the staging uploader and compares it with the saving caller.
consistency:
- rule: Upload issuance and its audit commit together, with invalid declarations rejected before signing.
  kind: transactional
  compensation: No reversal is needed when no issue was committed.
- rule: The owning save controls whether staged content becomes permanent record content.
  kind: eventual
  compensation: Storage retention removes unused temporary files; no pruning removes their issue rows.
evidence:
- 'services-platform at ad3f6a65: modules/files/aws/api/files.routes.ts, files.schemas.ts; services/uploads/**;
  services/persistence/file-uploads.ts; db/file-uploads.table.ts; files.settings.ts; aws/resources/files-storage.s3.ts;
  aws/platform.service.ts (FILES_PERMISSIONS); docs/files.md; docs/assets.md'
controls: [TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003]
---

# Files Service Module

## What This Service Is For

Files authorizes a declared attachment and provides a signed staging location before the record save. Issuance records who received the location and the declared content contract.

## Boundary

The record owner’s asset binding checks bytes and prepares permanent copies. Files owns issuance persistence but no separate broad domain concept, and it references the existing uploads bucket.

## Operations in Words

Staff with upload reach can obtain staging. The health read is public; neither operation has a Submissions binding. Possession of a signed address permits upload with its bound headers, and save-time checks enforce uploader matching.

## Consistency Guarantees

Issuance and its audit commit together. Direct upload and later record saving are separate steps connected by a staged reference; unused issue rows remain stored.