# kosasih/eulers-shield architecture

> Architecture diagram of the GitHub repository kosasih/eulers-shield, 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/eulers-shield
- Repository: https://github.com/kosasih/eulers-shield

## Overview

##### Project Type and Purpose
- Euler’s Shield is a decentralized, AI-powered financial system to stabilize Pi Coin at a target price.
- It combines blockchain nodes, smart contracts, AI/ML agents, cybersecurity modules, and a full-stack application (React frontend + Node.js/Flask APIs).
- Key capabilities: data collection & analytics, ML-based market‐making, decentralized governance, on-chain consensus, and security monitoring.

##### High-Level System Components
a. User Interface
- React single‐page app (frontend/src)
- Consumes REST/WebSocket APIs
b. API & Business Logic
- Node.js backend (backend/src) – user & transaction controllers, auth middleware
- Python Flask/FastAPI service (api/app.py) – price oracle, on-chain integration
- “src/main.py” orchestration script for monolithic services
c. AI/ML Engines
- ai-market-maker (automated market maker, LSTM model)
- ai_agents (decentralized governance, oracle aggregator, upgrade agent, compliance, etc.)
- ai_security (anomaly detection, intrusion & facial recognition)
d. Blockchain Layer
- Self-hosted pi-coin-blockchain node (PoW/PoS modules)
- Smart contracts (smart-contracts/, contracts/mainnet & testnet) deployed to Pi network
- Blockchain integration adapters (immutable_storage, blockchain_integration.py)
e. Data Layer
- Market data CSVs & generators (ai-market-maker/data)
- Model artifacts in ml modules
- Persistent storage (implied: database for users & transactions)
f. External Services
- Global financial system API (global-financial-system-integration/api)
- Key management (HSM, distributed key management)
- External oracles & exchanges
g. Infrastructure & DevOps
- Docker & CI (CircleCI configs)
- Environment config per stage (config/.env.*)
- Deployment on cloud/Kubernetes (referenced by badges: AWS, GCP, Azure)

##### Relationships & Interactions
- Frontend ↔ API Gateway: user actions → HTTP/WS requests
- API Gateway → Business Logic: routes to Node.js services or Python Flask endpoints
- Business Logic → AI/ML Engines: RPC or message queue calls to Python agent microservices
- AI/ML Engines ↔ Data Layer: read historical & real-time market data, write recommendations
- Business Logic → Blockchain Integration: send transactions to the pi-coin-blockchain node, invoke smart contracts
- Blockchain Node ↔ Smart Contracts: consensus & state updates
- AI Security → Monitors logs & network traffic; alerts governance agents
- Decentralized Governance Agents → submit proposals on-chain via smart contracts
- External Financial Systems ↔ Global Integration API

##### Architectural Patterns & Principles
- Microservices: each AI component, governance agent, security detector is a standalone Python service
- Three‐Tier MVC: React UI, API/Controllers, Data/Blockchain
- Event‐Driven: use message queues (or webhook callbacks) for market data updates, ML alerts, governance proposals
- Hexagonal Ports & Adapters: clear separation between core logic (src/) and infrastructure adapters (blockchain_integration, immutable_storage)
- Security by Design: zero-trust communications, homomorphic encryption, differential privacy modules

##### Essential Elements
- Component containers labeled by directory/service name
- Environment/Deployment hints (CI/CD pipeline, config environments)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        UI["React SPA"]:::ui
    end

    %% API Layer
    subgraph "API Layer"
        NodeAPI["Node.js Backend"]:::api
        Flask["Python Flask Price Oracle"]:::api
        Script["Monolithic Orchestration Script"]:::api
    end

    %% Domain Services
    subgraph "Domain Services"
        subgraph "AI Orchestration"
            MM["Market Maker Engine"]:::service
            Gov["Governance Agents"]:::service
        end
        subgraph "AI Security"
            AD["Anomaly Detection Service"]:::service
            FR["Facial Recognition Service"]:::service
            ID["Intrusion Detection Service"]:::service
        end
    end

    %% Blockchain & Data Stores
    subgraph "Blockchain & Data Stores"
        BCNode["Pi Coin Blockchain Node"]:::blockchain
        SmartC["Smart Contracts"]:::blockchain
        DB["User & Transaction DB"]:::datastore
        Gen["Market Data Generator"]:::datastore
        CSV["Market Data CSV"]:::datastore
        ModelArt["Model Artifacts"]:::datastore
    end

    %% External Systems
    subgraph "External Systems"
        GFS["Global Financial API"]:::external
        HSM["Key Management"]:::external
        Oracles["External Oracles & Exchanges"]:::external
    end

    %% Deployment
    subgraph "Deployment"
        Config["Env Config Files"]:::infra
        CircleCI["CircleCI Pipeline"]:::infra
        CodeQL["GitHub CodeQL Workflow"]:::infra
    end

    %% Connections
    UI -->|"HTTP/WS Requests"| NodeAPI
    UI -->|"WebSocket"| Flask

    NodeAPI -->|"Routes Requests"| Flask
    NodeAPI -->|"Invoke Orchestration"| Script

    NodeAPI -->|"priceUpdate"| MM
    NodeAPI -->|"transactionProposal"| Gov

    Flask -->|"Sends Transactions"| BCNode
    Script -->|"Orchestrates Services"| MM
    Script -->|"Orchestrates Services"| Gov

    MM -->|"Reads/Writes Data"| Gen
    MM -->|"Reads/Writes Data"| CSV
    MM -->|"Loads Models"| ModelArt

    Gov -->|"Submit Proposals"| SmartC

    BCNode <-->|"Consensus & State"| SmartC

    AD -->|"Monitors Logs"| NodeAPI
    AD -->|"Monitors Traffic"| BCNode

    FR -->|"Facial Data"| Gen
    ID -->|"Network Data"| BCNode

    GFS -->|"External Market Data"| Flask
    HSM -->|"Key Storage"| NodeAPI
    Oracles -->|"Price Feeds"| Flask

    %% Deployment links
    Config -.-> NodeAPI
    Config -.-> Flask
    CircleCI -.-> NodeAPI
    CodeQL -.-> Script

    %% Click Events
    click UI "https://github.com/kosasih/eulers-shield/tree/main/frontend/src"
    click NodeAPI "https://github.com/kosasih/eulers-shield/tree/main/backend/src"
    click Flask "https://github.com/kosasih/eulers-shield/blob/main/api/app.py"
    click Script "https://github.com/kosasih/eulers-shield/blob/main/src/main.py"
    click MM "https://github.com/kosasih/eulers-shield/blob/main/ai-market-maker/aimm.py"
    click Gen "https://github.com/kosasih/eulers-shield/blob/main/ai-market-maker/data/market-data-generator/generate_market_data.py"
    click CSV "https://github.com/kosasih/eulers-shield/blob/main/ai-market-maker/data/market_data.csv"
    click ModelArt "https://github.com/kosasih/eulers-shield/blob/main/ai-market-maker/models/lstm.py"
    click Gov "https://github.com/kosasih/eulers-shield/tree/main/ai_agents/"
    click AD "https://github.com/kosasih/eulers-shield/blob/main/ai_security/anomaly_detection/anomaly_detection.py"
    click FR "https://github.com/kosasih/eulers-shield/blob/main/ai_security/facial_recognition/face_recognition.py"
    click ID "https://github.com/kosasih/eulers-shield/blob/main/ai_security/intrusion_detection/intrusion_detector.py"
    click BCNode "https://github.com/kosasih/eulers-shield/blob/main/blockchain/pi-coin-blockchain/blockchain.py"
    click SmartC "https://github.com/kosasih/eulers-shield/tree/main/smart-contracts/contracts/"
    click DB "https://github.com/kosasih/eulers-shield/blob/main/backend/src/models/User.js"
    click GFS "https://github.com/kosasih/eulers-shield/blob/main/global-financial-system-integration/api/api.py"
    click HSM "https://github.com/kosasih/eulers-shield/blob/main/key_management/hsm_key_management.py"
    click Config "https://github.com/kosasih/eulers-shield/blob/main/config/.env.development"
    click CircleCI "https://github.com/kosasih/eulers-shield/blob/main/.circleci/config.yml"
    click CodeQL "https://github.com/kosasih/eulers-shield/blob/main/.github/workflows/codeql.yml"

    %% Styles
    classDef ui fill:#aed6f1,stroke:#1f618d,color:#1f618d;
    classDef api fill:#d6eaf8,stroke:#1f618d,color:#1f618d;
    classDef service fill:#fad7a0,stroke:#b9770e,color:#b9770e;
    classDef datastore fill:#abebc6,stroke:#229954,color:#229954;
    classDef blockchain fill:#e8daef,stroke:#8e44ad,color:#8e44ad;
    classDef external fill:#f5b7b1,stroke:#943126,color:#943126;
    classDef infra fill:#d5dbdb,stroke:#2e4053,color:#2e4053;
```
