Last updated 2026-06-01

adb-persons

AI-generated content

This document was generated by an AI assistant. Verify accuracy before relying on the details.

Role

Service responsible for every person handled by the platform: owners, tenants, suppliers, guarantees, etc. It also manages organizations (companies), user invitations, and Keycloak provisioning.

It is the only service that writes to Keycloak to create and update user accounts.

It also serves as the identity source for all other services: the /persons/me endpoint resolves the currently authenticated user from the JWT and returns their full person record. Every service that needs to identify the caller (accounting, contracts, views, etc.) calls this endpoint.

Tech stack

Item	Value
Spring Boot	3.1.3
Java	18
Port	8081
Database	MongoDB Atlas — database `adb-persons`
Auth	Keycloak (resource server + admin client)
Reactive stack	Spring WebFlux + Reactive MongoDB
Version	`0.29.0-SNAPSHOT`
Main class	`fr.lifeconnect.adb.person.AdbPersonApplication`

Depends on the shared modules: adb-common, adb-model, adb-messaging, adb-actions, adb-action-logs.

Internal architecture

flowchart TB
    subgraph Controllers
        PC[PersonController]
        OC[OrganizationController]
        TC[TenantController]
        IC[InvitationController]
        UC[UserController]
        CSC[CompanySettingsController]
    end

    subgraph Services
        PS[PersonService]
        OS[OrganizationService]
        IS[InvitationService]
        US[UserService]
    end

    subgraph External
        Mongo[(adb-persons<br/>Mongo)]
        KC[Keycloak Admin API]
        AtlasTrigger[Atlas Trigger]
        EB[EventBridge]
        SQS[SQS queues]
        Files[adb-files]
    end

    PC --> PS
    OC --> OS
    TC --> PS
    IC --> IS
    UC --> US

    PS --> Mongo
    OS --> Mongo
    IS --> Mongo
    US -->|admin credentials| KC

    PS -.HTTP.-> Files
    Mongo -.entity change.-> AtlasTrigger
    AtlasTrigger -.-> EB
    EB -.-> SQS

Endpoints

Controller	Base path	Role
`PersonController`	`/persons`	Person CRUD + `/persons/me`
`OrganizationController`	`/persons/organizations`	Organization CRUD
`TenantController`	`/persons/tenants`	Tenant management
`InvitationController`	`/persons/invitations`	User invitations
`UserController`	`/persons/{personId}/users`	Keycloak user accounts
`CompanySettingsController`	`/persons/companySettings`	Company settings
`ErrorDebugController`	`/persons/errors`	Debug

OpenAPI / Swagger available at /persons/api-docs.

Data model

erDiagram
    PersonEntity ||--o{ OrganizationEntity : "belongs to"
    PersonEntity ||--o{ InvitationEntity : "receives"
    PersonEntity ||--o{ DelegationEntity : "delegator / delegatee"
    OrganizationEntity ||--|| CompanySettingEntity : "configures"

    PersonEntity {
        string _id
        string firstName
        string lastName
        string email
        string type "natural / legal / unknown"
        string organizationId
    }
    OrganizationEntity {
        string _id
        string name
        string vatNumber
    }
    InvitationEntity {
        string _id
        string personId
        string status
        date expiresAt
    }
    CompanySettingEntity {
        string _id
        string organizationId
        object settings
    }
    DelegationEntity {
        string _id
        TargetObject delegatedResource
        TargetObject delegator
        TargetObject delegatee
        Set~String~ delegatedScopes
        date startDate
        date endDate
    }

Collection	Entity
`persons`	`PersonEntity`
`organization`	`OrganizationEntity`
`invitations`	`InvitationEntity`
`company_settings`	`CompanySettingEntity`
`delegations`	`DelegationEntity`

Delegation

DelegationAdapterPersonImpl implements the DelegationPort interface (from adb-security) and persists delegation records in the delegations collection. A delegation links a delegator (e.g. an owner) to a delegatee (e.g. a manager), scoped to a specific resource and a set of delegatedScopes, optionally bounded by startDate / endDate.

The adapter is consumed by security infrastructure to resolve effective permissions for a principal acting on behalf of another — it is not exposed directly via an HTTP controller in this service.

Events

Emitted (MongoDB Atlas Trigger → EventBridge → SQS)

Events are not published by the Spring service directly. MongoDB Atlas triggers fire on entity changes and push notifications through AWS EventBridge, which delivers them to the relevant SQS queues:

onPersonModified — fired when a persons document is written
onOrganizationModified — fired when an organization document is written

Consumed by adb-contracts, adb-accounting, adb-views.

Consumed

No SQS listeners — adb-persons is purely an event producer.

Dead-letter

No SNS usage — no SQS consumers means no DLQ producer.

Inter-service dependencies

flowchart LR
    persons[adb-persons]
    files[adb-files]
    keycloak[Keycloak]

    persons -->|GET /files/...| files
    persons -->|admin API<br/>user creation| keycloak

    contracts[adb-contracts] -->|GET /persons| persons
    parts[adb-parts] -->|GET /persons| persons
    accounting[adb-accounting] -->|GET /persons| persons
    aggregates[adb-aggregates] -->|GET /persons| persons
    views[adb-views] -->|GET /persons| persons
    web[adb-web/bff] --> persons
    ui[adb-ui] --> persons

Configuration / deployment

Environment variables

Variable	Role
`MONGO_DB_URI`	MongoDB connection string
`SECURITY_ISSUER_URI`	Keycloak issuer (JWT validation)
`SECURITY_TOKEN_URI`	Token endpoint (Client Credentials)
`CLIENT_ID` / `CLIENT_SECRET`	Service credentials
`ADMIN_CLIENT_ID` / `ADMIN_CLIENT_SECRET`	Keycloak admin credentials (user creation)
`INVITATION_URI`	Invitation URL sent by email

Helm chart

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

adb-charts/charts/services/templates/adb-persons.yaml — deploys a Kubernetes Deployment + Service. Docker image: lifeconnect/adb-persons.

CI/CD pipeline

Bitbucket Pipelines (legacy) — migration to GitHub Actions is ongoing as part of the move to a monorepo.