Real-Time Bidirectional Integration with Cegid Primavera ERP

# Real-Time Bidirectional Integration with Cegid Primavera ERP

## Project Overview

The objective is to develop a secure, scalable, real-time bidirectional communication system between **Software.IA**, an AI-powered platform hosted on an Ubuntu VPS (Hostinger), and **Cegid Primavera ERP V10**, installed on customers' Windows servers.

The solution will use **ASP.NET Core SignalR and C#** to establish persistent communication between the cloud platform and locally installed agents.

The system must support remote ERP operations, automatic event detection, data synchronization, and real-time notifications.

## 1. System Architecture

The solution will consist of three main components.

### A. POTEIA.Server – SignalR Server

- Developed in C# using ASP.NET Core.
- Hosted on an Ubuntu VPS using Docker.
- Exposes a secure SignalR Hub over HTTPS/WSS (port 443).
- Manages simultaneous connections from multiple customer agents.
- Identifies and authenticates each customer and agent.
- Routes commands to the correct customer environment.
- Receives events and responses from connected agents.
- Integrates with the existing POTE.IA Python/FastAPI backend.

### B. POTEIA.Agent – Windows Service

- Developed in C# using .NET.
- Installed as a Windows Service on each customer's server.
- Automatically connects to the POTE.IA SignalR Server.
- Maintains a persistent bidirectional connection.
- Automatically reconnects after network interruptions.
- Integrates with Cegid Primavera ERP V10 through its SDK (BSO/DSO).
- Executes authorized commands received from POTE.IA.
- Detects and reports relevant ERP changes.
- Maintains a local persistent event queue when the cloud server is unavailable.

### C. POTE.IA – AI Platform

- Developed in Python using FastAPI.
- Communicates with the SignalR Server through an internal API.
- Sends ERP commands to specific customer agents.
- Receives structured JSON responses.
- Processes ERP events in real time.
- Uses AI to interpret user requests and trigger authorized ERP operations.

## 2. Bidirectional Communication

### POTE.IA → Primavera ERP

The AI platform must be able to request operations such as:

- Retrieve customer information and account balances.
- Retrieve sales invoices and purchase documents.
- Check stock availability and warehouse inventory.
- Retrieve sales orders and order statuses.
- Execute predefined SQL queries and stored procedures.
- Create or update ERP records through authorized Primavera SDK operations.
- Retrieve accounting and financial information.

Each command must include a unique request identifier, customer identification, command type, parameters, and appropriate authorization information.

### Primavera ERP → POTE.IA

The local agent must automatically detect and report events such as:

- New sales invoice created.
- Sales order created or updated.
- Customer information modified.
- Stock quantity changed.
- Payment or receipt registered.
- Purchase document created.
- Accounting entry registered or updated.

Event detection should use Primavera extensibility mechanisms where available, supplemented by SQL Server Change Data Capture (CDC), an outbox mechanism, or periodic synchronization when appropriate.

## 3. Example Command

POTE.IA sends:

```json
{
"request_id": "REQ-10001",
"organization": "CUSTOMER_A",
"command": "GET_CUSTOMER_BALANCE",
"parameters": {
"customer": "0001"
}
}
```

The Windows agent executes the authorized operation using the Primavera SDK and returns:

```json
{
"request_id": "REQ-10001",
"success": true,
"data": {
"customer": "0001",
"balance": 12500.75,
"currency": "EUR"
}
}
```

## 4. Example ERP Event

When a new invoice is created, the agent sends:

```json
{
"event_id": "EVT-10001",
"organization": "CUSTOMER_A",
"event": "INVOICE_CREATED",
"module": "SALES",
"document": {
"type": "FA",
"series": "2026",
"number": 1523,
"customer": "0001",
"total": 1250.00
}
}
```

POTE.IA receives the event and can automatically update dashboards, synchronize external systems, execute business rules, or generate AI-powered notifications.

## 5. Security Requirements

The system must implement:

- Encrypted communication using TLS.
- Authentication for each Windows agent.
- Customer-specific authorization and data isolation.
- Secure storage of credentials.
- Command allowlisting and parameter validation.
- Protection against arbitrary SQL execution.
- Audit logging of commands and events.
- Request timeouts and error handling.
- Duplicate event detection and idempotent processing.

Each customer agent must only receive commands explicitly authorized for its organization.

## 6. Reliability and Event Management

The system must support:

- Automatic SignalR reconnection.
- Agent online/offline status monitoring.
- Persistent local event storage.
- Retry mechanisms for failed transmissions.
- Server-side acknowledgement of processed events.
- Recovery of pending events after reconnection.
- Unique event and request identifiers.
- Prevention of duplicate processing.

Events must not be marked as successfully delivered until the server confirms durable receipt or processing.

## 7. Development Requirements

Create a Visual Studio solution containing:

**POTEIA.Server**
- ASP.NET Core SignalR Hub.
- Agent authentication and connection management.
- Command routing.
- Event reception.
- Internal API for Python/FastAPI integration.
- Docker configuration for Ubuntu deployment.

**POTEIA.Agent**
- .NET Windows Worker Service.
- SignalR client.
- Automatic reconnection.
- Primavera ERP V10 integration layer.
- Command execution service.
- ERP event detection.
- Local event queue.
- Structured logging.
- Configuration file for customer and server settings.

The solution must be modular, maintainable, and designed to support multiple customer installations.

## 8. Expected Deliverables

1. Complete C# Visual Studio solution with source code.
2. Functional ASP.NET Core SignalR server.
3. Windows Service agent installer or deployment package.
4. Integration interfaces for Primavera ERP V10.
5. Example commands and ERP event handlers.
6. Python/FastAPI integration examples.
7. Docker deployment configuration.
8. Security and configuration documentation.
9. Installation and deployment instructions.
10. End-to-end communication tests.

## 9. Final Objective

Build a reliable, secure, multi-tenant communication infrastructure that allows **POTE.IA to interact with multiple Cegid Primavera ERP installations in real time**, without requiring inbound firewall ports or direct public access to customer databases.

The platform must support both on-demand ERP operations initiated by POTE.IA and automatic event notifications originating from Primavera ERP.

The architecture should be suitable for future expansion into additional ERP modules, automated accounting processes, document processing, and AI-driven business workflows.