adb-accounting

Role

Full-featured accounting service: invoices, payments, journals, accounting entries, auxiliary accounts (customers/suppliers), fiscal years, CRG reports (Recoverable Charges / Guarantees), housing allowances.

It is the largest service in the backend (17 controllers, 23+ collections) and one of the heaviest event consumers: it reacts to changes in contracts, persons, and payments to automatically generate the corresponding accounting entries.

Tech stack

Internal architecture

flowchart TB
    subgraph Controllers["17 Controllers"]
        IC[InvoiceController]
        PC[PaymentController]
        IPC[InvoicePaymentController]
        BC[BalanceController]
        TC[TransactionController]
        AEC[AccountingEntriesController]
        AVC[AccountingEventController]
        JC[JournalController]
        LAC[LedgerAccountController]
        LAUX[LedgerAuxiliaryAccountController]
        FYC[FiscalYearController]
        CRGC[CRGController]
        DC[DocumentController]
        SC[SettlementController]
        RASC[RentalAllowanceStatementController]
        AMI[AccountingModuleInfoController]
        OIC[ObjectIdController]
    end

    subgraph SM[State Machines]
        ISM[InvoiceStateMachine]
        PSC[payment/StateMachineCreator]
    end

    subgraph Listeners[SQS Listeners]
        L1[AccountingFunctions]
        L2[PersonsFunctions]
        L3[PaymentFunctions]
        L4[ContractsFunctions]
    end

    subgraph External
        Mongo[(adb-accounting)]
        S3[(S3 templates)]
        GS[Google Sheets/Drive]
        AtlasTrigger[Atlas Trigger]
        EB[EventBridge]
        SQS[SQS queues]
        SNS["SNS (DLQ router)"]
    end

    Controllers --> SM
    Controllers --> Mongo
    Listeners --> Mongo
    Controllers --> GS
    Controllers --> S3
    Mongo -.entity change.-> AtlasTrigger
    AtlasTrigger -.-> EB
    EB -.-> SQS
    Listeners -.failed msg.-> SNS
    SNS -.routes to DLQ.-> SQS

Endpoints (17 controllers)

Data model (excerpt)

erDiagram
    InvoiceEntity ||--o{ AccountingEntry : "generates"
    PaymentEntity ||--o{ AccountingEntry : "generates"
    JournalEntity ||--o{ AccountingEntry : "groups"
    LedgerAccountEntity ||--o{ AccountingEntry : "posted to"
    FiscalYearEntity ||--o{ AccountingEntry : "period"
    AccountingEventEntity ||--o{ InvoiceEntity : "triggers"
    AccountingEventEntity ||--o{ PaymentEntity : "triggers"

    InvoiceEntity {
        string _id
        string contractId
        string state
        number amount
        date dueDate
    }
    PaymentEntity {
        string _id
        string state
        number amount
        date paymentDate
    }
    AccountingEntry {
        string _id
        string journalId
        string ledgerAccountId
        number debit
        number credit
        date date
    }
    AccountingEventEntity {
        string _id
        string type "call-for-rent / payment-received / ..."
        date timestamp
        object payload
    }

23+ collections, the main ones being: invoices, payments, accounting_entries, accounting_events, journals, ledger_account, ledger_account_definition, ledger_auxiliary_accounts, fiscal_year, rental_allowance_statements, tenant_rental_allowances, serial, accounting_sequence, transaction_reads, configurations, resume_token, accounting_event_fallback.

State machines

Both state machines implement the reactive StateMachineCreator<S, E> interface (statemachine/StateMachineCreator.java), which wraps Spring Statemachine in a Project Reactor pipeline (Mono/Flux) and exposes withStateMachine, sendTransition, and allowedTransitions.

• Invoice (statemachine/InvoiceStateMachine) — invoice lifecycle (PARKED → BOOKED → DELETED). Strategies: ProcessInvoiceStateMachineStrategy, ProposeInvoiceStateMachineStrategy. Actions live under statemachine/invoice/actions/.
• Payment (statemachine/payment/) — payment lifecycle (PARKED → BOOKED → REVERSED → ARCHIVED). Reactive actions under statemachine/payment/actions/ (BookPaymentAction, ProposePaymentAction, AbstractProcessPaymentAction, UnsupportedOperationAction).

Events

Emitted (MongoDB Atlas Trigger → EventBridge → SQS)

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

• onAccountingEntryModified — fired when an accounting_entries document is written
• onAccountingEventModified — fired when an accounting_events document is written
• onPaymentModified — fired when a payments document is written

Dead-letter (SNS → SQS DLQ)

SNS is not used for normal event publishing. When a listener fails to process a message, the failed message is published to the ACCOUNTING_DLQ_TOPIC SNS topic, which routes it to the accounting SQS DLQ. No other SNS publishing occurs in this service.

Consumed (SQS Listeners)

• onPersonModified (from adb-persons)
• onOrganizationModified (from adb-persons)
• onContractModified (from adb-contracts) → triggers call-for-rent
• onDirectDebitProcessed (from adb-contracts)
• Self-listening: onAccountingEntryModified, onAccountingEventModified, onPaymentModified

Inter-service dependencies

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

    accounting -->|"GET /persons"| persons
    accounting -->|"GET /parts"| parts
    accounting -->|"GET /contracts<br/>(descriptors, allowances)"| contracts
    accounting -->|"GET /files,<br/>POST /files"| files
    accounting -->|"GET /utilities/i18n"| utilities

    contracts2[adb-contracts] -->|"POST /accounting/entries"| accounting
    aggregates[adb-aggregates] -.indirect.-> accounting
    views[adb-views] -.SQS events.-> accounting

External integrations

• Google Sheets v4 + Drive v3: accounting exports, CRG reports. Service account configured via GOOGLE_SHEETS_CLIENT_CREDENTIALS (JSON).
• AWS S3 (BUCKET_TEMPLATES): PDF templates.
• AWS SQS/SNS: event-driven (see listeners above).
• BlockHound: enabled in cloud environments to detect blocking code (BLOCKHOUND_ENABLED).

Configuration / deployment

Key environment variables

Special profiles

• cloud: production / dev cloud (BlockHound enabled).
• maven-build: profile used for the CI build.
• filatov: Deprecated. To be removed in the future.

Helm chart

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

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

Links

• Code: adb-accounting/
• Functional docs: technical-epics/accounting/
• CRG docs: functional-epics/reporting/