Entity register data model

Entity-relationship diagram

Identity and versions

An entity has one identity (EntityIdentity, whose id is the uid of its versions) and versions (Entity): name, legal form, LEI… at each date. Every reference to an entity — edges, external codes, rounding policies, NAVs, trial balances — points at the identity, never at a version. Renaming an entity creates a version; nothing is repointed and nothing is lost: the version valid at the requested date provides the attributes. The type of an entity is that of its identity and never changes.

A fact is changed through supersede(). With an effective date (default: now), the former state remains true until that date and stays readable at a past date. With the start date of the version, it is a correction: only the knowledge time changes. end_validity() ends a fact without erasing anything.

Quality status

A received fact (NAV, trial balance) arrives in Bronze. Its status changes through events (NavQualityEvent, BalanceQualityEvent, abstract base core.QualityEventBase), never by changing the fact, which stays immutable. An event targets a version: the status of a version is that of its latest event, Bronze without any. A correction or a restatement creates a version without events, which therefore starts again in Bronze; the former version keeps the quality it had.

Transitions (core.quality.record_quality_event): promotion one step at a time, Bronze → Silver → Gold; downgrade with a mandatory reason; only the current version receives an event. Each event carries its author (decided_by, e.g. Trail), its date and, where relevant, the reference of the control. Events are never changed nor deleted.

Relationship categories

Trial balances

Balances received already checked by AlfaWay and Trail (debit / credit balance included) and stored as received, in Bronze on arrival; their quality status then changes through BalanceQualityEvent. A balance belongs to any node of the graph: fund, sub-fund, share class, SPV… Account, counterparty, instrument and share class codes on the lines are strings from the source, with no foreign key to the register.

Parties

A party — investor, counterparty, related party — is an entity of the register: a natural person (NATURAL_PERSON), a legal person (LEGAL_PERSON) or a fund (fund of funds), with no Party table. A role is never a type: INVESTOR is deprecated. A natural person is registered under a pseudonym (investor code); their name, date of birth, address and tax identifier live in PartyPersonalData, isolated and erasable. A tax identifier or an identity document number never goes into the external codes.

Reading personal data requires the parties.pii_read permission (group acta.pii.read) and every read is logged (PersonalDataAccessLog); otherwise the admin masks it, and it always masks it in lists. Erasure deletes every version once the retention period has expired — 5 years after the end of the relationship, configurable — and logs who, when and why, without the content (PersonalDataErasure). The pseudonym, the profile, the codes and the whole business history stay intact. The KYC status of the profile is the one published by TrustLink.

Roles: service providers, counterparties, governance

Who plays which role for a fund, a sub-fund, an SPV, a holding company or a ManCo is a typed edge, never a flag on the entity. Direction: provider → served entity, like MANAGES. A role carries neither a percentage nor units and is never traversed by ownership. Allowed combinations come from RelationshipRule: a legal person for every role, a natural person also for governance and investment advice. Each role has its own served entities: a sub-fund has neither registered office nor board (it inherits the domiciliary agent and directors from the umbrella), a property manager serves an SPV or a HoldCo, a share class is never served. A ManCo is never a provider: when it manages the portfolio itself, that is MANAGES; INVESTMENT_MANAGER_OF means delegated management.

counterparties_of(entity, as_of, roles, inherit) returns the roles held towards an entity. A role set on the umbrella applies to its sub-funds (inherited), unless the sub-fund carries the same role type itself: its own then applies (direct). roles_of(party, as_of) returns every role of a party with the served entity. Both are read at a date (validity and knowledge): a depositary change on 1 July shows the old one before and the new one after.

Related parties

“Is this party related to this fund, at that date, and why?” A related party is declared — an edge of category RELATED_PARTY towards the reference entity (RELATED_PARTY_SAME_GROUP, RELATED_PARTY_SIGNIF_INFLUENCE, RELATED_PARTY_KEY_MANAGEMENT, RELATED_PARTY_OTHER, which requires a justification) — or derived from the graph at the date, never stored (logic inspired by IAS 24):

Each basis carries its path, the sequence of edges from the party to the reference. is_related_party(party, fund, as_of) queries the fund and its management company at the date. Share class units give neither control nor influence; an asset or a share class is never a party. Thresholds and depth: ACTA_RELATED_PARTY_* in the settings.

Investor register

The investor register: accounts, commitments, transactions and their reference tables. Account, commitment and transaction each have a stable identity that every reference targets, like entities. OperationType (subscription, redemption, capital call…: the EQUITY domain of the single reference table, next section) and TransactionComponentType (components of a call, a distribution, a shareholder loan, deductions) are configuration, not bitemporal: a new waterfall component is a row, not a migration. A code is never deleted, it is deactivated (is_active). Their labels are data, in French and English; the other interface languages get English.

Reading. transactions returns the transactions of an account, a class or a fund over a period of trade dates, as known at a knowledge date. cash_flows sums the flows of an account by family and direction, in the class currency (amount × rate), on the effective date: the components, and the principal (family PRINCIPAL) according to the direction declared by the operation type — the gross amount paid by the investor for a subscription, the net amount received for a redemption or a cash dividend. Deductions are already included in it: they are informative lines. A cancelled transaction does not count; a reversal counts negatively.

Unfunded commitment — provisional convention, to be validated against the LPA (it will be configurable per structure): committed amount of the version valid at the date, minus the unfunded-reducing components of the commitment's non-cancelled transactions up to the date (notice date), plus the recallable amounts still recallable at the date. A commitment transferred by a sale is not taken into account as such: a sale is recorded in the commitments — the seller's is amended at the sale date (reduced amount, TRANSFERRED if the sale is full), the buyer gets a new commitment on the same class with the original closing number. transferred_commitment_amount remains the trace received on the transaction; its consistency with the commitments is checked (C4).

Positions. A position is received as is (units, NAV, value, and for a closed-ended fund committed, contributed, unfunded, distributed, recallable), one per account, class, date, basis (trade or settlement date) and source. The register (register) and a party's portfolio (portfolio) keep, when several sources deliver the same position, the one from the best-ranked source (SourcePriority); a register never mixes two dates for a class. The register carries a computed “related party” column (IAS 24) towards the fund and its management company.

Trail. Every stored commitment, transaction or position publishes an event (DomainEvent) in the same transaction. Trail reads these events at its own pace, in order; Acta never calls it.

Ingestion. Register data arrives in batches (Standard Data File v1, JSON schemas in docs/sdf/v1/): parties, personal data, accounts, commitments, transactions and positions. Each record is processed on its own, in order: a rejection with its reason does not stop the others, and nothing rejected is stored. The same record sent again changes nothing; a different value creates a new version through the fact's write service. References (parties, funds, classes, accounts) are natural keys resolved at ingestion; no party is ever created implicitly.

Demonstration. The seed_investor_demo data set (fictitious data, prefix DEMOREG-) covers an open-ended UCITS fund with two classes, a closed-ended real estate fund (two closings, calls with equalisation, recallable distribution, carried interest, secondary sale), a fund of funds, the management company's group and its related parties, and the service providers (change of depositary during the year). Controls C1 to C6 find no discrepancy on it.

Holdings, operations and positions

What each entity holds (assets), has in cash and owes (borrowings), how it moves and what it is worth at a date. Funds, holdings and SPVs remain entities of the graph; an asset is what is held at the end of the chain (building, infrastructure, land, receivable, target fund unknown to Acta). Decisions: docs/positions_model_mapping.md.

Single reference table of operation types. OperationType lives in the base (core) and serves the four balance-sheet categories: domain = ASSET, CASH, BORROWING or EQUITY (the twelve types of the investor register). direction gives the cash flow seen from the holder: the fund for EQUITY (a subscription is an inflow), the asset holder, the borrower (a drawdown is an inflow), the account holder. MIXED (equalisation, shareholder loan): the direction comes from the components. Register-specific fields (units, NAV, commitment, pairs, principal) stay neutral outside EQUITY, and an investor transaction only takes an EQUITY type.

Equity. The EQUITY domain is the investor register (previous section), aligned without renaming: the prompt's InvestorOperation is InvestorTransaction, and its call and distribution columns (called_*, distributed_*, withholding_tax, fees) are computed from the components by breakdown; a component without a column stays readable in other. Its cash leg is a CashOperation. Full mapping: docs/positions_model_mapping.md, § 7.

Assets. An asset (Asset) has a stable identity and versions, like an entity; its real estate or debt record is a separate bitemporal table, one current version per asset. Who holds it, and how much, is never on the graph: those are its dated positions, per direct holder (SPV, HoldCo or fund). The ASSET entity type is deprecated. An indivisible asset (building, land, infrastructure) is held in quantity 1 and a percentage; a divisible asset (receivable, units, shares) in quantity. Operations, valuations (at 100 %) and positions are received facts, immutable: a status change, a finalised valuation or a correction is a new version with the same valid_from; a restated position goes back to Bronze.

Borrowings. A borrowing (Borrowing) has a borrower (SPV, HoldCo or fund) and exactly one lender: an entity of the group for an intra-group loan, otherwise a party (bank, investor, vendor, lessor). An intra-group loan is recorded once: borrowings_of returns it as a liability of the borrower and a receivable of the lender. A bank, a lessor or a fund financer must hold the LENDER_TO role towards the borrower at signing. Tranches, operations (positive amount, effect on the drawn amount given by the type: drawdown and capitalised interest +, repayments and waiver −) and positions (drawn, undrawn, accrued interest, actual covenants, as received) follow the same principle as assets.

Cash. An account (CashAccount) belongs to an SPV, a HoldCo or a fund, in a bank holding the ACCOUNT_BANK_OF role towards it; its reference is masked, never a full IBAN. A DSRA or pledged account names the borrowing it secures. A cash operation is a statement line with a signed amount (+ inflow, − outflow, per the direction of its type); its leg is at most one asset, borrowing or investor operation of the holder. A line loaded from a statement stays unmatched until a new version gives it its leg.

Controls INV-01 to INV-06. Non-blocking Python services (holdings/controls.py), read by Trail: they return findings (code, keys, expected, actual, difference, tolerance) and neither refuse nor correct anything. INV-01 roll-forward (quantity or % of an asset, balance of an account, drawn amount of a borrowing, units of the register); INV-02 cash leg of every settled operation that moves money, and list of unmatched lines; INV-03 one lender, one leg (database CHECKs, re-read); INV-04 Σ % of an asset ≤ 100; INV-05 cross-check with the trial balance per category, through the BalanceCategoryMapping table (account prefix → fixed assets, cash, financial debt, intragroup loans apart); INV-06 received rate for every position in a foreign currency, consistent per currency (no rate table). For one object and one date, a single position is read: the best-ranked source, then the most final nature. API: /api/v1/controls/holdings/. Assets, borrowings, cash and operation types are readable through the API (/api/v1/assets/, borrowings/, cash-accounts/, operation-types/…), read only.

API and ingestion. Everything is readable through the API, read only: /api/v1/assets/, asset-operations/, asset-valuations/, asset-positions/, borrowings/, borrowing-tranches/, borrowing-operations/, borrowing-positions/, entities/{uid}/borrowings/, cash-accounts/, cash-operations/, cash-positions/, operation-types/ — masters at as_of / known_at, facts at known_at. Everything comes in through the Standard Data File v1 (POST /api/v1/ingest/): masters identified by their code, facts by (source, source_record_id), written by the services above.

Fees

Work in progress (fees prompt): the fees of a fund, from the reference table of fee types to the amounts received with the NAV. Acta does not compute the NAV: it stores the fees received from the administrator and checks them against the contractual terms. Decisions: docs/fees_model_mapping.md.

Fee types. FeeType is a coded configuration table, like OperationType: adding a fee type is a row. Each type has a family (service provider, performance, tax, other), a basis (% of NAV, fixed amount, % of commitments, % of invested capital) and, for a service provider, the role it holds towards the fund (DEPOSITARY_OF, ADMINISTRATOR_OF…), used to check the provider of a fee term. A tax (subscription tax) has no provider. Thirteen types seeded.

Contractual terms. FeeSchedule (bitemporal) holds the terms of a fee type on a share class or on a fund — umbrella, sub-fund or standalone fund —, exactly one of the two (CHECK), one current schedule per scope and fee type. Annual rate in % for a percentage basis (or tiers), annual fixed amount otherwise; annual minimum and maximum, frequency, day count convention (ACT/365 by default). The provider must hold the role of the fee type towards the fund (umbrella inheritance included) on the validity date; a service provider fee names one, a tax never. Terms applying to a class: those of the class, else of its fund, else of the umbrella (resolve_fee_schedule). Tiers (FeeScheduleTier) belong to one version: contiguous, from 0 to infinity, copied onto every new version; the schedule says how they apply (tier_method: each band at its rate, or the rate of the tier reached on the whole basis). A change creates a version (correction, or change at a date); scope and fee type never change.

Fees received with the NAV. FeeAccrual is an immutable dated fact, as received from the administrator (same mechanism as positions): for a share class — or for a sub-fund or standalone fund when the fee is not broken down by class —, a NAV date and type, a fee type and a source, the accrual of the period (negative for a reversal) and the year-to-date amount (empty when not received, never recomputed), in the currency of the class. valid_from = NAV date; a correction is a new version at the same valid_from, back to Bronze (quality status by FeeAccrualQualityEvent). Several sources coexist (SourcePriority, domain FEE_ACCRUAL). Fees arrive through the Standard Data File (FEE_ACCRUAL type); their actual payment is a FUND_FEE_PAYMENT cash operation. Only the fees of an official NAV will be checked (FEE-01 to FEE-04).

Fee payments. FeePayment (immutable fact, as received from the fee report) records what was paid: fee type, scope (class or fund), payment date, period covered, amount (negative for a refund), provider paid — who must hold the role of the fee type towards the fund on that date. It is linked, once known, to the FUND_FEE_PAYMENT cash operation that settled it, on an account of the fund; one operation may settle several fees, and a line so linked no longer appears among unmatched operations. Accrued versus paid: controls of lot 4.

Controls. Non-blocking, they read only the fees of an official NAV, one source per date (SourcePriority). FEE-01: the accrual of the period equals the annual amount of the applicable schedule (basis × rate, tiers, fixed amount, bounded by the minimum and the maximum) × the year fraction since the previous accrual, per the day count convention; the basis is the official NAV of the class, or the sum of those of the classes of the fund. FEE-02: the year-to-date amount equals the previous one plus the accrual, and restarts from the accrual after the financial year end (the fund's, else its umbrella's). FEE-03: at the date of a trial balance, the sum of the year-to-date amounts received (fees of the fund and of its classes, converted into the fund currency at the ratio of the NAV amounts) equals the charges of the accounts mapped to the fee type (FeeAccountMapping: account prefix → type, the longest wins, configuration without seed). FEE-05: the provider of a schedule still holds its role on the date. FEE-06: the fee payments linked to a FUND_FEE_PAYMENT operation cover its amount. Missing data gives “not available”, never a default.

Computed on demand, never stored. FEE-04, ongoing charges: sum of the accruals of the period (performance fee excluded) over the average NAV of the period — simple average of the NAV dates or weighted by the days each NAV applies, as chosen —, and this ratio annualised; for a class, the fees of the fund are allocated at its weight on each NAV date. Fee report: by scope and type, accrued and paid over the period, accrued, paid and outstanding at the end date.

Enumeration values