# 09-backend-module-plan.md

# Backend Module Plan (Laravel Modular Architecture)

**Version:** 1.0
**Project Type:** Single Vendor eCommerce
**Architecture:** Modular + Service Layer + Event Driven

---

## 1. PURPOSE OF THIS DOCUMENT

This file defines:

- How backend will be divided into modules
- Responsibilities of each module
- Internal structure of each module
- Inter-module communication rules

**Goal:** Each feature must be isolated, scalable, and AI-readable.

---

## 2. CORE PRINCIPLE

We are **NOT** building a monolithic messy Laravel app.

We are building:

### Modular Business System

Each module:

- Has its own logic
- Has its own routes
- Has its own services
- Can be developed independently
- Can be extended later

---

## 3. MAIN MODULE LIST (SYSTEM OVERVIEW)

### Core Business Modules

1. Product Module
2. Category Module
3. Brand Module
4. Order Module
5. Customer Module (Guest-based)
6. Cart Module
7. Checkout Module
8. Payment Module
9. Inventory Module

---

### Business Control Modules

10. Admin Module
11. Role & Permission Module
12. Dashboard Module
13. Settings Module
14. Report Module
15. Activity Log Module

---

### Marketing Modules

16. Coupon Module
17. Flash Sale Module
18. Offer Module
19. Banner Module
20. Popup Campaign Module

---

### CMS Modules

21. Page Module
22. Blog Module
23. FAQ Module
24. Menu Module

---

### Logistics Modules

25. Courier Module
26. Shipment Module
27. Tracking Module

---

### Accounting Modules

28. Expense Module
29. Income Module
30. Profit/Loss Module
31. Transaction Ledger Module

---

## 4. MODULE INTERNAL STRUCTURE STANDARD

Each module follows this structure:

```
Modules/
 ├── Order/
 │    ├── Controllers/
 │    ├── Services/
 │    ├── Repositories/
 │    ├── Models/
 │    ├── Requests/
 │    ├── DTO/
 │    ├── Events/
 │    ├── Listeners/
 │    ├── Jobs/
 │    ├── Routes/
 │    ├── Resources/
 │    └── OrderServiceProvider.php
```

---

## 5. MODULE RESPONSIBILITY BREAKDOWN

---

### 5.1 PRODUCT MODULE

**Responsibilities:**

- Product CRUD
- Product variants
- Product pricing
- Product images
- SEO management
- Product stock handling

**Business Logic:**

- Stock validation
- Price calculation
- Discount handling
- Product status control

---

### 5.2 CATEGORY MODULE

**Responsibilities:**

- Category tree system
- Nested categories
- Category SEO
- Category visibility control

---

### 5.3 ORDER MODULE _(CORE SYSTEM)_

**Responsibilities:**

- Order creation
- Order lifecycle
- Status tracking
- Invoice generation
- Order validation

**Business Flow:**

```
Cart → Checkout → Order Created → Events Triggered → Stock Reduce → Notification → Courier Sync
```

---

### 5.4 CUSTOMER MODULE _(GUEST SYSTEM)_

**Responsibilities:**

- Phone-based customer tracking
- Order history grouping
- VIP tagging
- Fraud detection
- Repeat customer identification

---

### 5.5 CHECKOUT MODULE

**Responsibilities:**

- Validate cart
- Validate address
- Apply coupon
- Calculate total
- Create order
- Clear cart

---

### 5.6 PAYMENT MODULE

**Responsibilities:**

- COD handling
- Payment verification (future)
- Payment logs
- Refund handling

---

### 5.7 INVENTORY MODULE

**Responsibilities:**

- Stock management
- Stock movements
- Purchase stock
- Damage stock
- Low stock alert

---

### 5.8 ADMIN MODULE

**Responsibilities:**

- Admin authentication
- Admin dashboard
- Admin activity handling

---

### 5.9 ROLE & PERMISSION MODULE

**Responsibilities:**

- Role creation
- Permission assignment
- Access control

---

### 5.10 DASHBOARD MODULE

**Responsibilities:**

- Business analytics
- Charts
- KPIs

**KPIs tracked:**

| KPI       | Description              |
|-----------|--------------------------|
| Sales     | Total revenue            |
| Profit    | Net profit               |
| Orders    | Total order count        |
| Expenses  | Total expense tracking   |

---

### 5.11 REPORT MODULE

**Responsibilities:**

- Daily report
- Monthly report
- Profit report
- Product performance report

---

### 5.12 SETTINGS MODULE

**Responsibilities:**

- Website settings
- Theme settings
- Homepage control
- Feature toggle system

---

### 5.13 MARKETING MODULES

#### Coupon Module

- Discount logic
- Coupon validation
- Usage tracking

#### Flash Sale Module

- Time-based discount
- Product mapping

#### Popup Module

- Campaign display logic
- Conversion tracking

---

### 5.14 CMS MODULE

**Responsibilities:**

- Static pages
- Blog system
- FAQ system
- Menu builder

---

### 5.15 COURIER MODULE

**Responsibilities:**

- Courier API integration
- Shipment creation
- Tracking sync
- Delivery status update

**Supported couriers:**

- SteadFast
- Pathao
- RedX
- Paperfly
- eCourier

---

### 5.16 ACCOUNTING MODULE

**Responsibilities:**

- Expense tracking
- Income tracking
- Profit/Loss calculation
- Transaction ledger

---

## 6. EVENT DRIVEN ARCHITECTURE _(VERY IMPORTANT)_

**Example Flow:**

```
OrderPlaced Event →
    ├── ReduceStock Listener
    ├── SendSMS Listener
    ├── CreateShipment Job
    └── GenerateInvoice Job
```

---

## 7. SERVICE LAYER RULE

Every module **MUST** use Service Layer.

**Examples:**

```
OrderService
ProductService
PaymentService
```

> ❌ Controller never contains business logic.

---

## 8. REPOSITORY LAYER RULE _(OPTIONAL BUT RECOMMENDED)_

Used for DB operations:

```
ProductRepository
OrderRepository
```

**Benefits:**

- Clean queries
- Easy optimization
- Easy DB switching

---

## 9. JOB SYSTEM _(QUEUE SYSTEM)_

Used for heavy tasks:

- SMS sending
- Email sending
- Courier API calls
- Report generation
- Image processing

---

## 10. MODULE COMMUNICATION RULE

Modules **never** talk directly to each other.

They communicate via:

- Events
- Services
- Jobs

**Example:**

```
Order Module → emits event → Inventory Module listens
```

---

## 11. SCALABILITY DESIGN

This structure allows:

- Adding new modules easily
- Removing modules safely
- Scaling independent features
- Future microservice migration

---

## 12. AI (CLAUDE) FRIENDLY DESIGN

This architecture ensures:

- Each module is isolated
- Clear responsibilities
- Easy code generation
- No dependency confusion

---

## 13. FINAL GOAL

This backend module plan ensures:

- ✅ Clean enterprise-level Laravel structure
- ✅ Fully scalable architecture
- ✅ Easy AI-based development
- ✅ Production-grade system design