Parties module (parties)

The parties module in src/cluster_erp/modules/parties/ keeps one record, the party (Party, a person or an organisation the company deals with), for everyone the business knows. Customers, suppliers, employees, and owned organisations are roles of a party, not separate cards; that model is explained on party unification. The module also holds addresses, communication channels, spoken languages, and the country, address-level, and channel-type reference data. This page is the module overview; each sub-module has its own reference page.

At a glance¶

What the module does¶

• Keeps one party card per person or organisation, with a yearly business code, a type, a display name, tax fields, notes, and an active flag (src/cluster_erp/modules/parties/parties/models.py:18-55).
• Records the roles a party plays as three flags, is_customer, is_supplier, and is_employee, which other modules keep in step over the EventBus (src/cluster_erp/modules/parties/module.py:168-195).
• Stores structured addresses whose levels come from country reference data; see addresses.
• Stores communication channels such as e-mail and phone; see communication channels.
• Stores the languages a person speaks; see person languages.
• Seeds the ISO country list and the default channel types at start-up (src/cluster_erp/modules/parties/module.py:37-74); see settings and reference data.
• Holds a profile photo per party in the shared attachment store (src/cluster_erp/modules/parties/parties/routes.py:153-249).

Sub-modules¶

All five routers are included under one module router, settings first, and the whole router depends on the parties app entitlement (src/cluster_erp/modules/parties/module.py:96-103). Two more routers with the same prefix live in the server layer: guided creation (POST /api/v1/parties/composite) and role enabling (POST /api/v1/parties/{party_id}/roles/...); both are described on party unification.

Data model¶

The diagram shows the eleven tables of the module and their foreign keys.

erDiagram
 Party ||--o| Individual : "party_id"
 Party ||--o| OrganisationInfo : "party_id"
 Party ||--o{ Address : "party_id"
 Party ||--o{ CommunicationChannel : "party_id"
 Party ||--o{ PersonLanguage : "party_id"
 Address ||--o{ AddressComponent : "address_id"
 Country ||--o{ Address : "country_id"
 Country ||--o{ AddressLevel : "country_id"
 AddressLevel ||--o{ AddressLevelValue : "level_id"
 AddressLevelValue ||--o{ AddressComponent : "level_value_id"
 ChannelType ||--o{ CommunicationChannel : "channel_type_id"

In prose: a Party has at most one live Individual row and at most one live OrganisationInfo row, and any number of addresses, channels, and spoken languages. An Address belongs to a Country and is made of AddressComponent rows, each pointing at an AddressLevel and an AddressLevelValue of that country. A CommunicationChannel has a ChannelType.

Every entity derives from BaseModel, so rows carry a ULID primary key, audit columns, and soft-delete columns; see base model and ids and soft delete and deactivation.

Screens and metadata¶

get_metadata declares one sidebar group Parties (Turkish Taraflar) with four sections (src/cluster_erp/modules/parties/module.py:557-641):

• Parties, a tabbed list with two entity tabs: the party list and the organisation list of owned_organisations (Turkish Kuruluşlar) (src/cluster_erp/modules/parties/module.py:570-599).
• Addresses and Communication Channels, two lists that use the list_all endpoints and are hidden from the tab bar (src/cluster_erp/modules/parties/module.py:603-626).
• Settings, with the tabs country, address_level, and channel_type (src/cluster_erp/modules/parties/module.py:627-637).

The party list has the columns code, name, type, tax id, active, and created, and two filters, Type and Role (src/cluster_erp/modules/parties/parties/metadata.py:440-508). The party detail has the tabs General, Addresses, Communication Channels, Spoken Languages, and Working Calendar; the last one is a custom widget of the calendars module (src/cluster_erp/modules/parties/parties/metadata.py:509-544). Role sections appear on the same card through five FacetMeta entries (src/cluster_erp/modules/parties/parties/metadata.py:550-763). The party card also declares guided creation, documents on create, tenant-field buckets, the quick actions call, message, and mail, and a photo (src/cluster_erp/modules/parties/parties/metadata.py:313-378). The web app renders these generically; see generic detail and generic form.

Status and actions¶

A party has no status field; it has an is_active flag (src/cluster_erp/modules/parties/parties/models.py:32). The module declares six ActionMeta entries (counted with grep "ActionMeta(" in the package).

Business rules¶

• A new party gets its code from the yearly sequence party (src/cluster_erp/modules/parties/parties/services.py:116); see base model and ids.
• The list search matches the display name, the code, and searchable tenant fields (src/cluster_erp/modules/parties/parties/services.py:64-73).
• The role filter reads the three role flags (src/cluster_erp/modules/parties/parties/services.py:55-61).
• Create does not copy is_customer, is_supplier, or is_employee from the payload into the row (src/cluster_erp/modules/parties/parties/services.py:117-126). The flags are set by the role routes, by PartyRoleSet, and by a start-up reconciliation (src/cluster_erp/server/app.py:1002-1055).
• An update raises the row version only when a field changed, and emits PartyUpdated with the new display name and tax id (src/cluster_erp/modules/parties/parties/services.py:197-212).
• Deleting a party sets deleted_at and emits PartyDeleted; bulk delete emits one PartyDeleted per id (src/cluster_erp/modules/parties/parties/services.py:216-233).
• A photo must be JPEG, PNG, WebP, or GIF, not empty, and at most 5 MB (src/cluster_erp/modules/parties/parties/routes.py:153-154, src/cluster_erp/modules/parties/parties/routes.py:196-203).

Events and queries¶

The module consumes 14 contracts and produces 3. Consumed means passed as the first argument of subscribe( or register_query_handler( in the package; produced means a contract class name followed by ( in the package. Producers and consumers across modules are listed on the contracts reference.

Permissions¶

How permission codes are seeded and checked is explained on roles and permissions.

Privacy, retention, and history¶

privacy_handlers.py answers the privacy module's two fan-out events for this module's tables (src/cluster_erp/modules/parties/privacy_handlers.py:1-10). collect_subject_data returns a copy of the party, its individual and organisation details, addresses, channels, and languages (src/cluster_erp/modules/parties/privacy_handlers.py:69-100). anonymise_subject overwrites identifying values with the request's marker, clears tax fields and notes, scrubs personal tenant fields, deactivates the rows with the request's reason, and reports the photo attachment so that the privacy module removes the file (src/cluster_erp/modules/parties/privacy_handlers.py:234-291). GetPartyContactValues returns the e-mail addresses and phone numbers of the party's live channels (src/cluster_erp/modules/parties/privacy_handlers.py:35-66). The overall flow is on privacy and data-subject requests. Changes are captured by change history.

Analytics facts¶

analytics_facts.py declares one fact set, party, over parties_parties, with the dimensions party type, the three role flags, active, and created date, and one measure, party_count (src/cluster_erp/modules/parties/analytics_facts.py:17-72). The module answers DescribeAnalyticsFacts with it (src/cluster_erp/modules/parties/analytics_facts.py:75-77).

Settings and reference data¶

Countries, address levels, address-level values, and channel types are reference data in the database. Countries come from the ISO 3166 list of the pycountry package and are seeded at start-up; existing rows are not overwritten (src/cluster_erp/modules/parties/settings/services.py:38-86). The details are on settings and reference data.

Tests¶

Found by file name in web-client/ and by a grep for modules.parties in tests/.

Discrepancies¶

Terms introduced¶

Related pages¶

• Modules index
• Party unification
• Parties sub-module
• Addresses
• Communication channels
• Person languages
• Settings and reference data
• Owned organisations module
• API reference for this module
• Related material, historical, not verified: the in-tree note src/cluster_erp/modules/parties/docs/how-to.md. It does not cover spoken languages, guided creation, or role enabling.

Verified against commit 92f8051 on 2026-11-13.