# iPaaS Architecture Documentation

This directory contains architecture documentation for the SuiteX iPaaS (Integration Platform as a Service) module.

---

## 📂 Directory Structure

```
ipaas/
├── README.md                               # This file
├── api_retry_backoff.md                    # API retry and backoff strategy
├── connector-authorization-system.md       # Connector OAuth/auth implementation
├── flow-node-id-refactoring-proposal.md    # Proposed improvement for node ID structure
├── flow_notifications.md                   # Flow execution notifications
├── form-fields-mapping.md                  # Form field mapping documentation
├── ipass_overview.md                       # High-level iPaaS overview
├── middleware-implementation.md            # Middleware architecture
├── security-progress.md                    # Security improvements tracking
├── structure-analysis.md                   # Module structure analysis
└── refactoring/                            # Refactoring summaries
    ├── branch-node-summary.md              # Branch node refactoring
    ├── connector-form-alpine.md            # Connector form Alpine.js migration
    ├── connector-summary.md                # General connector refactoring
    └── nodes-controllers-summary.md        # Node controllers refactoring
```

---

## 🎯 Core Concepts

### iPaaS Module

The iPaaS module provides integration capabilities between SuiteX and external systems through:

- **Flows**: Visual workflow builder for data integration
- **Connectors**: OAuth/API connections to external services
- **Nodes**: Processing units (API, Map, Transform, Branch)
- **Scheduling**: Cron-based flow execution

### Key Components

1. **Flow Builder** (`resources/js/components/flows/`)
   - React Flow-based visual editor
   - Drag-and-drop node creation
   - Real-time flow execution

2. **Node Types**
   - **API Node**: HTTP requests to external APIs
   - **Map Node**: Data transformation/mapping
   - **Transform Node**: JavaScript-based data manipulation
   - **Branch Node**: Conditional flow routing

3. **Connectors**
   - OAuth1/OAuth2 authentication
   - Credential encryption
   - Multi-tenant isolation

---

## 📖 Documentation Guide

### For New Developers

Start with these documents in order:

1. [iPaaS Overview](./ipass_overview.md) - High-level architecture
2. [Structure Analysis](./structure-analysis.md) - Code organization
3. [Middleware Implementation](./middleware-implementation.md) - Security layer

### For Architecture Changes

Review these before making structural changes:

1. [Flow Node ID Refactoring Proposal](./flow-node-id-refactoring-proposal.md) - Proposed improvements
2. [Security Progress](./security-progress.md) - Current security state
3. [Refactoring Summaries](./refactoring/) - Previous refactorings

### For Integration Work

Reference these for connector/API work:

1. [Connector Authorization System](./connector-authorization-system.md)
2. [API Retry & Backoff](./api_retry_backoff.md)
3. [Form Fields Mapping](./form-fields-mapping.md)

---

## 🔒 Security

All iPaaS operations require the `can_manage_ipass` permission. Key security features:

- **FormRequest validation**: All inputs validated via FormRequests
- **Encrypted credentials**: Connector credentials encrypted at rest
- **Tenant isolation**: Multi-tenant database separation
- **CSRF protection**: All state-changing operations protected

See [Security Progress](./security-progress.md) for detailed security audit.

---

## 🏗️ Architecture Patterns

### Domain-Driven Design (DDD)

The iPaaS module follows DDD principles:

```
src/
├── Domain/Ipaas/           # Domain layer (business logic)
│   ├── Flows/
│   ├── Nodes/
│   ├── Connectors/
│   └── ...
└── App/                    # Application layer (HTTP, UI)
    ├── Http/Controllers/Ipaas/
    ├── Http/Requests/Ipaas/
    └── Livewire/Ipaas/
```

### Actions Pattern

Business logic encapsulated in Action classes:

```php
// Domain/Ipaas/Flows/Actions/CreateFlow.php
class CreateFlow {
    public static function create(array $input): Flow {
        // Pure domain logic
        // Returns model or throws exception
    }
}
```

### FormRequest Validation

All user input validated via FormRequests:

```php
// App/Http/Requests/Ipaas/Flow/FlowRequest.php
class FlowRequest extends FormRequest {
    public function authorize(): bool { /* ... */ }
    public function rules(): array { /* ... */ }
}
```

---

## 🔄 Recent Refactorings

### Completed

- ✅ **Livewire → Alpine.js + HTTP Pattern** (2025-11-18)
  - Migrated TransformNodeForm, MapNodeForm, ApiNodeForm
  - See [refactoring summaries](./refactoring/)

- ✅ **Connector Form Security** (2025-11)
  - Implemented comprehensive FormRequest validation
  - See [Connector Authorization System](./connector-authorization-system.md)

- ✅ **Node Controllers Standardization** (2025-11)
  - RESTful conventions
  - DDD pattern enforcement
  - See [Node Controllers Summary](./refactoring/nodes-controllers-summary.md)

### Proposed

- ⏳ **Flow Node ID Refactoring** (Proposed)
  - Simplify node ID structure
  - Use DB connection fields
  - See [Flow Node ID Refactoring Proposal](./flow-node-id-refactoring-proposal.md)

---

## 🧪 Testing

iPaaS tests follow established patterns:

- **Feature Tests**: Controller endpoints (`tests/Feature/Http/Controllers/Ipaas/`)
- **Unit Tests**: Domain Actions (`tests/Unit/Domain/Ipaas/`)
- **Database**: File-based SQLite for tests
- **Multi-tenancy**: `SetupMultiTenancyForTests` trait

See `docs/AI/ai_tests.md` for testing guidelines.

---

## 🔗 Related Documentation

- [API Architecture](../api/api-structure.md)
- [Security Policy](../security/form-validation-policy.md)
- [Database Connection Safety](../database/connection-pool-safety.md)
- [Import Queue](../import/queue-setup.md)

---

## 📝 Contributing

When adding new documentation:

1. Place architectural docs in `docs/architecture/ipaas/`
2. Place refactoring summaries in `docs/architecture/ipaas/refactoring/`
3. Use `kebab-case.md` naming convention
4. Update this README with links to new docs
5. Add entry to "Change Log" below

---

## 📅 Change Log

| Date | Document | Change |
|------|----------|--------|
| 2025-11-18 | `flow-node-id-refactoring-proposal.md` | Added proposal for node ID simplification |
| 2025-11-18 | `README.md` | Created iPaaS architecture index |
| 2025-11-18 | `refactoring/*.md` | Organized refactoring summaries |

---

## 🤝 Maintainers

For questions or clarifications on iPaaS architecture:

- Review this documentation first
- Check related documents in parent directories
- Refer to `docs/AI/ai_rules.md` for coding standards