Parties settings and reference data

This page lists the reference data of the parties module: countries, address levels, and address-level values in src/cluster_erp/modules/parties/settings/, and how each is seeded. These tables are what lets an address follow the structure of any country without code changes. Channel types are also reference data of this module; they are listed on communication channels.

Scope and source¶

• Defined in: src/cluster_erp/modules/parties/settings/models.py (Country, AddressLevel, AddressLevelValue), services.py (CountryService, AddressLevelService, AddressLevelValueService), routes.py, seed_data.py (ADDRESS_LEVEL_TEMPLATES), metadata.py (COUNTRY_META, ADDRESS_LEVEL_META, ADDRESS_LEVEL_VALUE_META, CHANNEL_TYPE_META).
• Count: 3 tables; 18 routes (@router. decorators in routes.py); address-level templates for 43 countries (top-level keys of ADDRESS_LEVEL_TEMPLATES).
• On the web, these tables are the tabs country, address_level, and channel_type of the Settings section of the parties app (src/cluster_erp/modules/parties/module.py:627-637). The settings view is described on generic tree and settings.

Countries¶

At every start, seed_iso_countries adds every ISO 3166 country from the pycountry package that is not yet present, using the common name and the official name. It never changes an existing row and leaves phone_code empty; the docstring states that pycountry does not carry calling codes (src/cluster_erp/modules/parties/module.py:44-61, src/cluster_erp/modules/parties/settings/services.py:38-86). The action Update from Internet calls fetch_from_internet, which reads the same bundled pycountry data. It updates the codes and names of existing countries and adds missing ones (src/cluster_erp/modules/parties/settings/services.py:102-139). The list returns a display_name in the request language, resolved from translations (src/cluster_erp/modules/parties/settings/routes.py:38-52). Other modules look a country up by alpha-2 or alpha-3 code with GetCountryByCode (src/cluster_erp/modules/parties/module.py:271-301).

Address levels¶

The action Seed Address Levels creates the levels of one country from ADDRESS_LEVEL_TEMPLATES (src/cluster_erp/modules/parties/settings/routes.py:133-146, src/cluster_erp/modules/parties/settings/services.py:239-282). If the country already has levels, it only adds missing translations from the template. If no template exists for the country code, it creates nothing and says so. The template for TR, for example, has four levels: province, district, neighbourhood, and postal code, the last one optional (src/cluster_erp/modules/parties/settings/seed_data.py:6-11).

Address-level values¶

A value is unique per level, text, and parent among live rows (src/cluster_erp/modules/parties/settings/models.py:85-94). GET /settings/address-levels/{level_id}/values lists a level's values sorted by text, optionally filtered by parent_id, which lets a form offer only the districts of the chosen province (src/cluster_erp/modules/parties/settings/routes.py:223-235, src/cluster_erp/modules/parties/settings/services.py:289-302).

Routes¶

All paths are under /api/v1/parties/settings.

Constraints and validation¶

• Creating a country with a code that a live country already has answers a conflict (src/cluster_erp/modules/parties/settings/routes.py:72-74).
• Country codes are stored in upper case (src/cluster_erp/modules/parties/settings/services.py:141-153).
• Deleting a country, level, or value sets deleted_at; nothing is removed (src/cluster_erp/modules/parties/settings/services.py:166-177).

Discrepancies¶

Terms introduced¶

Related pages¶

• Parties module
• Addresses
• Communication channels
• Reference data and core i18n

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