adb-utilities

Role

Cross-cutting services consumed by every other microservice. It provides:

• Catalogs and translations (/utilities/catalog, /utilities/i18n) — multilingual reference tables.
• Business configuration (/utilities/configurations) — formats, sequences, charges, parameters.
• Allocation keys (/utilities/allocationkey) — rules to allocate charges across lots.
• INSEE indices (/utilities/indexes) — IRL, ILC, ILAT, ICC indices for rent revisions, refreshed daily at noon by a cron job.
• Notifications (/utilities/notifications, /utilities/notification-definitions) — the admin banners: an administrator defines a notification (notification_definitions), its activation fans out one organisation-level instance per target organisation (notifications), and each user's copy is materialised when they read /utilities/notifications/assigned. See Notification fan-out.
• UI logs (/utilities/logs) — collects client-side logs.
• Dashboards (/utilities/dashboards) — user dashboard configuration.
• Validations (/utilities/validations) — reusable business validation rules.

Tech stack

Internal architecture

flowchart TB
    subgraph Controllers["12 Controllers"]
        CC[CatalogController]
        I18N[I18NController]
        CFC[ConfigurationController]
        AKC[AllocationKeysController]
        IC[IndexController]
        NC[NotificationController]
        NDC[NotificationDefinitionController]
        DC[DashboardController]
        VC[ValidationsController]
        SC[SerialController]
        ULC[UiLogsController]
        INFOC[InfoController]
    end

    subgraph Jobs
        InseeJob[INSEE Job<br/>cron: 0 0 12 * * *]
    end

    Mongo[(adb-utilities)]
    INSEE[INSEE API]

    Controllers --> Mongo
    InseeJob --> INSEE
    InseeJob --> Mongo
    InseeJob -.publish.-> SNS[SNS<br/>onIndexPublished]

Endpoints (12 controllers)

Data model

erDiagram
    AllocationKeyEntity ||--o{ Configuration : "references"

    AllocationKeyEntity {
        string _id
        string name
        object rules
    }
    AbstractConfigurationEntity {
        string _id
        string type "format / serial / charge / ..."
        object data
    }
    CatalogValueEntity {
        string _id
        string catalog
        string code
        object translations
    }
    InseeIndexEntity {
        string _id
        string bankId "IRL / ILC / ILAT / ICC"
        date publishedAt
        number value
    }
    NotificationDefinitionEntity {
        string _id
        string type
        string template
    }
    NotificationEntity {
        string _id
        ObjectId definitionId
        TargetObject organisation
        TargetObject user
        object schedule
        string notificationType
        string payload
        boolean acknowledgeable
        string state
    }

Collections: allocationkeys, configurations, dashboards, catalog, indexes, notifications, notification_definitions, serials.

Events

Emitted (SNS)

• onIndexPublished — when the INSEE job publishes a new index (consumed by adb-contracts to re-index rents).

Consumed

No SQS listener — adb-utilities is purely a producer or read-only.

Notification fan-out (banners)

Two collections, three steps:

Visibility is gated at read time on schedule.start <= now < schedule.end, so a definition scheduled in the future is materialised at activation and surfaces at its start; deactivating, updating or deleting the definition removes every instance (broadcasts and per-user copies alike). The SPA (adb-ui banner.service.ts) reads /assigned on load and PATCHes each copy to RECEIVED, then ACKNOWLEDGED when dismissed.

History. Until 2026-09 step 2 did not exist in the service: it was performed by two hand-managed Atlas triggers of the triggers-kkeqz app (notification-definition-modified → a TTL document in notifications_ttl → notification-ttl-deleted → insertMany into notifications, see Atlas Triggers). Those exist on one cluster only, so on staging, on the local stack and in the Cloudflare port an activated banner never reached anyone (measured on staging 0.68.0 and on the local stack, 2026-09-23). The property notifications.fan-out.enabled (env NOTIFICATIONS_FANOUT_ENABLED, default true) exists for the cutover: it must be false only where the two triggers are still enabled, otherwise every banner is produced twice. The Cloudflare port (services/utilities, src/notificationDefinitions.mjs) mirrors the same write paths.

Inter-service dependencies

flowchart LR
    utilities[adb-utilities]
    insee[INSEE API]

    utilities --> insee

    parts[adb-parts] -->|GET /utilities/allocationkey| utilities
    contracts[adb-contracts] -->|GET /utilities/i18n| utilities
    accounting[adb-accounting] -->|GET /utilities/i18n| utilities
    web[adb-web/bff] --> utilities
    ui[adb-ui] --> utilities

adb-utilities does not call any other business service.

Seeding / pipeline scripts

The pipeline_scripts/ directory contains shell scripts for bootstrapping configuration data into a target environment. They read TSV files from the module root and POST documents directly to MongoDB via mongosh.

Translation TSV files present in the repo root (ACCOUNTING-values-input.tsv, ADMIN-values-input.tsv, CATALOG-values-input.tsv, COMMON-values-input.tsv, CONTRACTS-values-input.tsv, DOCUMENTS-values-input.tsv, JEDI-values-input.tsv, LISTS-values-input.tsv, NACE-values-input.tsv, NOTES-values-input.tsv, PARTS-values-input.tsv, PERSONS-values-input.tsv, SEARCH-values-input.tsv, TICKET-values-input.tsv) represent one domain per file; each row is a translation entry (key, locale, value).

INSEE Job

A Spring job (cron 0 0 12 * * * — every day at noon) that:

1. Calls the INSEE API with the credentials insee.consumer.key / insee.consumer.secret.
2. Fetches the IRL, ILC, ILAT, ICC indices.
3. Persists them in the indexes collection.
4. Publishes the onIndexPublished event to SNS.

Can be disabled via insee.job.enabled=false.

Configuration / deployment

Environment variables

Helm chart

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

Links

• Code: adb-utilities/
• Allocation keys docs: functional-epics/utility/allocation-keys.md
• Revision index docs: functional-epics/utility/revision-index.md