# 05-folder-architecture.md

# Laravel Folder Architecture (Scalable + Clean + Production Ready)

**Version:** 1.0
**Project Type:** Single Vendor eCommerce
**Architecture Style:** Modular + Service Based + AI Friendly
**Framework:** Laravel (Latest Recommended Version)

---

## 1. ARCHITECTURE GOAL

This architecture is designed to ensure:

- Clean separation of business logic
- Easy scaling for large traffic
- AI-friendly code generation (Claude friendly)
- Independent modules (plug & play style)
- Easy maintenance by multiple developers
- Ready for future API / Mobile App / Admin expansion

---

## 2. CORE ARCHITECTURE PRINCIPLE

We will **NOT** use messy MVC-only structure.

We will use:

### Hybrid Modular Architecture

Combination of:

- Modular Structure (Feature-based)
- Service Layer Pattern
- Repository Pattern (optional but recommended)
- DTO / Request Validation Layer
- Event Driven System (for orders, payments)

---

## 3. ROOT PROJECT STRUCTURE

```
app/
bootstrap/
config/
database/
public/
resources/
routes/
storage/
tests/
Modules/
```

---

## 4. MAIN BUSINESS MODULE STRUCTURE

All business logic goes inside:

```
Modules/
```

Each module is **independent**.

---

## 5. MODULE STRUCTURE STANDARD

Every module follows this structure:

```
Modules/
 ├── Product/
 │    ├── Controllers/
 │    ├── Models/
 │    ├── Services/
 │    ├── Repositories/
 │    ├── Requests/
 │    ├── Resources/
 │    ├── DTO/
 │    ├── Events/
 │    ├── Listeners/
 │    ├── Routes/
 │    └── ProductServiceProvider.php
```

---

## 6. MODULE LIST (FULL SYSTEM BREAKDOWN)

### 6.1 Core Modules

- Product Module
- Category Module
- Brand Module
- Order Module
- Customer Module (Guest based)
- Payment Module
- Inventory Module

### 6.2 Admin Modules

- Admin Module
- Role & Permission Module
- Dashboard Module
- Report Module
- Settings Module
- Activity Log Module

### 6.3 Marketing Modules

- Coupon Module
- Flash Sale Module
- Offer Module
- Popup Campaign Module
- Banner Module

### 6.4 CMS Modules

- Page Module
- Blog Module
- FAQ Module
- Menu Module

### 6.5 Logistics Modules

- Courier Module
- Shipment Module
- Tracking Module

### 6.6 Accounting Modules

- Expense Module
- Income Module
- Profit/Loss Module
- Transaction Ledger Module

---

## 7. LARAVEL CORE FOLDER STRUCTURE

### 7.1 Controllers

Only **thin controllers**:

```
app/Http/Controllers/
```

Used only for:

- Request receiving
- Calling service layer
- Returning response

> ❌ No business logic here.

---

### 7.2 Services Layer _(VERY IMPORTANT)_

```
app/Services/
```

**Examples:**

```
OrderService.php
ProductService.php
PaymentService.php
ReportService.php
```

**Purpose:** All business logic stays here.

---

### 7.3 Repository Layer _(DATA ACCESS)_

```
app/Repositories/
```

**Examples:**

```
ProductRepository.php
OrderRepository.php
```

**Purpose:**

- Database queries isolated
- Easy optimization
- Easy switching DB logic later

---

### 7.4 Models _(Lightweight Only)_

```
app/Models/
```

Only contains:

- relationships
- fillable
- casts
- scopes

> ❌ No business logic
> ❌ No heavy queries

---

### 7.5 Requests _(Validation Layer)_

```
app/Http/Requests/
```

**Examples:**

```
StoreProductRequest.php
CheckoutRequest.php
```

**Purpose:**

- Input validation
- Security protection
- Clean controller

---

### 7.6 DTO Layer _(Data Transfer Objects)_

```
app/DTO/
```

**Examples:**

```
OrderDTO.php
ProductDTO.php
```

**Purpose:**

- Clean structured data between layers
- AI friendly architecture

---

### 7.7 Events & Listeners _(IMPORTANT FOR SCALABILITY)_

```
app/Events/
app/Listeners/
```

**Example flow:**

```
OrderPlaced Event →
    - Reduce stock
    - Send SMS
    - Generate invoice
    - Send courier request
```

---

### 7.8 Jobs _(Queue System)_

```
app/Jobs/
```

Used for:

- Sending SMS
- Sending email
- Courier API request
- Report generation
- Image processing

---

### 7.9 Notifications

```
app/Notifications/
```

Used for:

- Order confirmation SMS/email
- Delivery updates
- Admin alerts

---

### 7.10 Traits _(Reusable Logic)_

```
app/Traits/
```

**Examples:**

```
ResponseTrait
UploadTrait
PricingTrait
```

---

### 7.11 Helpers

```
app/Helpers/
```

**Examples:**

```
format_price()
generate_invoice_no()
```

---

## 8. ROUTES STRUCTURE

### 8.1 API Routes

```
routes/api.php
```

Used for:

- Frontend API
- Mobile app API
- AJAX calls

### 8.2 Web Routes

```
routes/web.php
```

Used for:

- Frontend pages
- Admin panel routes

### 8.3 Module Routes _(IMPORTANT)_

Each module has own routes:

```
Modules/Product/Routes/web.php
Modules/Order/Routes/web.php
```

Then auto-loaded via Service Provider.

---

## 9. SERVICE PROVIDER STRUCTURE

Each module has:

```
ProductServiceProvider.php
```

**Responsibilities:**

- Load routes
- Bind services
- Register dependencies

---

## 10. ADMIN PANEL STRUCTURE

```
resources/views/admin/
```

```
admin/
 ├── dashboard/
 ├── products/
 ├── orders/
 ├── customers/
 ├── reports/
 ├── settings/
 ├── marketing/
 └── courier/
```

---

## 11. FRONTEND STRUCTURE

```
resources/views/frontend/
```

```
frontend/
 ├── pages/
 ├── product/
 ├── cart/
 ├── checkout/
 ├── components/
 └── layouts/
```

---

## 12. PERFORMANCE STRUCTURE

### Cache Layer

**Use:**

- Redis (recommended)
- Laravel cache system

**Cache:**

- Settings
- Homepage sections
- Product listing
- Categories

---

## 13. EVENT FLOW EXAMPLE (ORDER SYSTEM)

```
User places order
 → OrderController
 → OrderService
 → Save order
 → Fire OrderPlaced Event
 → Listeners:
      ├── ReduceStock
      ├── SendSMS
      ├── GenerateInvoice
      └── SendCourierRequest
```

---

## 14. SCALABILITY RULES

### ✅ MUST FOLLOW:

| Layer          | Responsibility       |
|----------------|----------------------|
| Controllers    | Thin — receive only  |
| Services       | Brain — all logic    |
| Repository     | DB layer only        |
| Events         | Async operations     |
| Jobs           | Heavy tasks          |

---

## 15. AI FRIENDLY DESIGN _(IMPORTANT)_

This architecture is designed so that **Claude / AI** can easily:

- Generate modules
- Understand structure
- Extend features
- Debug easily

---

## 16. FINAL GOAL

This folder architecture ensures:

- ✅ Clean Laravel codebase
- ✅ No messy logic
- ✅ Easy scaling
- ✅ Production-grade performance
- ✅ Future mobile app readiness