Skip to content

System Architecture

This document describes the detailed system architecture of AzharStore.

Component Layers

1. User Layer

The user layer consists of two main interfaces:

  • Store Frontend: React-based customer-facing application
  • Admin Dashboard: Medusa admin dashboard for store management

2. API Gateway Layer

Nginx serves as the API gateway and reverse proxy:

  • Static file serving for frontend assets
  • API request proxying to backend
  • SSL termination
  • Gzip compression
  • Caching headers

3. Backend Layer (MedusaJS v2)

The backend is organized into four layers:

API Layer

  • Store Routes: Public-facing endpoints (/store/*)
  • Admin Routes: Protected endpoints (/admin/*)
  • Core Routes: Authentication and system endpoints

Workflow Layer

  • createOrderAtomicWorkflow: 8-step order creation with compensation
  • Custom workflows for business logic

Service Layer

  • Custom Services: Advertisement, Settings, Translation
  • Core Services: Product, Customer, Order, Cart, Payment

Module Layer

  • Advertisement Module: Promotional content management
  • Settings Module: Application configuration
  • Translation Module: Multi-language support

4. Data Layer

PostgreSQL

  • Persistent data storage
  • ACID transactions
  • Relational data model

Redis

  • Event bus (Pub/Sub)
  • Caching layer
  • Session storage

Data Flow

Store Request Flow

User → Frontend → API Service → Nginx → Medusa Backend → Service → Database

Order Creation Flow

User → POST /store/orders → API Route → createOrderAtomicWorkflow → Services → Database

Admin Request Flow

Admin → Admin Dashboard → API Service → Nginx → Medusa Backend → Service → Database

Module Architecture

Custom Module Structure

Each custom module follows this pattern:

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

Module Registration

Modules are registered in medusa-config.ts:

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

Security Architecture

Authentication

  • Store: JWT token-based (optional for guests)
  • Admin: Cookie-based session authentication

Authorization

  • Store Routes: Public access
  • Admin Routes: Admin role required

Data Protection

  • Environment variables for secrets
  • Parameterized queries (SQL injection prevention)
  • CORS configuration
  • HTTPS in production

Scalability Architecture

Horizontal Scaling

  • Stateless backend design
  • Shared database and cache
  • Load balancer compatibility

Vertical Scaling

  • Database connection pooling
  • Redis clustering
  • Caching strategies

Deployment Architecture

Development

Local Machine → Docker Compose → All services in containers

Production

Load Balancer → Nginx → Backend Servers → Database Cluster → Redis Cluster

Monitoring Architecture

Logging

  • Application logs (Medusa logger)
  • Access logs (Nginx)
  • Database logs (PostgreSQL)

Health Checks

  • Backend health endpoint
  • Database connection check
  • Redis ping check

Metrics

  • Request/response times
  • Error rates
  • Database performance
  • Cache hit rates

Next Steps