# hac1es/nt219-project architecture

> Architecture diagram of the GitHub repository hac1es/nt219-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hac1es/nt219-project
- Repository: https://github.com/hac1es/nt219-project

## Overview

##### Project type and purpose
- This is a distributed, peer-to-peer (P2P) plus server system for credit scoring using homomorphic encryption and threshold decryption.
- Banks act as clients to generate keys, encrypt customer data, and perform partial decryption. A central server (FinanceOrg HEServer) evaluates encrypted scores and aggregates partial decryptions. A Certificate Authority (CA) issues and signs keys.

##### File structure
- Top-level directories:
- Banks/…: code each bank runs
- CA/…: certificate authority server and keys
- FinanceOrg/…: central aggregator (HEServer) and its certificates
- Testing/…: proof-of-concept and benchmarks
- install.sh, requirements.txt: deployment scripts and dependencies
- Within Banks/:
- Certificate: CSR and signed CA root certificates
- DBService: customer data lookup service
- HEModule: UI and scripts for key gen, joint key, eval-mult keys, encryption, decryption
- InterbankService: REST API and client for inter-bank communication and forwarding encrypted data to FinanceOrg
- Configuration and build: runAPI.sh, server.py, runServer.sh

##### README for architecture hints
- Describes sequential processes: key generation → joint public key → eval-mult key contributions → data encryption → server evaluation → threshold decryption
- Emphasizes P2P model among banks plus server aggregation

##### Main components
a. Certificate Authority (CA service)
- server.py, runServer.sh
- Issues and signs keys (RootCA, sbv.org)
b. Bank Clients (multiple instances)
- Certificate module (requestCert.py)
- HEModule UI (MainWindow.ui + keyGenerator, calculateJointKey, evalMultKey1, evalMultKey2, interactiveEncrypt, multipartyDecrypt)
- DBService (getCustomerInfo.py)
- InterbankService (interbankAPI.py, interbankClient.py, runAPI.sh, sendToFECredit.py)
c. Finance Organization Aggregator
- HEServer.py (receives ciphertexts, performs homomorphic evaluation, returns encrypted score)
- Certificate folder for trust anchors
d. Testing/Benchmarking (PoC.py, PoC_benchmark.py, results)
e. Shared artifacts/repos
- Joint public key files, eval-mult keys, encrypted data blobs, signature files

##### Relationships and data flows
- Banks request and obtain certificates from CA.
- Each bank generates its own HE key pair via keyGenerator.
- Banks sequentially construct a joint public key (calculateJointKey).
- Banks contribute to eval-mult key in two phases (evalMultKey1, evalMultKey2).
- Banks encrypt customer data via interactiveEncrypt/SerializeData and sign ciphertexts.
- Banks push ciphertexts through their InterbankService to the FinanceOrg HEServer.
- HEServer performs homomorphic computations and returns encrypted results.
- Each bank executes partial decryptions via multipartyDecrypt/decryptEncryptedText and finally the aggregator reconstructs the plaintext score.

##### Architectural patterns and design principles
- P2P key-exchange and threshold cryptography
- Micro-services per bank: separate modules for certificate, encryption, interbank communication, database access
- Central evaluation service (FinanceOrg)
- REST API pattern for interbank/federated communication
- UI layer (Qt .ui file) separate from CLI scripts
- Secure channels and signing for data integrity

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Certificate Authority
    subgraph "Certificate Authority"
        direction TB
        CA_Server["CA Server<br/>server.py<br/>runServer.sh"]:::ca
        CA_Artifacts["RootCA.crt, RootCA.key,<br/>RootCA.srl,<br/>sbv.org.crt, sbv.org.csr,<br/>sbv.org.ext, sbv.org.key"]:::ca
    end

    %% Bank Client
    subgraph "Bank Client (× N)"
        direction TB
        Bank_Cert["Certificate Module<br/>requestCert.py<br/>RootCA.crt"]:::bank
        Bank_DB["DB Service<br/>getCustomerInfo.py"]:::bank
        subgraph "HE Module UI & Scripts"
            direction TB
            HE_UI["MainWindow.ui"]:::bank
            KeyGen["keyGenerator.py"]:::bank
            JointKey["calculateJointKey.py"]:::bank
            Eval1["evalMultKey1.py"]:::bank
            Eval2["evalMultKey2.py"]:::bank
            Encrypt["interactiveEncrypt.py"]:::bank
            Decrypt["multipartyDecrypt.py"]:::bank
        end
        subgraph "Interbank Service"
            direction TB
            IB_API["interbankAPI.py"]:::bank
            IB_Client["interbankClient.py"]:::bank
            IB_Run["runAPI.sh"]:::bank
            IB_Send["sendToFECredit.py"]:::bank
            IB_Cert["RootCA.crt"]:::bank
            IB_Keep["Received/.gitkeep"]:::bank
        end
    end

    %% FinanceOrg Aggregator
    subgraph "FinanceOrg Aggregator"
        direction TB
        HEServer["FinanceOrg HEServer<br/>HEServer.py"]:::agg
        FO_Cert["Certificate Module<br/>requestCert.py<br/>RootCA.crt"]:::agg
    end

    %% Testing / Benchmarking
    subgraph "Testing & Benchmarking"
        direction TB
        PoC["PoC.py"]:::test
        Benchmark["PoC_benchmark.py"]:::test
        Results["benchmark_results_20250607_142239.txt"]:::test
    end

    %% Interactions
    CA_Server -->|1 Issue Certificates| Bank_Cert
    Bank_Cert -->|2 Key Generation| KeyGen
    KeyGen -->|3 Joint Key Contribution| JointKey
    JointKey --> Eval1
    Eval1 --> Eval2
    Eval2 --> Encrypt
    Encrypt --> IB_Client
    IB_Client -->|4 Send Ciphertexts| HEServer
    HEServer -->|5 Return Encrypted Scores| IB_API
    IB_API --> Decrypt
    Decrypt -->|6 Partial Decryption| HEServer

    %% Testing flows
    PoC --> Benchmark
    Benchmark --> Results

    %% Click Events - CA
    click CA_Server "https://github.com/hac1es/nt219-project/blob/main/CA/server.py"
    click CA_Server "https://github.com/hac1es/nt219-project/blob/main/CA/runServer.sh"
    click CA_Artifacts "https://github.com/hac1es/nt219-project/blob/main/CA/rootCA.crt"
    click CA_Artifacts "https://github.com/hac1es/nt219-project/blob/main/CA/rootCA.key"
    click CA_Artifacts "https://github.com/hac1es/nt219-project/blob/main/CA/rootCA.srl"
    click CA_Artifacts "https://github.com/hac1es/nt219-project/blob/main/CA/sbv.org.crt"
    click CA_Artifacts "https://github.com/hac1es/nt219-project/blob/main/CA/sbv.org.csr"
    click CA_Artifacts "https://github.com/hac1es/nt219-project/blob/main/CA/sbv.org.ext"
    click CA_Artifacts "https://github.com/hac1es/nt219-project/blob/main/CA/sbv.org.key"

    %% Click Events - Bank Certificate Module
    click Bank_Cert "https://github.com/hac1es/nt219-project/blob/main/Banks/Certificate/requestCert.py"
    click Bank_Cert "https://github.com/hac1es/nt219-project/blob/main/Banks/Certificate/RootCA.crt"

    %% Click Events - Bank DB Service
    click Bank_DB "https://github.com/hac1es/nt219-project/blob/main/Banks/DBService/getCustomerInfo.py"

    %% Click Events - HE Module UI & Scripts
    click HE_UI "https://github.com/hac1es/nt219-project/blob/main/Banks/HEModule/MainWindow.ui"
    click KeyGen "https://github.com/hac1es/nt219-project/blob/main/Banks/HEModule/keyGenerator.py"
    click JointKey "https://github.com/hac1es/nt219-project/blob/main/Banks/HEModule/calculateJointKey.py"
    click Eval1 "https://github.com/hac1es/nt219-project/blob/main/Banks/HEModule/evalMultKey1.py"
    click Eval2 "https://github.com/hac1es/nt219-project/blob/main/Banks/HEModule/evalMultKey2.py"
    click Encrypt "https://github.com/hac1es/nt219-project/blob/main/Banks/HEModule/interactiveEncrypt.py"
    click Decrypt "https://github.com/hac1es/nt219-project/blob/main/Banks/HEModule/multipartyDecrypt.py"

    %% Click Events - Interbank Service
    click IB_API "https://github.com/hac1es/nt219-project/blob/main/Banks/InterbankService/interbankAPI.py"
    click IB_Client "https://github.com/hac1es/nt219-project/blob/main/Banks/InterbankService/interbankClient.py"
    click IB_Run "https://github.com/hac1es/nt219-project/blob/main/Banks/InterbankService/runAPI.sh"
    click IB_Send "https://github.com/hac1es/nt219-project/blob/main/Banks/InterbankService/sendToFECredit.py"
    click IB_Cert "https://github.com/hac1es/nt219-project/blob/main/Banks/InterbankService/RootCA.crt"
    click IB_Keep "https://github.com/hac1es/nt219-project/blob/main/Banks/InterbankService/Received/.gitkeep"

    %% Click Events - FinanceOrg Aggregator
    click HEServer "https://github.com/hac1es/nt219-project/blob/main/FinanceOrg/HEServer.py"
    click FO_Cert "https://github.com/hac1es/nt219-project/blob/main/FinanceOrg/Certificate/requestCert.py"
    click FO_Cert "https://github.com/hac1es/nt219-project/blob/main/FinanceOrg/Certificate/RootCA.crt"

    %% Click Events - Testing
    click PoC "https://github.com/hac1es/nt219-project/blob/main/Testing/PoC.py"
    click Benchmark "https://github.com/hac1es/nt219-project/blob/main/Testing/PoC_benchmark.py"
    click Results "https://github.com/hac1es/nt219-project/blob/main/Testing/benchmark_results/benchmark_results_20250607_142239.txt"

    %% Styles
    classDef ca fill:#ADD8E6,stroke:#000;
    classDef bank fill:#90EE90,stroke:#000;
    classDef agg fill:#FFA500,stroke:#000;
    classDef test fill:#D3D3D3,stroke:#000;
```
