> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wavecentric.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Connectivity

> Data lifecycle and entity relationships

## 1. The Operational Lifecycle: Life of a Booking

The application tracks the lifecycle of an intermodal transport mandate from its inception as a commercial agreement to its closure and archival.

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant B as Booking
    participant P as Planning
    participant E as Execution
    participant M as Monitoring
    participant A as Admin

    Note over B, A: Master Data Validated (Subjects, Nodes, Matrix)
    B->>P: New Booking Created (Customer, Route, UTI Type)
    Note right of P: Validation: Is UTI type compatible with Wagon?
    P->>P: Assign specific Wagon & position
    P->>E: Handover to Live Operations
    Note right of E: Status: PRONTO (Ready)
    E->>M: Trigger Gate-In Event
    M-->>E: Update: ARRIVATO (Arrived at Terminal)
    Note right of E: Status: CARICATO (Loaded)
    E->>E: Generate documents (CIM/Bill of Lading)
    E->>M: In Transit (GPS Hub active)
    M-->>E: Gate-Out / Delivery reached
    E->>A: Close Trip for Billing
```

## 2. Core Entity Relationship

How the **General** module drives the rest of the system through strict foreign key relationships.

```mermaid theme={null}
erDiagram
    SOGGETTI ||--o{ CONTATTI : "manages"
    SOGGETTI ||--o{ NAVI : "owns/vessel"
    NODI ||--o{ ZONE : "contains"
    TIPI-CARRO ||--o{ COMPATIBILITA-MATRIX : "defines-Y"
    TIPI-UTI ||--o{ COMPATIBILITA-MATRIX : "defines-X"
    COMPATIBILITA-MATRIX ||--o{ PLANNING : "validates"
    BOOKING }|--|| SOGGETTI : "customer/client"
    BOOKING }|--|| NODI : "origin/dest"
    BOOKING ||--o{ UTIS-LOADED : "contains"
    UTIS-LOADED }|--|| CARRI : "placed-on"
```

## 3. External Ecosystem & Integrations

Magemo acts as a central hub for multiple external stakeholders.

```mermaid theme={null}
graph LR
    subgraph "External Entities"
        PCS[Port Community Systems]
        IM[Infrastructure Manager]
        GPS[IoT Providers]
    end
    
    subgraph "Internal Core"
        EXEC[Execution: CIM/EDI]
        PLAN[Planning: Compos]
        MON[Monitoring: Alerts]
    end

    EXEC <-->|Electronic Manifest| PCS
    EXEC <-->|Web-CIM Submission| IM
    MON <-->|GPS Polling| GPS
```

## 4. Key Connectivity Rules

1. **The Safety Validator**: The **Wagon/UTI Compatibility Matrix** is the mandatory gatekeeper. The **Planning** module cannot bypass this; if the matrix says "No", the system physically prevents the assignment to ensure rail safety.
2. **Dynamic Notification Hub**: The **Modelli Mail** system resolves contacts dynamically. It looks at the **Soggetto** in the Booking, finds the linked **Contati**, and filters by `Tipologia` (e.g., "Operations") and `Ufficio` (e.g., "Export") to send the correct PDF to the correct human.
3. **Master Data Propagation**: A change in the **Generale** module (e.g., updating a Wagon's "Soglia Lunghezza") propagates instantly. The next time that wagon is used in **Planning**, the new length is used for the total train composition calculation.
4. **Calculated Dependencies**: The **Admin** module calculates final tonnage only when the **Execution** module marks the trip as `CHIUSO` (Closed), ensuring financial reports only use verified operational data.