adb-files

Role

Document storage service: upload, download, deletion, and concatenation of files (mostly PDF). It combines AWS S3 for binaries and MongoDB for metadata (name, size, owner, tags, link to the business entity).

It is a leaf service: it never calls any other business service. Almost every other service that needs to store documents consumes it.

Tech stack

Internal Maven modules

• adb-files-model — exposed DTOs and entities.
• adb-files-app — runnable Spring Boot application.
• adb-files-client — Java client consumable by other services.

Internal architecture

flowchart TB
    Client[Client adb-*<br/>via FQDN.FILES]

    subgraph adb-files
        FC[FileController]
        FMC[FileMetadataController]
        FS[FileService]
        FMS[FileMetadataService]
        FF[FileFunction<br/>SQS Listener]
    end

    subgraph External
        Mongo[(adb-files<br/>files)]
        S3[(S3<br/>BUCKET_FILES)]
        SQS[SQS queue<br/>S3 upload trigger]
        SNS["SNS (DLQ router)"]
    end

    Client -->|POST /files| FC
    Client -->|GET /files/:id| FC
    Client -->|GET /files/metadata| FMC

    FC --> FS
    FMC --> FMS

    FS --> S3
    FS --> Mongo
    FMS --> Mongo

    S3 -.file uploaded.-> SQS
    SQS --> FF
    FF --> Mongo
    FF -.failed msg.-> SNS
    SNS -.routes to DLQ.-> SQS

Endpoints

Key endpoints

• POST /files — multipart upload (returns a fileId).
• GET /files/{id} — download.
• DELETE /files/{id} — S3 + metadata deletion.
• GET /files/pdf?ids=a,b,c — PDF concatenation of several files.
• GET /files/metadata/list?q=... — search by tag, owner, etc.
• GET /files/metadata/diagnostics?q=... — enriched metadata (used by adb-views).

Data model

erDiagram
    FileMetaDataEntity {
        string _id
        string s3Key
        string fileName
        string mimeType
        number size
        string ownerPersonId
        array tags
        date uploadedAt
    }

A single collection: files.

Events

Emitted

adb-files does not publish events directly — it has no Atlas trigger and no SNS publishing.

Consumed (SQS Listeners)

• onFileUploaded — triggered by an S3 event notification: when a file is written to BUCKET_FILES, S3 sends a message to the FILES_FILE_UPLOADED_QUEUE SQS queue. The FileFunction listener picks it up and updates the MongoDB metadata accordingly.

Dead-letter (SNS → SQS DLQ)

When a listener fails to process a message, the failed message is published to the FILES_DLQ_TOPIC SNS topic, which routes it to the files SQS DLQ.

Inter-service dependencies

flowchart LR
    files[adb-files]
    s3[(AWS S3)]

    files --> s3

    persons[adb-persons] -->|GET /files| files
    contracts[adb-contracts] -->|POST/GET/DELETE /files| files
    accounting[adb-accounting] -->|POST/GET /files| files
    aggregates[adb-aggregates] -->|GET /files/metadata/list| files
    views[adb-views] -->|GET /files/metadata/diagnostics| files
    reports[adb-reports] -.via aggregates.-> files

adb-files does not call any other business service (consumes no FQDN).

Configuration / deployment

Environment variables

Helm chart

Deprecated — Helm charts are no longer maintained. Infrastructure is managed via Pulumi (infra/).

adb-charts/charts/services/templates/adb-files.yaml. Image: lifeconnect/adb-files.

Links

• Code: adb-files/
• Functional docs: technical-epics/files/