# kosasih/global-connect architecture

> Architecture diagram of the GitHub repository kosasih/global-connect, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kosasih/global-connect
- Repository: https://github.com/kosasih/global-connect

## Overview

##### Project type and purpose
- This is a full-stack, microservice-based platform (“Global Connect”) for Pi Coin, combining:
- A React SPA (“frontend” + “dashboard”) for end users and partners
- Node.js/Express microservices (“backend”) exposing REST/GraphQL/WebSocket APIs
- On-chain logic via JavaScript smart contracts under “smart_contracts”
- A massive catalog of AI modules (JS/Python) under “ai/” for compliance, risk, forecasting, user support, etc.
- Blockchain connectors (Python) under “blockchain/”
- SDKs (Node + Python) and example apps in “apps/”
- CI/CD, local dev scripts, monitoring, and test harnesses

##### File structure
- Top-level “frontend” and “dashboard” hold React code, static assets, and Dockerfiles
- “backend” is organized into adapters, API routes, controllers, services, models, middleware, tests
- “ai/” contains:
- A central orchestrator (ai_orchestration_engine.js) and “engine/modules” implementing business-domain AI flows (e.g., compliance, liquidity optimizer, macro forecast)
- Standalone micro-apps (e.g., aiamlmonitor, aibankgateway, …) each with its own entry point
- Utilities for logging, data ingestion, monitoring, etc.
- “blockchain/”: Python scripts for connecting to multiple chains, listening to events, and managing wallets
- “smart_contracts/”: dual-value system and PiCoin contracts + migrations + tests
- “api/”: low-level webhook handlers and OpenAPI definition
- “apps/”: example end-to-end applications grouped by domain (AI, DeFi, e-commerce, identity, …)
- “sdk/”: Node.js and Python client libraries
- “scripts/”: deployment, ABI updates, test data generation, fraud simulation
- “config/”, CI configs, Docker compose, Prometheus/Grafana in “backend/monitoring”

##### README for additional insights
- Core architecture is described as:
- Node.js & Express microservices
- React SPA
- Smart contracts on blockchain (Stellar/Ethereum-style JS contracts)
- AI modules for every domain (fraud, compliance, market forecasting, voice assistants, etc.)
- Monitoring & alerting with Prometheus + Grafana
- Plug-and-play modularity for rapid feature swaps

a. Main components
- Presentation Layer:
– User Web App (frontend React SPA)
– Admin/Partner Dashboard (dashboard React SPA)
- API Layer:
– API Gateway / Express App (“backend/app.js”)
– Versioned API routes (REST + GraphQL + WebSocket)
- Microservice Layer:
– Transaction Service, User Service, Analytics Service, Compliance Service, Price Prediction, etc.
– Redis (caching, pub/sub for WebSocketServer)
– PostgreSQL/MongoDB (models under “backend/models”)
- AI Layer:
– Orchestration Engine invoking AI modules (ai/engine/index.js)
– Domain-specific AI modules (e.g. aml_ctf_checker.py, liquidity_optimizer.js, chatbot.js)
- Blockchain Layer:
– Python chain connectors (cosmos_client, solana_client)
– Universal Wallet services
– Event listener producing chain events → Microservices
– Smart Contracts (DualValueSystem.js, PiCoin.js) deployed on chain
- Data & Storage:
– Relational/NoSQL DB for core entities (Users, Transactions, NFTs, PricePredictions…)
– Redis for sessions, rate-limit, caching
– File store for logs, alerts, reports
- Integration & Extensibility:
– Adapters (Shopify, WooCommerce, etc.) under “backend/adapters”
– SDKs for Node/Python clients
– Webhooks (api/v1/webhooks.js), partner connectors (apps/)
- Observability:
– Health checks & metrics (backend/monitoring) → Prometheus → Grafana
– Advanced logging (ai/utils/advanced_logging.js + backend/loggingMiddleware.js)
– Audit logs (backend/audit)

b. Relationships & interactions
1. User → Browser → React SPA → API Gateway
2. Gateway dispatches to microservices → DB / Redis / Blockchain connector
3. Microservices call AI Orchestrator via internal API or direct module call
4. AI modules process data, store results, push events back to message bus or DB
5. WebSocketServer streams real-time updates to SPA
6. Background “blockchain/event_listener.py” pushes on-chain events to transactionService
7. Smart contracts enforce dual-value stability and issue on-chain events
8. Monitoring agents scrape metrics, trigger alerts

c. Architectural patterns & principles
- Microservices + modular plugin architecture (loose coupling, single responsibility)
- Hexagonal ports-and-adapters for external systems (backend/adapters, blockchain connectors)
- Event-driven communication (WebSockets, message bus, pub/sub)
- Separation of concerns: Presentation / API / Business Logic / Data / AI / Chain
- CI/CD: test suites (unit, integration, e2e) gated via GitHub Actions & CircleCI

d. Key technologies & frameworks
- Node.js, Express, GraphQL, WebSocket
- React, Redux, React Hooks
- Python for blockchain connectors & select AI scripts
- Redis, PostgreSQL or MongoDB
- Truffle/Hardhat-style JS smart contracts
- Prometheus, Grafana for observability
- Docker & Docker Compose

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        UserApp["User Web App (React SPA)"]:::frontend
        Dashboard["Admin/Partner Dashboard (React SPA)"]:::frontend
    end

    %% API Layer
    subgraph "API Gateway Layer"
        direction TB
        APIGateway["API Gateway / Express App"]:::api
        RESTWS["Versioned REST & WebSocket Endpoints"]:::api
        GraphQL["GraphQL Endpoint"]:::api
        Webhooks["Webhook Handlers"]:::api
    end

    %% Microservice Layer
    subgraph "Microservice Layer"
        direction TB
        Controllers["Controllers"]:::micro
        ServicesGroup["Services"]:::micro
        Models["Models (DB Schemas)"]:::data
        Adapters["Adapters (Ports-and-Adapters)"]:::micro
        subgraph ServicesList
            direction TB
            TransactionSvc["Transaction Service"]:::micro
            UserSvc["User Service"]:::micro
            AnalyticsSvc["Analytics Service"]:::micro
            ComplianceSvc["Compliance Service"]:::micro
            PricePredictionSvc["Price Prediction Service"]:::micro
            BlockchainListener["Blockchain Listener"]:::micro
            WebsocketServer["WebSocket Server"]:::micro
        end
    end

    %% AI Layer
    subgraph "AI & Orchestration Layer"
        direction TB
        Orchestration["AI Orchestration Engine"]:::ai
        EngineIndex["Engine Index"]:::ai
        AIModules["Domain-specific AI Modules"]:::ai
        CentralBankModules["Central Bank AI Modules"]:::ai
        StandaloneAIMicroApps["Standalone AI Micro-apps"]:::ai
        AIUtils["AI Utilities"]:::ai
    end

    %% Blockchain Layer
    subgraph "Blockchain Layer"
        direction TB
        CosmosClient["Cosmos Client"]:::blockchain
        SolanaClient["Solana Client"]:::blockchain
        UniversalWallet["Universal Wallet Service"]:::blockchain
        ChainEventListener["Event Listener"]:::blockchain
        DualValueContract["DualValueSystem Contract"]:::blockchain
        PiCoinContract["PiCoin Contract"]:::blockchain
        Migrations["Migrations"]:::blockchain
    end

    %% Data & Infrastructure Layer
    subgraph "Data & Infrastructure Layer"
        direction TB
        PostgresDB["PostgreSQL / MongoDB"]:::data
        RedisCache["Redis (Cache & Pub/Sub)"]:::data
        FileStore["File Store (Logs, Reports)"]:::data
    end

    %% Integration & SDKs & Apps
    subgraph "Integration & Extensibility"
        direction TB
        SDKNode["Node.js SDK"]:::micro
        SDKPython["Python SDK"]:::micro
        ExampleApps["Example Apps"]:::micro
    end

    %% Observability & Config & Scripts
    subgraph "Observability & Support"
        direction TB
        HealthChecks["Health Checks"]:::observ
        Metrics["Metrics"]:::observ
        LoggingMiddleware["Logging Middleware"]:::observ
        Config["Configuration"]:::data
        Scripts["CI/CD & Scripts"]:::data
    end

    %% Connections
    UserApp -->|requests| APIGateway
    Dashboard -->|requests| APIGateway

    APIGateway -->|routes to| RESTWS
    APIGateway -->|routes to| GraphQL
    APIGateway -->|routes to| Webhooks

    RESTWS --> Controllers
    GraphQL --> Controllers
    Webhooks --> Controllers

    Controllers --> ServicesList
    Controllers --> Adapters
    ServicesList --> Models
    ServicesList --> PostgresDB
    ServicesList --> RedisCache
    ServicesList --> Orchestration
    ServicesList --> CosmosClient
    ServicesList --> SolanaClient
    ServicesList --> WebsocketServer

    WebsocketServer -->|push events| UserApp
    ChainEventListener -->|on-chain events| TransactionSvc

    Orchestration --> EngineIndex
    EngineIndex --> AIModules
    EngineIndex --> CentralBankModules
    EngineIndex --> StandaloneAIMicroApps
    EngineIndex --> AIUtils

    AIModules --> PostgresDB
    CentralBankModules --> PostgresDB
    StandaloneAIMicroApps --> PostgresDB

    CosmosClient --> DualValueContract
    SolanaClient --> PiCoinContract
    CosmosClient --> UniversalWallet
    SolanaClient --> UniversalWallet

    DualValueContract -->|deployed via| Migrations
    PiCoinContract -->|deployed via| Migrations

    ServicesList --> Metrics
    ServicesList --> HealthChecks
    ServicesList --> LoggingMiddleware

    HealthChecks -->|scrapes| Metrics
    Metrics -->|visualized by| ExampleApps

    SDKNode -->|used by| ExampleApps
    SDKPython -->|used by| ExampleApps
    Adapters -->|integrate with| ExampleApps

    Config --> APIGateway
    Config --> ServicesList
    Config --> Orchestration
    Scripts --> Migrations
    Scripts --> CosmosClient
    Scripts --> SolanaClient

    %% Click Events
    click UserApp "https://github.com/kosasih/global-connect/tree/main/frontend/"
    click Dashboard "https://github.com/kosasih/global-connect/tree/main/dashboard/"
    click APIGateway "https://github.com/kosasih/global-connect/blob/main/backend/app.js"
    click RESTWS "https://github.com/kosasih/global-connect/tree/main/backend/api/"
    click GraphQL "https://github.com/kosasih/global-connect/blob/main/backend/api/graphql.js"
    click Webhooks "https://github.com/kosasih/global-connect/blob/main/api/v1/webhooks.js"
    click Controllers "https://github.com/kosasih/global-connect/tree/main/backend/controllers/"
    click TransactionSvc "https://github.com/kosasih/global-connect/blob/main/backend/services/transactionService.js"
    click UserSvc "https://github.com/kosasih/global-connect/blob/main/backend/services/userService.js"
    click AnalyticsSvc "https://github.com/kosasih/global-connect/blob/main/backend/services/analyticsService.js"
    click ComplianceSvc "https://github.com/kosasih/global-connect/blob/main/backend/services/dualValueService.js"
    click PricePredictionSvc "https://github.com/kosasih/global-connect/blob/main/backend/services/pricePredictionService.js"
    click BlockchainListener "https://github.com/kosasih/global-connect/blob/main/backend/services/blockchainListener.js"
    click WebsocketServer "https://github.com/kosasih/global-connect/blob/main/backend/services/websocketServer.js"
    click Models "https://github.com/kosasih/global-connect/tree/main/backend/models/"
    click Adapters "https://github.com/kosasih/global-connect/tree/main/backend/adapters/"
    click Orchestration "https://github.com/kosasih/global-connect/blob/main/ai/ai_orchestration_engine.js"
    click EngineIndex "https://github.com/kosasih/global-connect/blob/main/ai/engine/index.js"
    click AIModules "https://github.com/kosasih/global-connect/tree/main/ai/engine/modules/"
    click CentralBankModules "https://github.com/kosasih/global-connect/tree/main/ai/aiCentralBank/"
    click StandaloneAIMicroApps "https://github.com/kosasih/global-connect/tree/main/ai/aiamlmonitor/"
    click AIUtils "https://github.com/kosasih/global-connect/blob/main/ai/aiCentralBank/utils/advanced_logging.js"
    click CosmosClient "https://github.com/kosasih/global-connect/blob/main/blockchain/cosmos_client.py"
    click SolanaClient "https://github.com/kosasih/global-connect/blob/main/blockchain/solana_client.py"
    click UniversalWallet "https://github.com/kosasih/global-connect/blob/main/blockchain/universal_wallet.py"
    click ChainEventListener "https://github.com/kosasih/global-connect/blob/main/blockchain/event_listener.py"
    click DualValueContract "https://github.com/kosasih/global-connect/blob/main/smart_contracts/DualValueSystem.js"
    click PiCoinContract "https://github.com/kosasih/global-connect/blob/main/smart_contracts/PiCoin.js"
    click Migrations "https://github.com/kosasih/global-connect/tree/main/smart_contracts/migrations/"
    click SDKNode "https://github.com/kosasih/global-connect/blob/main/sdk/node/index.js"
    click SDKPython "https://github.com/kosasih/global-connect/blob/main/sdk/python/globalconnect.py"
    click ExampleApps "https://github.com/kosasih/global-connect/tree/main/apps/"
    click HealthChecks "https://github.com/kosasih/global-connect/blob/main/backend/monitoring/health.js"
    click Metrics "https://github.com/kosasih/global-connect/blob/main/backend/monitoring/metrics.js"
    click LoggingMiddleware "https://github.com/kosasih/global-connect/blob/main/backend/middleware/loggingMiddleware.js"
    click Config "https://github.com/kosasih/global-connect/blob/main/config/default.json"
    click Scripts "https://github.com/kosasih/global-connect/blob/main/scripts/deploy.js"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0366D6,color:#0366D6;
    classDef api fill:#DFFFE0,stroke:#28A745,color:#28A745;
    classDef micro fill:#E6F7FF,stroke:#0052CC,color:#0052CC;
    classDef ai fill:#FFF0D4,stroke:#FF8C00,color:#FF8C00;
    classDef blockchain fill:#F3E5F5,stroke:#6F42C1,color:#6F42C1;
    classDef data fill:#F0F0F0,stroke:#6C757D,color:#6C757D;
    classDef observ fill:#FDE2E2,stroke:#D73A49,color:#D73A49;
```
