# sagiri2004/live-caller-id-lookup-demo architecture

> Architecture diagram of the GitHub repository sagiri2004/live-caller-id-lookup-demo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sagiri2004/live-caller-id-lookup-demo
- Repository: https://github.com/sagiri2004/live-caller-id-lookup-demo

## Overview

##### Project Type and Purpose
– This is a backend microservice (written in Go) that exposes a RESTful HTTP API for Private Information Retrieval (PIR) on an encrypted database.
– It uses the Lattigo v4 library to perform BFV homomorphic‐encryption operations, letting clients retrieve database entries without revealing which entry is accessed.

##### File‐Structure Analysis
Top‐level files & dirs:
- main.go              → HTTP server + handler bootstrapping
- go.mod, go.sum      → Go module dependencies (incl. Lattigo)
- Makefile            → build/test scripts
- client/             → standalone Go client binary (client/main.go) to invoke the PIR service
- encryption_database/ (implied in README) → JSON config + encrypted data files (.bin, .txtpb)
– Other code files (per README):
- pir_client.go       → client library for service calls
- database_utils.go   → load/validate database, stats, search utility functions

##### README Insights
– Defines four logical subsystems:
a) PIR Service (HTTP API + request routing)
b) Database Utils (file‐I/O, integrity checks, in‐memory loading)
c) Homomorphic‐Encryption Engine (Lattigo BFV operations)
d) PIR Client (Go library + binary for testing/integration)
– External dependency: Lattigo v4 for encryption; file‐based encryption_database inputs.

##### Main Components
– External PIR Client (Go CLI or library)
– HTTP API Layer (main.go):
- Endpoints: /health, /config, /query
– PIR Handler Module (in main.go or a dedicated service package)
– Database Utils Module (database_utils.go): load, validate, retrieve entry by index
– Encryption Engine (Lattigo BFV): key‐gen, encrypt/decrypt, homomorphic ops
– Configuration Loader: reads encryption_database/pir_config.json
– Encryption Database Storage:
- pir-parameters-*.txtpb, block_database-*.bin, evaluation-key-config.txtpb

##### Interactions & Data Flow
1) Client → HTTP POST /query (payload: { "index": N })
2) API Layer parses request → invokes PIR Handler
3) PIR Handler uses Database Utils to locate and load the requested block from disk (or memory cache)
4) Handler calls Encryption Engine (Lattigo) to perform homomorphic retrieval (e.g., BFV “Rotate” + “Mul” operations)
5) Assembles encrypted response payload → HTTP response → Client
6) Client uses its local decryption ability (via evaluation keys) to recover plaintext data

##### Architectural Patterns & Principles
– Layered Architecture: clearly separate API, business logic (PIR Handler), data access (Database Utils), and crypto engine.
– Configuration‐Driven: JSON config drives algorithm parameters and file paths.
– Single‐Responsibility Modules: each Go file/package has one focus (API, client, utils).
– In‐Memory Caching: database loaded into memory for performance (per README).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    ClientCLI["PIR Client (CLI)"]:::external
    click ClientCLI "https://github.com/sagiri2004/live-caller-id-lookup-demo/blob/main/client/main.go"

    %% Running Service
    subgraph "go-pir-service"
        direction TB
        API["HTTP API Layer\n(endpoints: /health, /config, /query)"]:::core
        click API "https://github.com/sagiri2004/live-caller-id-lookup-demo/blob/main/main.go"

        Handler["PIR Handler Module"]:::core
        click Handler "https://github.com/sagiri2004/live-caller-id-lookup-demo/blob/main/go-pir-service/handler.go"

        ConfigLoader["Configuration Loader"]:::data
        click ConfigLoader "https://github.com/sagiri2004/live-caller-id-lookup-demo/blob/main/go-pir-service/config_loader.go"

        DBUtils["Database Utils Module"]:::core
        click DBUtils "https://github.com/sagiri2004/live-caller-id-lookup-demo/blob/main/go-pir-service/database_utils.go"

        CryptoEngine["Homomorphic-Encryption Engine"]:::core
        click CryptoEngine "https://github.com/sagiri2004/live-caller-id-lookup-demo/blob/main/go-pir-service/crypto_engine.go"
    end

    %% External Dependencies and Data Store
    Lattigo["Lattigo v4 Library"]:::lib
    click Lattigo "https://github.com/sagiri2004/live-caller-id-lookup-demo/blob/main/go.mod"

    DataStore["Encryption Database Store"]:::data
    %% DataStore is a cylinder for storage
    class DataStore cylinder

    %% Build & Module Definitions
    Makefile["Makefile"]:::lib
    click Makefile "https://github.com/sagiri2004/live-caller-id-lookup-demo/tree/main/Makefile"

    GoMod["go.mod"]:::lib
    click GoMod "https://github.com/sagiri2004/live-caller-id-lookup-demo/blob/main/go.mod"
    GoSum["go.sum"]:::lib
    click GoSum "https://github.com/sagiri2004/live-caller-id-lookup-demo/blob/main/go.sum"

    %% Flows
    ClientCLI -->|HTTP POST /query\nJSON payload| API
    API -->|"invoke"| Handler
    Handler -->|"load config"| ConfigLoader
    ConfigLoader -->|reads JSON config| DataStore
    Handler -->|"retrieve block"| DBUtils
    DBUtils -->|fetch block| DataStore
    Handler -->|"homomorphic ops"| CryptoEngine
    CryptoEngine -->|"uses API"| Lattigo
    Handler -->|assemble encrypted response| API
    API -->|HTTP response\nEncrypted payload| ClientCLI

    %% Styles
    classDef external fill:#dae8fc,stroke:#6c8ebf;
    classDef core fill:#d5e8d4,stroke:#82b366;
    classDef data fill:#ffe6cc,stroke:#d07900;
    classDef lib fill:#f8cecc,stroke:#b85450;
    classDef cylinder shape: cylinder;
```
