Life ConnectLife Connect
Table of contents
Architecture
Services
Swagger Docs
GitHub
Table of contents
Architecture
Services
Swagger Docs
GitHub
  • Backend (Java / Spring Boot)

    • adb (parent Maven + proxy)
    • adb-persons
    • adb-parts
    • adb-contracts
    • adb-accounting
    • adb-files
    • adb-utilities
    • adb-aggregates
    • adb-views
    • adb-reports
  • Frontend

    • adb-ui
    • adb-web
  • Infrastructure & Outillage

    • adb-charts
    • adb-infrastructure
    • adb-tests-artillery
    • adb-doc
  • Services externes (hors monorepo)

    • adb-tickets (externe)
    • adb-notes (déprécié)
    • adb-graph (externe, statut incomplet)

adb-contracts

Rôle

Service de gestion du cycle de vie des contrats liés à un bien : bail (rental contract), bail délégué (rental delegate), assurance, garantie, mandat SEPA, prélèvement automatique. Très riche fonctionnellement, il combine :

  • des machines d'états Spring Statemachine pour piloter les transitions (DRAFT → ACTIVE → TERMINATED, etc.),
  • la génération de documents (PDF via FreeMarker + html2pdf),
  • la gestion du dunning (relances impayés),
  • la création de mandats SEPA ISO20022 (PAIN.008),
  • des événements vers adb-accounting pour déclencher la création de factures (call-for-rent).

Stack

ÉlémentValeur
Spring Boot3.1.3
Java18
Port8084
DatabaseMongoDB Atlas — base adb-contracts
AuthKeycloak (resource server)
Stack réactiveSpring WebFlux + Reactive MongoDB
State machinesSpring Statemachine 2.2.3
PDFhtml2pdf 4.0.2 + iTextPDF
TemplatingFreeMarker
StockageAWS S3 (templates), AWS SQS/SNS (events)
Version0.48.0-SNAPSHOT
Main classfr.lifeconnect.adb.contract.AdbContractApplication

Architecture interne

flowchart TB
    subgraph Controllers["15 Controllers"]
        CC[ContractController]
        BCC[BankContractController]
        ICC[InsuranceContractController]
        GCC[GuaranteeContractController]
        RACC[RentalAllowanceContractController]
        SMCC[SepaMandateContractController]
        DDC[DirectDebitController]
        DC[DocumentController]
        DnC[DunningController]
        CEC[ContractEventsController]
        CACC[ContractAccountingController]
        CPC[ContractPersonsController]
        CPaC[ContractPartsController]
        TVC[TemplateValuesController]
    end

    subgraph StateMachines
        RCSM[RentalContractStateMachine]
        RDSM[RentalDelegateStateMachine]
        SMM[StateMachineManager]
    end

    subgraph Listeners["SQS Listeners"]
        L1[PartFunction → onPartModified]
        L2[PersonFunction → onPersonModified]
        L3[FileFunction → onFileMetaDataModified]
        L4[IndexFunction → onIndexPublished]
        L5[ContractFunction]
        L6[AccountingFunction]
        L7[DunningFunction]
    end

    Mongo[(adb-contracts)]
    S3[(S3 templates)]
    SNS[SNS topics]

    Controllers --> StateMachines
    Controllers --> Mongo
    DC --> S3
    Listeners --> Mongo
    StateMachines -.publish.-> SNS

Endpoints (15 controllers)

ControllerPathRôle
ContractController/contractsCRUD contrats génériques
BankContractController/contracts/banksComptes bancaires liés aux contrats
InsuranceContractController/contracts/insurancesContrats d'assurance
GuaranteeContractController/contracts/guaranteeContrats de garantie
RentalAllowanceContractController/contracts/rental-allowancesAllocations logement
SepaMandateContractController/contracts/sepa-mandatesMandats SEPA
DirectDebitController/contracts/direct-debitPrélèvements automatiques
DocumentController/contracts/documentsDocuments (PDF) liés aux contrats
DunningController/contracts/dunningsRelances impayés
ContractEventsController/contractsÉvénements de contrat (call-for-rent…)
ContractAccountingController/contractsVue comptable d'un contrat
ContractPersonsController/contractsPersonnes liées au contrat
ContractPartsController/contracts/partsParts liées au contrat
TemplateValuesController–Valeurs injectées dans les templates
ErrorDebugController/contracts/errorsDebug

Modèle de données

erDiagram
    ContractEntity ||--o{ ContractPartEntry : "couvre"
    ContractEntity ||--|| DirectDebitEntity : "prélèvement"
    ContractEntity ||--o{ TemplateValuesEntity : "génère"
    ContractEntity ||--o{ ProposeContractEntity : "draft de"

    ContractEntity {
        string _id
        string type "rental / insurance / guarantee / sepa"
        string state "DRAFT / ACTIVE / TERMINATED"
        date startDate
        date endDate
        array partIds
        array personIds
    }
    DirectDebitEntity {
        string _id
        string contractId
        string mandateId
        number amount
    }
    TemplateValuesEntity {
        string _id
        string contractId
        object values
    }
    ProposeContractEntity {
        string _id
        string contractId
        object proposal
    }

Collections : contracts, propose_contracts, direct_debits, template_values.

Machines d'états

Deux machines principales :

  • RentalContractStateMachine — pilote le cycle de vie d'un bail standard.
  • RentalDelegateContractStateMachine — bail délégué (gestion locative).

Pool size : 1000 (config state-machine.pool.size).

États typiques : DRAFT, PROPOSED, SIGNED, ACTIVE, TERMINATED, CANCELLED. Événements : UPDATE, SIGN, CANCEL, TERMINATE, RENEW.

Événements

Émis (SNS)

  • onContractModified
  • onContractUpdated
  • onDirectDebitProcessed
  • dunningNoticeSent

Consommés (SQS Listeners)

  • onPartModified (depuis adb-parts)
  • onPersonModified (depuis adb-persons)
  • onFileMetaDataModified (depuis adb-files)
  • onIndexPublished (depuis adb-utilities) → ré-indexation des loyers
  • onAccountingEventModified (depuis adb-accounting)
  • dunningNoticeSent (auto-listening pour orchestration)
  • ContractsAuxiliaryAccountBalanceUpdated

Dépendances inter-services

flowchart LR
    contracts[adb-contracts]
    persons[adb-persons]
    parts[adb-parts]
    files[adb-files]
    accounting[adb-accounting]
    utilities[adb-utilities]

    contracts -->|GET /persons| persons
    contracts -->|GET /parts| parts
    contracts -->|GET /files,<br/>POST /files| files
    contracts -->|GET /accounting/balances,<br/>POST /accounting/entries| accounting
    contracts -->|GET /utilities/i18n| utilities

    parts2[adb-parts] -->|GET /contracts/sellPart| contracts
    accounting2[adb-accounting] -->|GET /contracts| contracts
    aggregates[adb-aggregates] -->|GET /contracts| contracts
    views[adb-views] -->|GET /contracts| contracts
    reports[adb-reports] -.via aggregates.-> contracts

Intégrations externes

  • AWS S3 (BUCKET_TEMPLATES) : stockage des templates FreeMarker pour les PDF.
  • AWS SQS/SNS : nombreuses queues ${CONTRACTS_*_QUEUE} (région eu-west-1).
  • Twilio SendGrid : envoi d'emails (mandats SEPA, dunning) — TWILIO_SENDGRID_API_KEY.
  • JAXB + ISO20022 : sérialisation XML des fichiers PAIN.008 pour les banques.
  • html2pdf : conversion HTML → PDF pour les contrats signés.

Configuration & déploiement

Variables d'environnement clés

VariableRôle
MONGO_DB_URIConnection string MongoDB
SECURITY_ISSUER_URI / SECURITY_TOKEN_URIKeycloak
CLIENT_ID / CLIENT_SECRETOAuth2
AWS_REGION / AWS_ACCESS_KEY / AWS_SECRET_KEYAWS
BUCKET_TEMPLATESBucket S3 des templates
CONTRACTS_*_QUEUEURLs des queues SQS consommées
TWILIO_SENDGRID_API_KEYEnvoi d'emails

Chart Helm

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

Liens

  • Code : adb-contracts/
  • State machine config : adb-contracts/src/main/java/fr/lifeconnect/adb/contract/
  • Doc fonctionnelle : technical-epics/contracts/
Edit this page
Last Updated:
Contributors: gregory
Prev
adb-parts
Next
adb-accounting