إنتقل إلى المحتوى الرئيسي

📛 Naming Conventions

Consistency in naming reduces cognitive load and prevents deployment naming conflicts. BayanCore enforces the following naming patterns:

1. Git Branching​

Branch names must follow a standard prefix pattern:

CategoryBranch PrefixExample
New Featuresfeature/feature/zatca-b2b-clearance
Bug Fixesbugfix/bugfix/gosi-deduction-rounding
Security Patchessecurity/security/clerk-token-refresh
Hotfixeshotfix/hotfix/zatca-api-endpoint
Documentationdocs/docs/update-naming-rules

2. API Endpoints​

Our dual-API strategy uses distinct patterns for REST and GraphQL:

REST API v1​

  • Use plural nouns for resource endpoints: /v1/invoices, /v1/employees.
  • URL paths must be lowercase using kebab-case: /v1/purchase-orders.
  • Use standard HTTP methods:
    • GET /v1/invoices - List invoices
    • POST /v1/invoices - Draft invoice
    • GET /v1/invoices/{id} - Fetch single invoice detail
    • DELETE /v1/invoices/{id} - Anonymize/Purge record

GraphQL Schema​

  • Types: Use PascalCase (e.g. InvoiceLineItem, EmployeeProfile).
  • Queries & Mutations: Use camelCase with verb prefixes:
    • Queries: getInvoiceDetails, listTenantCompanies.
    • Mutations: createDraftInvoice, approvePurchaseOrder.

3. Database Objects (MariaDB)​

  • Tables: Lowercase snake_case, prefixed by the module name to prevent namespace clashes (e.g. hr_employee_attendance, acc_zatca_clearance_log).
  • Columns: Lowercase snake_case (e.g. is_active, vat_amount_sar).
  • Foreign Keys: Prefixed with fk_ followed by target table and column (e.g. fk_invoice_company_id).
  • Indexes: Prefixed with idx_ followed by table and columns indexed (e.g. idx_invoice_company_status).