# ERPFlow Module Development Standard

## 1. Core Principle

ERPFlow is a modular ERP platform.

A module must be independently understandable, maintainable, and replaceable where practical.

---

## 2. Module Boundary

A module owns its:

- Domain logic
- Controllers
- Requests
- Services
- Repositories
- Models
- Resources
- DTOs
- Events
- Jobs
- Policies
- Routes
- Configuration
- Migrations where applicable

Do not place module-specific business logic inside the core framework.

---

## 3. Dependency Direction

Prefer:

```text
Core
 ↑
Platform
 ↑
Module
```

A module should not tightly depend on unrelated modules' internal implementation.

---

## 4. Cross-Module Communication

When one module needs another module:

Prefer:

- Contracts
- Interfaces
- Events
- Explicit application services
- Stable public APIs

Avoid:

- Accessing another module's internal repositories directly
- Accessing another module's private implementation
- Copying business logic

---

## 5. Configuration

Module behavior should be configurable where business requirements justify it.

Examples:

- Enable/disable module
- Actions
- Permissions
- Menus
- Settings
- Workflow definitions
- Notification templates

Avoid hardcoding module behavior unnecessarily.

---

## 6. Module Registration

A module should have a predictable registration mechanism.

Registration may include:

- Service provider
- Routes
- Configuration
- Permissions
- Menus
- Events
- Migrations

---

## 7. Module Naming

Use consistent naming:

```text
HR
Attendance
Payroll
RBAC
Approval
ProjectManagement
Commission
```

---

## 8. Module Independence

Do not create circular dependencies.

Bad:

```text
Payroll → HR → Payroll
```

If circular dependency appears, introduce:

- Shared contract
- Core abstraction
- Event
- Application-level coordinator

---

## 9. New Module Checklist

Before creating a module:

- [ ] Define responsibility
- [ ] Define boundaries
- [ ] Define entities
- [ ] Define dependencies
- [ ] Define permissions
- [ ] Define routes
- [ ] Define workflows
- [ ] Define events/jobs
- [ ] Define tests
- [ ] Define configuration

---

## 10. Core Framework Protection

Never modify core framework behavior merely to solve a single module's business requirement.

If a module needs special behavior:

First consider:

```text
Extension point
Contract
Configuration
Plugin
Event
Module service
```

before changing the core.