EnAccess · Zhey-on · Mar 14, 2026
diff --git a/collections/Create Agent.bru b/collections/Create Agent.bru
@@ -16,7 +16,7 @@ body:json {
     "surname": "Test Agent (Created via API)",
     "is_customer": 0,
     "nationality": null,
-    "city_id": 3,
+    "village_id": 3,
     "email": "demo_agent_api_created@example.com",
     "phone": "+254 123 456789",
     "is_primary": 1,

diff --git a/collections/Create Customer (incomplete information).bru b/collections/Create Customer (incomplete information).bru
@@ -17,7 +17,7 @@ body:json {
     "surname": null,
     "phone": null,
     "street": null,
-    "city_id": null,
+    "village_id": null,
     "is_primary": null,
     "country_code": null,
     "title": null,

diff --git a/collections/Create Customer.bru b/collections/Create Customer.bru
@@ -17,7 +17,7 @@ body:json {
     "surname": "surname",
     "phone": "+254123456789",
     "street": "Some street, somewhere",
-    "city_id": 1,
+    "village_id": 1,
     "is_primary": true,
     "title": "Mr",
     "education": "Well educated",

diff --git a/docs/usage-guide/customers.md b/docs/usage-guide/customers.md
@@ -5,7 +5,7 @@ order: 8
 # Customers
 
 MicroPowerManager customers are listed under `Customers` in the sidebar.
-This table contains the customers' name, phone number, city, and device number.
+This table contains the customers' name, phone number, village, and device number.
 The search function also includes all those fields.
 By clicking on a customer, the customer’s profile page will be loaded
 Data parameters included are:

diff --git a/src/backend/app/Console/Commands/ReportGenerator.php b/src/backend/app/Console/Commands/ReportGenerator.php
@@ -6,8 +6,8 @@
 use Carbon\Carbon;
 
 class ReportGenerator extends AbstractSharedCommand {
-    protected $signature = 'reports:city-revenue {type} {--start-date=} {--company-id=}';
-    protected $description = 'Creates city revenue reports';
+    protected $signature = 'reports:village-revenue {type} {--start-date=} {--company-id=}';
+    protected $description = 'Creates village revenue reports';
 
     public function __construct(private Reports $reports) {
         parent::__construct();

diff --git a/src/backend/app/DTO/ClusterDashboardData.php b/src/backend/app/DTO/ClusterDashboardData.php
@@ -17,7 +17,7 @@ public function __construct(
         public float $revenue = 0.0,
         public int $population = 0,
         /** @var array<array-key, mixed> */
-        public array $citiesRevenue = [],
+        public array $villagesRevenue = [],
         /** @var array<array-key, mixed> */
         public array $revenueAnalysis = [],
         /** @var array<array-key, mixed> */
@@ -43,7 +43,7 @@ public function toArray(): array {
             'meterCount' => $this->meterCount,
             'revenue' => $this->revenue,
             'population' => $this->population,
-            'citiesRevenue' => $this->citiesRevenue,
+            'villagesRevenue' => $this->villagesRevenue,
             'revenueAnalysis' => $this->revenueAnalysis,
             'clusterData' => $this->cluster,
             'period' => $this->period,

diff --git a/src/backend/app/Http/Controllers/AgentWebController.php b/src/backend/app/Http/Controllers/AgentWebController.php
@@ -42,7 +42,7 @@ public function store(CreateAgentRequest $request): ApiResource {
         $agentData = [
             'password' => $request['password'],
             'email' => $request['email'],
-            'mini_grid_id' => $request['city_id'],
+            'mini_grid_id' => $request['village_id'],
             'agent_commission_id' => $request['agent_commission_id'],
             'mobile_device_id' => '-',
             'fire_base_token' => '-',

diff --git a/src/backend/app/Http/Controllers/AppliancePersonController.php b/src/backend/app/Http/Controllers/AppliancePersonController.php
@@ -84,7 +84,7 @@ public function store(
 
                 $address = $this->addressesService->make([
                     'street' => $addressData['street'],
-                    'city_id' => $addressData['city_id'],
+                    'village_id' => $addressData['village_id'],
                 ]);
 
                 // Attach the new address to the person rather than the device.

diff --git a/src/backend/app/Http/Controllers/CityController.php b/src/backend/app/Http/Controllers/CityController.php
diff --git a/src/backend/app/Http/Controllers/ClusterExportController.php b/src/backend/app/Http/Controllers/ClusterExportController.php
@@ -45,7 +45,7 @@ public function downloadCsv(Request $request): StreamedResponse {
 
         $this->clusterExportService->setClusterData($clusters);
         $this->clusterExportService->setExportingData();
-        $headers = ['Cluster Name', 'Manager', 'Mini Grids Count', 'Cities Count', 'Created At', 'Updated At'];
+        $headers = ['Cluster Name', 'Manager', 'Mini Grids Count', 'Villages Count', 'Created At', 'Updated At'];
         $csvPath = $this->clusterExportService->saveCsv($headers);
 
         return Storage::download($csvPath, 'cluster_export_'.now()->format('Ymd_His').'.csv');

diff --git a/src/backend/app/Http/Controllers/MaintenanceUserController.php b/src/backend/app/Http/Controllers/MaintenanceUserController.php
@@ -42,7 +42,7 @@ static function ($q) use ($phone) {
             } else {
                 $person = $this->personService->createMaintenancePerson($personData);
             }
-            $this->addressService->createForPerson($person->getId(), $request->getCityId(), $request->getPhone(), $request->getEmail(), $request->getStreet(), true);
+            $this->addressService->createForPerson($person->getId(), $request->getVillageId(), $request->getPhone(), $request->getEmail(), $request->getStreet(), true);
         }
 
         // Ensure the person is marked as maintenance type

diff --git a/src/backend/app/Http/Controllers/MeterGeographicalInformationController.php b/src/backend/app/Http/Controllers/MeterGeographicalInformationController.php
@@ -4,7 +4,7 @@
 
 use App\Http\Resources\ApiResource;
 use App\Models\Meter\Meter;
-use App\Services\CityService;
+use App\Services\VillageService;
 use App\Services\MeterGeographicalInformationService;
 use App\Services\MeterService;
 use App\Services\PersonMeterService;
@@ -14,7 +14,7 @@ class MeterGeographicalInformationController extends Controller {
     public function __construct(
         private MeterGeographicalInformationService $meterGeographicalInformationService,
         private PersonMeterService $personMeterService,
-        private CityService $cityService,
+        private VillageService $villageService,
         private MeterService $meterService,
     ) {}
 
@@ -28,12 +28,12 @@ public function __construct(
      * @responseFile responses/meters/meters.geo.list.json
      */
     public function index(?int $miniGridId = null): ApiResource {
-        $cityIds = $miniGridId ? $this->cityService->getCityIdsByMiniGridId($miniGridId) : [];
-        // we can get city id only by address
+        $villageIds = $miniGridId ? $this->villageService->getVillageIdsByMiniGridId($miniGridId) : [];
+        // we can get village id only by address
         if ($miniGridId === null) {
             $meters = $this->meterService->getUsedMetersGeoWithAccessRatePayments();
         } else {
-            $meters = $this->meterService->getUsedMetersGeoWithAccessRatePaymentsInCities($cityIds);
+            $meters = $this->meterService->getUsedMetersGeoWithAccessRatePaymentsInVillages($villageIds);
         }
 
         return ApiResource::make($meters);

diff --git a/src/backend/app/Http/Controllers/PersonController.php b/src/backend/app/Http/Controllers/PersonController.php
@@ -34,7 +34,7 @@ public function __construct(
      * @urlParam agent_id int optional. To get a list of customers of a specific agent.
      * @urlParam limit int optional. The number of items per page.
      * @urlParam active_customer int optional. To get a list of active customers. Default: 0
-     * @urlParam city_id int optional. Filter by primary address city/village id.
+    * @urlParam village_id int optional. Filter by primary address village id.
      * @urlParam total_paid_min float optional. Minimum total paid amount for the customer.
      * @urlParam total_paid_max float optional. Maximum total paid amount for the customer.
      * @urlParam latest_payment_from string optional. ISO date string for minimum latest payment date.
@@ -50,7 +50,7 @@ public function index(Request $request): ApiResource {
         $perPage = $request->input('per_page', config('settings.paginate', 15));
         $agentId = $request->input('agent_id');
         $activeCustomer = $request->has('active_customer') ? (bool) $request->input('active_customer') : null;
-        $cityId = $request->input('city_id');
+        $villageId = $request->input('village_id');
         $totalPaidMin = $request->input('total_paid_min');
         $totalPaidMax = $request->input('total_paid_max');
         $latestPaymentFrom = $request->input('latest_payment_from');
@@ -65,7 +65,7 @@ public function index(Request $request): ApiResource {
                 $customerType,
                 $agentId,
                 $activeCustomer,
-                $cityId,
+                $villageId,
                 $totalPaidMin,
                 $totalPaidMax,
                 $latestPaymentFrom,

diff --git a/src/backend/app/Http/Controllers/PersonExportController.php b/src/backend/app/Http/Controllers/PersonExportController.php
@@ -58,7 +58,7 @@ public function downloadCsv(Request $request): StreamedResponse {
 
         $this->peopleExportService->setPeopleData($people);
         $this->peopleExportService->setExportingData();
-        $headers = ['Title', 'Name', 'Surname', 'Birth Date', 'Gender', 'Email', 'Phone', 'City', 'Device Serial', 'Agent Name'];
+        $headers = ['Title', 'Name', 'Surname', 'Birth Date', 'Gender', 'Email', 'Phone', 'Village', 'Device Serial', 'Agent Name'];
         $csvPath = $this->peopleExportService->saveCsv($headers);
 
         return Storage::download($csvPath, 'customer_export_'.now()->format('Ymd_His').'.csv');

diff --git a/src/backend/app/Http/Controllers/Reports.php b/src/backend/app/Http/Controllers/Reports.php
@@ -3,7 +3,7 @@
 namespace App\Http\Controllers;
 
 use App\Exceptions\ConnectionGroupNotFoundException;
-use App\Models\City;
+use App\Models\Village;
 use App\Models\ConnectionGroup;
 use App\Models\ConnectionType;
 use App\Models\DatabaseProxy;
@@ -52,7 +52,7 @@ public function __construct(
         private ConnectionType $connectionType,
         private ConnectionGroup $connectionGroup,
         private PaymentHistory $paymentHistory,
-        private City $city,
+        private Village $village,
         private Target $target,
         private Report $report,
     ) {}
@@ -145,11 +145,11 @@ private function initSheet(): void {
 
     public function generateWithJob(string $startDate, string $endDate, string $reportType): void {
         try {
-            $cities = $this->city->newQuery()->get();
-            foreach ($cities as $city) {
+            $villages = $this->village->newQuery()->get();
+            foreach ($villages as $village) {
                 $this->getCustomerGroupCountPerMonth($endDate);
                 $this->getCustomerGroupEnergyUsagePerMonth([$startDate, $endDate]);
-                $this->generateReportForCity($city->id, $city->name, $startDate, $endDate, $reportType);
+                $this->generateReportForVillage($village->id, $village->name, $startDate, $endDate, $reportType);
             }
         } catch (\Exception $e) {
             Log::critical(
@@ -501,9 +501,9 @@ private function excelColumnRange(string $lower, string $upper): \Generator {
      * @throws ConnectionGroupNotFoundException
      * @throws \PhpOffice\PhpSpreadsheet\Exception
      */
-    private function generateReportForCity(
-        int $cityId,
-        string $cityName,
+    private function generateReportForVillage(
+        int $villageId,
+        string $villageName,
         string $startDate,
         string $endDate,
         string $reportType,
@@ -519,8 +519,8 @@ private function generateReportForCity(
             ->selectRaw('id,message,SUM(amount) as amount,GROUP_CONCAT(DISTINCT id SEPARATOR \',\') AS transaction_ids')
             ->whereHas(
                 'device.person.addresses',
-                function ($q) use ($cityId) {
-                    $q->where('city_id', $cityId)
+                function ($q) use ($villageId) {
+                    $q->where('village_id', $villageId)
                         ->where('is_primary', 1);
                 }
             )
@@ -568,7 +568,7 @@ static function ($q) {
             $sheet2->setTitle('monthly');
             // Add targets
             $this->addTargetConnectionGroups($sheet2);
-            $this->addStoredTargets($sheet2, $cityId, $endDate);
+            $this->addStoredTargets($sheet2, $villageId, $endDate);
             $this->addTargetsToXls($sheet2);
         }
 
@@ -577,11 +577,11 @@ static function ($q) {
             $databaseProxy = app(DatabaseProxy::class);
             $companyId = $databaseProxy->findByEmail($user->email)->getCompanyId();
 
-            $fileName = Str::slug("{$reportType}-{$cityName}-{$dateRange}").'.xlsx';
+            $fileName = Str::slug("{$reportType}-{$villageName}-{$dateRange}").'.xlsx';
             $path = "reports/{$companyId}/village_report_{$reportType}/{$fileName}";
 
             // Save to a temporary local file
-            $tempFile = tempnam(sys_get_temp_dir(), 'city_report_').'.xlsx';
+            $tempFile = tempnam(sys_get_temp_dir(), 'village_report_').'.xlsx';
             $writer = new Xlsx($this->spreadsheet);
             $writer->save($tempFile);
 
@@ -593,13 +593,13 @@ static function ($q) {
                 'path' => $path."*{$companyId}",
                 'type' => $reportType,
                 'date' => "{$startDate}---{$endDate}",
-                'name' => $cityName,
+                'name' => $villageName,
             ]);
 
             Log::info("Report generated: {$fileName}");
         } catch (Exception $e) {
-            Log::error('Error generating report for city', [
-                'city' => $cityName,
+            Log::error('Error generating report for village', [
+                'village' => $villageName,
                 'exception' => $e->getMessage(),
             ]);
         }
@@ -697,11 +697,11 @@ private function addTargetsToXls(Worksheet $sheet): void {
         }
     }
 
-    private function addStoredTargets(Worksheet $sheet, int $cityId, string $endDate): void {
+    private function addStoredTargets(Worksheet $sheet, int $villageId, string $endDate): void {
         $targetData = $this->target::with('subTargets.connectionType')
             ->where('target_date', '>', $endDate)
             ->where('owner_type', 'mini-grid')
-            ->where('owner_id', $cityId)
+            ->where('owner_id', $villageId)
             ->oldest('target_date')->first();
 
         if (!$targetData) { // no target is defined for that mini-grid

diff --git a/src/backend/app/Http/Controllers/RevenueController.php b/src/backend/app/Http/Controllers/RevenueController.php
@@ -3,7 +3,7 @@
 namespace App\Http\Controllers;
 
 use App\Http\Resources\ApiResource;
-use App\Models\City;
+use App\Models\Village;
 use App\Models\Cluster;
 use App\Models\ConnectionGroup;
 use App\Models\ConnectionType;
@@ -22,7 +22,7 @@ public function __construct(
         private Ticket $ticket,
         private TicketCategory $label,
         private PeriodService $periodService,
-        private City $city,
+        private Village $village,
         private RevenueService $revenueService,
         private MeterRevenueService $meterRevenueService,
         private Target $target,
@@ -71,11 +71,11 @@ public function trending(int $id, Request $request): ApiResource {
         $end = $request->input('endDate', date('Y-m-d'));
         $endDate = Carbon::parse($end)->endOfDay();
 
-        $cities = $this->city::query()->where('mini_grid_id', $id)->get();
-        $cityIds = implode(',', $cities->pluck('id')->toArray());
+        $villages = $this->village::query()->where('mini_grid_id', $id)->get();
+        $villageIds = implode(',', $villages->pluck('id')->toArray());
 
-        if (count($cities) === 0) {
-            $response = ['data' => null, 'message' => 'There is no city for this MiniGrid'];
+        if (count($villages) === 0) {
+            $response = ['data' => null, 'message' => 'There is no village for this MiniGrid'];
 
             return ApiResource::make($response);
         }
@@ -92,9 +92,9 @@ public function trending(int $id, Request $request): ApiResource {
             $initialData
         );
 
-        $connections->each(function (ConnectionType $connection) use ($endDate, $startDate, $cityIds, &$response) {
-            $this->meterRevenueService->getConnectionTypeBasedRevenueInWeeklyPeriodForCities(
-                $cityIds,
+        $connections->each(function (ConnectionType $connection) use ($endDate, $startDate, $villageIds, &$response) {
+            $this->meterRevenueService->getConnectionTypeBasedRevenueInWeeklyPeriodForVillages(
+                $villageIds,
                 $connection->id,
                 $startDate,
                 $endDate