# port-labs/ocean architecture

> Architecture diagram of the GitHub repository port-labs/ocean, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/port-labs/ocean
- Repository: https://github.com/port-labs/ocean

## Overview

##### Main Components

a. Core Framework Components:
- Ocean Framework Core (`port_ocean/core/`)
- Event Listeners System (`port_ocean/core/event_listener/`)
- Entity Processors (`port_ocean/core/handlers/entity_processor/`)
- Integration Base System (`port_ocean/core/integrations/`)
- Port Client (`port_ocean/clients/port/`)

b. Integration Layer:
- Individual Integration Modules (in `integrations/` directory)
- Integration Configuration Management
- Integration Event Handlers

c. External Systems:
- Port API
- Third-party Systems (AWS, Azure, GitLab, etc.)
- Message Brokers (Kafka)

##### Integration Lifecycle

For each flow, include:

a. Export Architecture:
- Data flow from third-party systems
- Entity processing pipeline
- State management
- Port API communication

b. Real-Time Updates:
- Event listeners (Kafka/Webhook)
- Event processing pipeline
- Real-time state updates

c. Integration Lifecycle:
- Integration initialization
- Configuration loading
- Event handling
- Resource synchronization

##### Key Relationships

- Event flow from third-party systems through event listeners
- Data transformation through entity processors
- State management and synchronization with Port API
- Integration configuration management
- Error handling and retry mechanisms

##### Component Details

**[Third-Party Systems] → [Event Listeners]**
- ↓
**[Ocean Framework Core] ← [Integration Modules]**
- ↓
**[Entity Processors] → [State Management]**
- ↓
**[Port Client] → [Port API]**

##### Implementation Notes

- Use different line styles for different types of communication (REST, Event-based, etc.)
- Version management aspects
- Integration points with CI/CD systems
- Monitoring and logging points

Remember to include the integration lifecycle stages:
##### Error Handling

This will provide a complete picture of how the Ocean framework operates while maintaining clarity and usefulness for the principal software engineer.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph External["External Systems Layer"]
        TP["Third-Party Systems"]:::external
        PA["Port API"]:::external
        KB["Kafka Message Broker"]:::external
    end

    subgraph Core["Ocean Framework Core"]
        direction TB
        OC["Ocean Core"]:::core
        click OC "https://github.com/port-labs/ocean/tree/main/port_ocean/core/"
        
        subgraph EventSystem["Event Processing System"]
            EL["Event Listeners"]:::event
            click EL "https://github.com/port-labs/ocean/tree/main/port_ocean/core/event_listener/"
            EC["Event Context"]:::event
            click EC "https://github.com/port-labs/ocean/tree/main/port_ocean/context/"
            EPP["Event Processing Pipeline"]:::event
            click EPP "https://github.com/port-labs/ocean/blob/main/port_ocean/core/handlers/base.py"
        end

        subgraph Handlers["Handlers Layer"]
            EP["Entity Processors"]:::handler
            click EP "https://github.com/port-labs/ocean/tree/main/port_ocean/core/handlers/entity_processor/"
            RM["Resource Mapping"]:::handler
            click RM "https://github.com/port-labs/ocean/blob/main/port_ocean/core/handlers/entity_processor/jq_entity_processor.py"
            ESM["Entity State Management"]:::handler
            click ESM "https://github.com/port-labs/ocean/tree/main/port_ocean/core/handlers/entities_state_applier/"
            SS["State Synchronization"]:::handler
            click SS "https://github.com/port-labs/ocean/tree/main/port_ocean/core/handlers/resync_state_updater/"
        end

        subgraph Config["Configuration Layer"]
            CM["Configuration Management"]:::config
            click CM "https://github.com/port-labs/ocean/tree/main/port_ocean/core/handlers/port_app_config/"
            CLI["Integration CLI Tools"]:::config
            click CLI "https://github.com/port-labs/ocean/tree/main/port_ocean/cli/"
        end
    end

    subgraph Integration["Integration Layer"]
        IB["Integration Base System"]:::integration
        click IB "https://github.com/port-labs/ocean/tree/main/port_ocean/core/integrations/"
        IM["Integration Modules"]:::integration
        click IM "https://github.com/port-labs/ocean/tree/main/integrations/"
        ILM["Integration Lifecycle Management"]:::integration
        click ILM "https://github.com/port-labs/ocean/blob/main/port_ocean/core/integrations/base.py"
    end

    subgraph Client["Client Layer"]
        PC["Port Client"]:::client
        click PC "https://github.com/port-labs/ocean/tree/main/port_ocean/clients/port/"
    end

    %% Connections
    TP --> EL
    KB --> EL
    EL --> EC
    EC --> EPP
    EPP --> EP
    EP --> RM
    RM --> ESM
    ESM --> SS
    SS --> PC
    PC --> PA

    IB --> OC
    IM --> IB
    ILM --> IM
    
    CM --> OC
    CLI --> CM

    %% Styles
    classDef core fill:#2196F3,stroke:#1565C0,color:white
    classDef event fill:#9C27B0,stroke:#7B1FA2,color:white
    classDef handler fill:#1976D2,stroke:#0D47A1,color:white
    classDef config fill:#607D8B,stroke:#455A64,color:white
    classDef integration fill:#4CAF50,stroke:#2E7D32,color:white
    classDef client fill:#FF9800,stroke:#F57C00,color:white
    classDef external fill:#E91E63,stroke:#C2185B,color:white

    %% Legend
    subgraph Legend
        L1["Core Components"]:::core
        L2["Event Processing"]:::event
        L3["Handlers"]:::handler
        L4["Configuration"]:::config
        L5["Integration"]:::integration
        L6["Client"]:::client
        L7["External Systems"]:::external
    end
```
