Skip to main content

medOS File Storage

Internal scope: ever-filestore  ·  Port: 8083  ·  File upload/download with pluggable IPFS or S3 backends and content-hash verification.

The File Storage service owns binary object handling for the whole platform — uploads, downloads, and the indirection layer that lets a deployment choose where blobs actually live. The same upload API works whether the configured backend is AWS S3 (managed cloud) or IPFS / IPFS Cluster (decentralized and on-premise). Every object is addressed by a content hash, so callers store and retrieve a stable identifier rather than a backend-specific path, and integrity can be re-verified on read.

8083
Default port
2
Pluggable backends
IPFS
Content-addressed
JWT
Access control

Responsibilities​

  • Upload & download — accept single and multi-file uploads, stream files back on request, and serve both authenticated and designated public read paths.
  • Backend abstraction — route storage operations to S3 or IPFS based on the FILESTORE_BACKEND configuration, keeping the caller-facing contract identical.
  • Content-hash addressing — return a content hash as the canonical file id, so retrieval and integrity verification key off the content itself.
  • IPFS lifecycle — pin and unpin content, query node/cluster version, and resolve metadata by hash against both a local node and an IPFS Cluster.
  • Document upload helper — a higher-level document-upload path that wraps a raw file store and returns the resulting file id.
  • Access control — JWT strategy, token guard, and an auth service that gate non-public file operations.
  • Cache hygiene — service-event mixins that listen for clean-up signals and evict stale cached file entries.

Major modules​

ModulePurpose
modules/s3AWS S3 backend — s3.service.ts for object operations plus s3.config.ts for bucket/region configuration.
modules/ipfsIPFS backend — service, repository, controller mixin, and DTOs covering upload, get-file, pin add/remove, info-by-hash, and the IPFS Cluster equivalents.
modules/authAccess control — JWT strategy, token guard, and auth service/controller protecting file routes.
serviceEventsCache-clean mixins (fileStore.cache.clean and fileStoreCacheCleanEvents) that react to platform events and invalidate cached entries.
filestoreService.tsService entry point binding the modules into the Moleculer/NestJS runtime.

Backend selection & configuration​

The active backend is chosen at deploy time. Storage code paths are otherwise identical, which is what lets the cloud and on-premise topologies share one image.

FILESTORE_BACKENDSERVICE_FILESTORE_PORTIPFS_HOSTIPFS_PORTIPFS_PROTOCOLIPFS_CLUSTER_HOSTIPFS_CLUSTER_PORTIPFS_CLUSTER_PROTOCOL
Config flagPurpose
FILESTORE_BACKENDSelects the active backend (S3 vs. IPFS).
SERVICE_FILESTORE_PORTService listen port (defaults to 8083).
IPFS_HOST / IPFS_PORT / IPFS_PROTOCOLConnection details for the local IPFS node.
IPFS_CLUSTER_HOST / IPFS_CLUSTER_PORT / IPFS_CLUSTER_PROTOCOLConnection details for the IPFS Cluster (replicated pinning).

All connection values are environment-parameterized — no backend endpoint is hardcoded — so the same build runs against managed cloud storage or a self-hosted IPFS fabric.

Upload & retrieval flow​

  Caller (service / frontend)
        │  upload file(s)
        ▼
  ┌────────────────────────────┐
  │      ever-filestore        │
  │  ┌──────────────────────┐  │
  │  │  JWT guard / auth     │  │   non-public routes
  │  └──────────┬───────────┘  │
  │             ▼              │
  │   FILESTORE_BACKEND ?      │
  │     ┌───────┴───────┐      │
  │     ▼               ▼      │
  │  ┌─────┐        ┌────────┐ │
  │  │ S3  │        │  IPFS  │ │  pin → (IPFS Cluster)
  │  └──┬──┘        └───┬────┘ │
  └─────┼───────────────┼──────┘
        │   content hash returned as fileId
        ▼               ▼
   stored object   addressable by hash
        │
        ▼
  Caller stores fileId → later get-file / get-public-file by hash

On retrieval the service resolves the object by its hash and streams it back with the stored content type; because the id is the content hash, the same identifier doubles as the integrity check. A separate public-file path serves designated content without an auth token, while all other operations pass through the JWT guard.

Integration notes​

  • Other backend services (for example clinical, diagnostic, and printing flows) store and reference documents by the file id this service returns, keeping blobs out of the primary databases.
  • The IPFS path makes File Storage the natural data plane for immutable, content-addressed artifacts in on-premise and edge deployments; secrets and live state are handled elsewhere.
S3 backendIPFS node + ClusterJWT access controlContent-hash verification
  • SYS-7 — File Storage (S3)
  • INT-12 — IPFS Document Storage
  • ST-8 — File Storage Encryption

See also​