Skip to content

Module Architecture

This document describes the architecture of custom modules in AzharStore.

Module Pattern

AzharStore uses Medusa's module pattern for extensibility. Each custom module encapsulates:

  • Data Model: Database schema definition
  • Service: Business logic and data access
  • Registration: Module configuration and initialization

Module Structure

backend/src/modules/<module-name>/
├── models/
│   └── <model-name>.ts    # Data model definition
├── service.ts              # Service class
└── index.ts                # Module registration

Custom Modules

Purpose: Manage promotional advertisements displayed on the store.

Model: advertisement - id (primary key) - title - image_url - link_url - location (home_slider, banner) - display_order - is_active - created_at

Service: AdvertisementModuleService - listActiveAdvertisements(): Filter active ads sorted by display_order

Documentation: Advertisement Module

Settings Module

Purpose: Manage application-wide configuration settings.

Model: setting - key (primary key) - value

Service: SettingsModuleService - getAllSettings(): Returns typed settings object - getSettingByKey(): Get single setting - upsertSetting(): Create or update setting - upsertManySettings(): Bulk upsert - deleteSetting(): Delete setting

Documentation: Settings Module

Translation Module

Purpose: Manage multi-language translations.

Model: translation - id (primary key) - language_code - key - value - section

Service: TranslationModuleService - getAllTranslations(): Get all translations - getTranslationsByLanguage(): Filter by language - upsertTranslation(): Create or update translation - getAllAsBundle(): i18next-compatible format

Documentation: Translation Module

Module Registration

Modules are registered in medusa-config.ts:

modules: [
  {
    resolve: "./modules/advertisement"
  },
  {
    resolve: "./modules/settings"
  },
  {
    resolve: "./modules/translation"
  }
]

Service Layer Pattern

Services extend MedusaService for automatic CRUD operations:

import { MedusaService } from "@medusajs/framework"

export class CustomModuleService extends MedusaService({ ... }) {
  // Custom methods
}

Data Access Pattern

Services use Medusa's data layer for database operations:

  • Automatic CRUD methods from MedusaService
  • Custom methods for specific business logic
  • Transaction support for complex operations

Module Dependencies

Modules can depend on each other through the service layer:

// Example: Translation service depending on settings
const languageSetting = await settingsModuleService.getSettingByKey("default_language")

Extending Modules

To add a new module:

  1. Create module directory: backend/src/modules/<module>/
  2. Define model in models/
  3. Create service extending MedusaService
  4. Export module in index.ts
  5. Register in medusa-config.ts

Module Testing

Each module should have:

  • Model validation
  • Service method tests
  • Integration tests with database

Next Steps