# brbarmex/ffi-foreign-function-interface architecture

> Architecture diagram of the GitHub repository brbarmex/ffi-foreign-function-interface, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brbarmex/ffi-foreign-function-interface
- Repository: https://github.com/brbarmex/ffi-foreign-function-interface

## Overview

##### Project Type and Purpose
- This is a language-interoperability proof-of-concept (POC) rather than a classic full-stack app.
- Its goal is to provide a single Go-based SDK (“cloudsdk”) that can be reused from C#, Java, Python (and any other FFI-capable language) to consume cloud message queues (AWS SQS or Azure Service Bus) with low latency, agnostic to provider, and using Protobuf for serialization.

##### High-Level Components
a. Go Core Module (“cloudsdk/”)
- main.go – entry point when building a standalone Go binary.
- queue/queue.go – abstraction over AWS/Azure queue consumption, uses the “cloudsdk_provider” env var to pick a strategy.
- protos/ – Protobuf definitions plus generated code for Go, C#, Java, Python.
b. FFI Layer
- cgo glue (Go `//export` functions in main.go or a dedicated .c file) that exposes Go functions as C symbols.
- A small C stub (in Go’s build process) to expose C ABI functions.
c. Language Bindings
- csharp/ – C# wrapper project that P/Invokes into the native library.
- java/ – Java code that uses JNI or JNA to load the shared library and call into it.
- (Python bindings can be added similarly using ctypes or cffi.)
d. External Services
- AWS SQS
- Azure Service Bus
e. Build & Deployment
- Makefile – orchestrates `go build -buildmode=c-shared`, Protobuf code generation, and packaging.
- go.mod – module dependencies.

##### Relationships & Data Flow
1. Language Client (C#/Java/Python)
→ loads the native “cloudsdk” shared library via FFI
→ calls `GetEvents()` or similar exported function
→ receives a serialized Protobuf byte array
→ uses the generated Protobuf classes in that language to deserialize into a strongly-typed message list
2. FFI Layer
→ marshals calling conventions between the host runtime (e.g., .NET, JVM) and Go’s C ABI
→ passes control & arguments into the Go Core
3. Go Core Module
→ reads “cloudsdk_provider” env var
→ selects AWS or Azure strategy implementation from queue/queue.go
→ fetches messages from the cloud queue
→ serializes them into Protobuf bytes
→ returns the byte buffer to the caller via the C ABI
4. External Cloud Service
← SDK issues HTTP/gRPC/SDK calls to AWS SQS or Azure Service Bus
← receives events

##### Key Architectural Patterns & Principles
- Strategy Pattern: for selecting the cloud provider at runtime based on an environment variable.
- Layered Architecture:
- Presentation Layer (language-specific client code)
- Integration Layer (FFI boundary + Protobuf contracts)
- Core SDK Layer (Go module implementing business logic)
- Infrastructure Layer (cloud message queues)
- Single Source of Truth: one Go codebase driving all language bindings.
- Tech Choices: Go + c-shared (cgo), Protobuf, P/Invoke (C#), JNI/JNA (Java), ctypes/cffi (Python).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Language Clients Layer
    subgraph "Language Clients" 
        direction TB
        CSharp["Client: C# via P/Invoke"]:::client
        Java["Client: Java via JNI/JNA"]:::client
        Python["Client: Python via ctypes/cffi"]:::client
        CSharp -->|"Load shared lib & call GetEvents()"| SharedLib
        Java -->|"Load shared lib & call GetEvents()"| SharedLib
        Python -->|"Load shared lib & call GetEvents()"| SharedLib
    end

    %% FFI Integration Layer
    subgraph "FFI Integration Layer"
        direction TB
        SharedLib["cloudsdk.so / .dll\n(C ABI Export)"]:::ffi
        SharedLib -->|"C ABI call"| GoCore
        GoCore -->|"Return Protobuf byte[]"| SharedLib
        SharedLib -->|"Byte buffer"| CSharp
        SharedLib -->|"Byte buffer"| Java
        SharedLib -->|"Byte buffer"| Python
    end

    %% Integration Contracts
    subgraph "Protobuf Contracts" 
        direction TB
        ProtoSource["message_queue.proto"]:::proto
        ProtoGoGen["message_queue.pb.go"]:::proto
        ProtoGoNested["go/cloudsdk/protos/message_queue.pb.go"]:::proto
        ProtoGoAlt["cloudsdk/protos/cloudsdk/protos/message_queue.pb.go"]:::proto
        ProtoCSharp["MessageQueue.cs"]:::proto
        ProtoJava["MessageQueueOuterClass.java"]:::proto
        ProtoPython["message_queue_pb2.py"]:::proto

        GoCore -->|uses| ProtoSource
        CSharp -->|deserialize| ProtoCSharp
        Java -->|deserialize| ProtoJava
        Python -->|deserialize| ProtoPython
    end

    %% Go Core Module
    subgraph "Go Core Module" 
        direction TB
        GoCore["Core SDK Logic"]:::core
        QueueAbstraction["QueueStrategy (AWS/Azure)"]:::core
        GoMod["go.mod"]:::core

        GoCore -->|reads env var| QueueAbstraction
        GoCore -->|serializes msgs| SharedLib
        GoCore -->|depends on| GoMod
        QueueAbstraction -->|fetch messages| AWS
        QueueAbstraction -->|fetch messages| Azure
    end

    %% External Cloud Services
    subgraph "External Services"
        direction TB
        AWS["AWS SQS"]:::external
        Azure["Azure Service Bus"]:::external
        AWS -->|"Messages received"| QueueAbstraction
        Azure -->|"Messages received"| QueueAbstraction
    end

    %% Click Events
    click SharedLib "https://github.com/brbarmex/ffi-foreign-function-interface/blob/main/cloudsdk/main.go"
    click QueueAbstraction "https://github.com/brbarmex/ffi-foreign-function-interface/blob/main/cloudsdk/queue/queue.go"
    click GoMod "https://github.com/brbarmex/ffi-foreign-function-interface/blob/main/cloudsdk/go.mod"
    click ProtoSource "https://github.com/brbarmex/ffi-foreign-function-interface/blob/main/cloudsdk/protos/message_queue.proto"
    click ProtoGoGen "https://github.com/brbarmex/ffi-foreign-function-interface/blob/main/cloudsdk/protos/message_queue.pb.go"
    click ProtoGoNested "https://github.com/brbarmex/ffi-foreign-function-interface/blob/main/cloudsdk/protos/go/cloudsdk/protos/message_queue.pb.go"
    click ProtoGoAlt "https://github.com/brbarmex/ffi-foreign-function-interface/blob/main/cloudsdk/protos/cloudsdk/protos/message_queue.pb.go"
    click ProtoCSharp "https://github.com/brbarmex/ffi-foreign-function-interface/blob/main/cloudsdk/protos/csharp/MessageQueue.cs"
    click ProtoJava "https://github.com/brbarmex/ffi-foreign-function-interface/blob/main/cloudsdk/protos/java/protos/MessageQueueOuterClass.java"
    click ProtoPython "https://github.com/brbarmex/ffi-foreign-function-interface/blob/main/cloudsdk/protos/python/cloudsdk/protos/message_queue_pb2.py"
    click Makefile "https://github.com/brbarmex/ffi-foreign-function-interface/tree/main/Makefile"
    click CSharp "https://github.com/brbarmex/ffi-foreign-function-interface/blob/main/csharp/MessageQueue.cs"
    click CSharp "https://github.com/brbarmex/ffi-foreign-function-interface/blob/main/csharp/Program.cs"
    click CSharp "https://github.com/brbarmex/ffi-foreign-function-interface/blob/main/csharp/csharp.csproj"
    click Java "https://github.com/brbarmex/ffi-foreign-function-interface/blob/main/java/CloudSdk.java"
    click README "https://github.com/brbarmex/ffi-foreign-function-interface/blob/main/README.md"

    %% Styles
    classDef client fill:#b2f2bb,stroke:#2f9e44,color:#1b4332
    classDef ffi fill:#a5d8ff,stroke:#1c7ed6,color:#1b3a4b
    classDef core fill:#ffd8a8,stroke:#f76707,color:#5f370e
    classDef external fill:#dee2e6,stroke:#495057,color:#212529
    classDef proto fill:#eebefa,stroke:#a8071a,color:#590000
```
