Module 1

Geographic & Org Setup

Purpose#

Establishes the operational geography before any farmer data can be captured. This is the first module an Entity Admin configures — nothing else can exist without the hierarchy. All data in SMS is scoped to this four-level tree.

Geographic hierarchy#

text

Organisation (Entity)
└── Region
    └── District
        └── Community
            └── Buying Station (optional PMS sub-unit)

Each level has a code (auto-generated or manual) and a name. The hierarchy labels are configurable per country — "Region" and "District" can be renamed to local administrative equivalents at setup time.

Farmer code format#

Every enrolled farmer receives an immutable code generated at registration time:

text

[Entity Code]-[Region Code]-[District Code]-[Community Code]-[Sequence]

Example: GH-AR-KUM-ABR-00142
  GH    → Ghana entity
  AR    → Ashanti Region
  KUM   → Kumasi District
  ABR   → Abrewapong Community
  00142 → Farmer sequence number (zero-padded, per community)

Global sequence per community

Sequence numbers are assigned per-community (not per officer) to avoid collisions during offline enrollment. Two officers in the same community enrolling simultaneously will receive non-conflicting codes when they sync.

Feature set#

Feature	Description
Organisation config	Name, country, legal entity type, contact details, logo, supported commodities, locale/timezone.
Region management	Create, edit, deactivate regions. Assign Regional Manager(s).
District management	Belongs to a region. Configurable label (district / zone / sub-region). Assign District Manager(s).
Community management	Belongs to a district. Optional GPS centroid for map display. Assign Sustainability Officers.
Buying Station	Optional PMS sub-unit within a community. Name, GPS location, capacity (bags).
Bulk CSV import	Upload a CSV template to create regions, districts, communities in batch for initial setup.
Hierarchy levels	Configurable hierarchy level names (labels for each level of the tree).

Packages#

Package	Type	Key exports
`@repo/feature-sms-settings`	Backend	Services: org-config, region, district, community, hierarchy, buying-station, csv-import, hierarchy-level-config
`@repo/feature-sms-settings-web`	Frontend	Hierarchy tree UI, node CRUD forms, CSV import wizard

API routes#

Route	Notes
/api/orgs	Read and update organisation config.
/api/regions	CRUD for regions.
/api/districts	CRUD for districts.
/api/communities	CRUD for communities.
/api/nodes	Generic hierarchy node operations.
/api/hierarchy	Full hierarchy tree read.
/api/hierarchy-levels	Manage hierarchy level label config.
/api/buying-stations	CRUD for buying stations.
/api/import	Bulk CSV import endpoint.

Key Zod schemas#

All schemas live in @repo/feature-sms-settings or @repo/validation:

OrgConfigSchema
CreateRegionSchema
CreateDistrictSchema
CreateCommunitySchema
HierarchyLevelConfigSchema
CreateBuyingStationSchema
CsvImportRowSchema

Setup flow#

Entity Admin performs initial setup in this order: configure org → create regions → create districts per region → create communities per district → assign Sustainability Officers to communities. Bulk CSV import is available for steps 2–4.