AzharStore Architecture Documentation¶
This document describes the overall architecture of the AzharStore Medusa backend system.
System Overview¶
AzharStore is built on MedusaJS v2, a modular e-commerce framework. The system consists of:
- Backend: MedusaJS v2 with custom modules
- Database: PostgreSQL 16
- Cache/Event Bus: Redis 7
- Frontend: React-based store
- Reverse Proxy: Nginx
Architecture Diagram¶
┌─────────────────────────────────────────────────────────────────┐
│ User Layer │
├─────────────────────────────────────────────────────────────────┤
│ Store Frontend (React) │ Admin Dashboard (Medusa Admin) │
│ Port 3000 │ Port 9000/app │
└────────────┬────────────────────────────────┬───────────────────┘
│ │
│ HTTP/HTTPS │ HTTP/HTTPS
│ │
┌────────────▼────────────────────────────────▼───────────────────┐
│ Nginx (Port 80/443) │
│ - Static file serving │
│ - API proxying │
│ - SSL termination │
└────────────┬─────────────────────────────────────────────────────┘
│
│ Proxy /api/* to backend
│
┌────────────▼─────────────────────────────────────────────────────┐
│ MedusaJS v2 Backend (Port 9000) │
├─────────────────────────────────────────────────────────────────┤
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ API Layer │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ Store Routes │ │ Admin Routes │ │ Core Routes │ │ │
│ │ │ /store/* │ │ /admin/* │ │ /auth/* │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ └───────────────────────────────────────────────────────────┘ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Workflow Layer │ │
│ │ ┌───────────────────────────────────────────────────┐ │ │
│ │ │ createOrderAtomicWorkflow │ │ │
│ │ │ - Validate Stock → Create Cart → Add Items │ │ │
│ │ │ - Update Address → Add Shipping → Payment Session │ │ │
│ │ │ - Complete Cart → Capture Payment │ │ │
│ │ └───────────────────────────────────────────────────┘ │ │
│ └───────────────────────────────────────────────────────────┘ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Service Layer │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ Advertisement│ │ Settings │ │ Translation │ │ │
│ │ │ Service │ │ Service │ │ Service │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ Product │ │ Customer │ │ Order │ │ │
│ │ │ Service │ │ Service │ │ Service │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ └───────────────────────────────────────────────────────────┘ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Module Layer │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ Advertisement│ │ Settings │ │ Translation │ │ │
│ │ │ Module │ │ Module │ │ Module │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ └───────────────────────────────────────────────────────────┘ │
└────────────┬─────────────────────────────────────────────────────┘
│
│ SQL
│
┌────────────▼─────────────────────────────────────────────────────┐
│ PostgreSQL (Port 5432) │
├─────────────────────────────────────────────────────────────────┤
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ advertisement │ │ setting │ │ translation │ │
│ │ table │ │ table │ │ table │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ product │ │ customer │ │ order │ │
│ │ table │ │ table │ │ table │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
│ TCP
│
┌────────────▼─────────────────────────────────────────────────────┐
│ Redis (Port 6379) │
├─────────────────────────────────────────────────────────────────┤
│ - Event Bus (Pub/Sub) │
│ - Caching Layer │
│ - Session Storage │
└─────────────────────────────────────────────────────────────────┘
Component Details¶
Backend (MedusaJS v2)¶
API Layer¶
The API layer handles incoming HTTP requests and routes them to appropriate handlers:
- Store Routes (
/store/*): Public-facing endpoints for store operations - Custom endpoints:
/store/advertisements,/store/settings,/store/translations,/store/orders -
Core endpoints: Products, cart, checkout, auth
-
Admin Routes (
/admin/*): Protected endpoints for admin operations - Custom endpoints:
/admin/advertisements,/admin/settings,/admin/translations - Core endpoints: Products, customers, orders, settings
Workflow Layer¶
Workflows define business logic with atomic operations and compensation:
- createOrderAtomicWorkflow: 8-step order creation process
- Each step can be compensated on failure
- Ensures data consistency across operations
Service Layer¶
Services contain business logic and data access:
- Custom Services: Advertisement, Settings, Translation
- Core Services: Product, Customer, Order, Cart, Payment
Module Layer¶
Modules encapsulate domain-specific functionality:
- Advertisement Module: Manages promotional content
- Settings Module: Manages application configuration
- Translation Module: Manages multi-language content
Database (PostgreSQL)¶
PostgreSQL stores all persistent data:
Custom Tables:
- advertisement: Promotional content
- setting: Application settings
- translation: Multi-language translations
Core Tables:
- product: Product catalog
- customer: Customer information
- order: Order records
- cart: Shopping cart data
Cache (Redis)¶
Redis provides:
- Event Bus: Pub/Sub for real-time events
- Caching: Frequently accessed data
- Session Storage: User session data
Frontend (React)¶
The store frontend communicates with the backend via REST API:
- API Adapter:
frontend/store/src/services/api.js - State Management: React hooks/context
- Routing: React Router
Reverse Proxy (Nginx)¶
Nginx serves as:
- Static File Server: Serves built frontend assets
- API Proxy: Forwards API requests to backend
- SSL Termination: Handles HTTPS encryption
Data Flow¶
Store Frontend Request Flow¶
1. User Action → Frontend Component
2. Component → API Service (api.js)
3. API Service → HTTP Request (axios)
4. HTTP Request → Nginx
5. Nginx → Medusa Backend
6. Backend → Service Layer
7. Service Layer → Database/Cache
8. Database/Cache → Service Layer
9. Service Layer → Backend
10. Backend → Nginx
11. Nginx → API Service
12. API Service → Component
13. Component → UI Update
Order Creation Flow¶
1. User submits order → POST /store/orders
2. API route validates input
3. createOrderAtomicWorkflow starts
4. Step 1: Validate stock
5. Step 2: Create cart
6. Step 3: Add line items
7. Step 4: Update cart address
8. Step 5: Add shipping method
9. Step 6: Create payment session
10. Step 7: Complete cart
11. Step 8: Capture payment
12. Return order to client
Admin Data Management Flow¶
1. Admin logs in → /app/login
2. Admin Dashboard loads
3. Admin navigates to custom page (e.g., Advertisements)
4. React component fetches data via API
5. API route calls module service
6. Service queries database
7. Data returned to component
8. Component displays data in table
9. Admin performs CRUD operation
10. API route handles request
11. Service updates database
12. Component refreshes data
Module Architecture¶
Custom Module Structure¶
Each custom module follows this structure:
backend/src/modules/<module-name>/
├── models/
│ └── <model-name>.ts # Data model definition
├── service.ts # Service class with business logic
└── index.ts # Module registration
Module Registration¶
Modules are registered in medusa-config.ts:
modules: [
{
resolve: "@medusajs/medusa/cache-redis",
options: { redisUrl: process.env.REDIS_URL }
},
{
resolve: "./modules/advertisement"
},
{
resolve: "./modules/settings"
},
{
resolve: "./modules/translation"
}
]
Security Architecture¶
Authentication¶
- Store: JWT token-based authentication (optional for guest users)
- Admin: Cookie-based session authentication
Authorization¶
- Store Routes: Public access, optional auth
- Admin Routes: Require admin session
Data Protection¶
- Environment variables for secrets
- SQL injection prevention via parameterized queries
- CORS configuration for cross-origin requests
- HTTPS in production
Scalability Considerations¶
Horizontal Scaling¶
- Stateless backend design
- Shared database and cache
- Load balancer can distribute requests
Vertical Scaling¶
- Database connection pooling
- Redis clustering for high throughput
- Caching frequently accessed data
Performance Optimization¶
- Database indexes on frequently queried fields
- Redis caching for translations and settings
- Nginx static file caching
- CDN for static assets (production)
Deployment Architecture¶
Development Environment¶
┌─────────────────────────────────────┐
│ Local Machine │
│ - Docker Compose │
│ - All services in containers │
│ - Hot reload enabled │
└─────────────────────────────────────┘
Production Environment¶
┌─────────────────────────────────────┐
│ Production Server │
│ - Docker Compose or Kubernetes │
│ - Separate database server │
│ - Redis cluster │
│ - Load balancer │
│ - SSL/TLS termination │
│ - Monitoring and logging │
└─────────────────────────────────────┘
Technology Stack¶
| Component | Technology | Version |
|---|---|---|
| Backend Framework | MedusaJS | v2 |
| Language | TypeScript | Latest |
| Runtime | Node.js | >=20 |
| Database | PostgreSQL | 16 Alpine |
| Cache | Redis | 7 Alpine |
| Frontend | React | Latest |
| Build Tool | Vite | Latest |
| Reverse Proxy | Nginx | Latest |
| Containerization | Docker | Latest |
| Orchestration | Docker Compose | Latest |
Design Patterns¶
Module Pattern¶
Custom modules encapsulate domain logic and data models, following Medusa's module system for extensibility.
Service Layer Pattern¶
Services contain business logic and provide a clean API for controllers and workflows.
Workflow Pattern¶
Workflows define multi-step operations with atomic execution and compensation for reliability.
Repository Pattern¶
Data access is abstracted through services, which use Medusa's built-in data layer.
Dependency Injection¶
Services and modules are resolved through Medusa's dependency injection container.
Event-Driven Architecture¶
Medusa uses an event-driven architecture with Redis as the event bus:
- Events are published for domain actions (order created, product updated)
- Subscribers listen for events and trigger side effects
- Enables decoupling of components
API Design Principles¶
RESTful Design¶
- Resource-based URLs
- HTTP methods for actions (GET, POST, PATCH, DELETE)
- Standard HTTP status codes
- JSON request/response format
Versioning¶
- API versioning via URL path (e.g.,
/store/v1/...) - Backward compatibility maintained where possible
Error Handling¶
- Consistent error response format
- Appropriate HTTP status codes
- Detailed error messages for debugging
Monitoring and Observability¶
Logging¶
- Application logs via Medusa logger
- Access logs via Nginx
- Database logs via PostgreSQL
Metrics¶
- Request/response times
- Error rates
- Database query performance
- Cache hit rates
Health Checks¶
- Backend health endpoint
- Database connection check
- Redis connection check
Future Enhancements¶
Potential Improvements¶
- Message Queue: Add RabbitMQ or Kafka for async processing
- Search Engine: Add Elasticsearch for product search
- File Storage: Add S3-compatible storage for images
- CDN: Add CDN for static assets
- Analytics: Add analytics tracking
- A/B Testing: Add feature flags for A/B testing
- Webhooks: Add webhook support for integrations
- GraphQL: Add GraphQL API alongside REST