masaruk Logo

Naming Conventions

Standard naming conventions for MASARUK analysis and development

1. Purpose

This document defines standard naming conventions for:

  • Entities
  • Database tables
  • Fields/columns
  • Enums and statuses
  • API endpoints
  • Screens and modules

The objective is to ensure that the same concept is named consistently across: UI, Data model, APIs, Documentation.

2. Core Naming Principles

1. One concept → One canonical English name

Example: حجز → Booking (Not: Order, Reservation, Ticket)

2. Arabic UI labels are never replaced

We always reference them explicitly as 'UI label' alongside their English technical names

3. Separation between UI names and technical names

UI (Arabic) can remain domain-friendly. Technical names (English) are used in DB, API, internal logic

4. Clarity over brevity

Prefer payment_transaction_id over tx_id. Prefer ad_campaign_status over status

3. Entities & Domain Objects

3.1 Entity Naming (English)

Entities are named in PascalCase, singular:

UserProviderTripBookingBookingPassengerPaymentTransactionHotelBusRestStopAdCampaignRating

3.2 Arabic–English Mapping Examples

Arabic (UI)EnglishEntity
إدارة الرحلاتTrips ManagementTrip
إدارة الحجوزاتBookings ManagementBooking
قائمة الباصاتBuses ManagementBus
قائمة الفنادقHotels ManagementHotel
قائمة الاستراحاتRest Stops ManagementRestStop
إدارة الإعلاناتAd Campaigns ManagementAdCampaign
التقارير الماليةFinancial ReportsPaymentTransaction
حجوزاتيMy Bookings (B2C)Booking
تقييم الرحلةTrip RatingRating

4. Database Tables and Columns

4.1 Table Names

Use snake_case, plural for main tables:

usersproviderstripsbookingsbooking_passengerspayment_transactionshotelsbusesrest_stopsad_campaignsratings

4.2 Column Names

  • Use snake_case
  • Primary key: id (bigint)
  • Foreign keys: {entity}_id (e.g., trip_id, user_id)
  • Timestamps: created_at, updated_at, deleted_at
  • Status fields: status (enum)

5. API Endpoints

  • Use snake_case for multi-word resources
  • Pluralize resource names
  • Use HTTP verbs correctly (GET, POST, PUT, DELETE)
  • Version prefix: /api/v1/
GET /api/v1/tripsPOST /api/v1/bookingsGET /api/v1/bookings/{id}PUT /api/v1/trips/{id}DELETE /api/v1/buses/{id}

6. Statuses and Enums

  • Internal enum values: UPPER_SNAKE_CASE
  • Arabic UI labels preserved exactly
  • Always map: Arabic → English → Enum
Arabic (UI)EnglishEnum
نشطةActiveACTIVE
غير نشطةInactiveINACTIVE
مؤكدةConfirmedCONFIRMED
ملغاهCancelledCANCELLED