# zerufinance/zscore-attester-prod architecture

> Architecture diagram of the GitHub repository zerufinance/zscore-attester-prod, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zerufinance/zscore-attester-prod
- Repository: https://github.com/zerufinance/zscore-attester-prod

## Overview

##### Main Components
- API Gateway/Controller: Represent the entry point for client requests (the POST /task/validate endpoint within the validator.controller.ts).
- Business Logic/Service: The validator.service.ts where the core wallet validation logic (using Merkle proofs and interaction with the external API) is implemented.
- Module Structure: The validator.module.ts which wires together the controller and service – a manifestation of NestJS’s modular architecture.
- Utility Libraries: Highlight usage of OpenZeppelin’s merkle-tree library and NestJS’s class-validator for input validation, indicating their role in ensuring data integrity and secure validation.
- Logging and Error Handling: Represent the integrated NestJS Logger and error management strategy that captures API requests, validation outcomes, and errors.
- Containerization & Deployment: Note Docker-related files (Dockerfile, docker-compose.yml, .env.example, etc.) which point to containerized deployment, ensuring the whole service is production-ready and replicable.

##### Out Relationships and Interactions
- The “Service” interacts with:
- The Merkle proofs logic (via the OpenZeppelin library) to validate wallet score proofs.
- The “External API” component to fetch wallet data.
- Once validation is complete, the response flows back from the service to the controller and then to the client.
- A sub-component or note for “Logging & Error Handling” attached to both the Controller and Service components, emphasizing the consistent monitoring and handling of issues.

##### Architectural Patterns & Principles
- Separation of concerns: presentation (API endpoints), business logic (wallet validation), and integration (external API).
- Use of Docker for containerization which supports consistency across development and production environments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client Request"]:::client

    subgraph "API Layer"
        VC["Validator Controller"]:::controller
        IV["Input Validation"]:::utility
        Log1["Logging & Error Handling"]:::logging
    end

    subgraph "Business Logic"
        VS["Validator Service"]:::service
        MP["Merkle Proof Library"]:::library
        EA["External API Integration"]:::external
        Log2["Logging & Error Handling"]:::logging
    end

    subgraph "Module Wiring"
        VM["Validator Module"]:::module
    end

    subgraph "Deployment Artifacts"
        DF["Dockerfile"]:::deployment
        DC["docker-compose.yml"]:::deployment
        ENV[".env.example"]:::deployment
        SD["src/Dockerfile"]:::deployment
    end

    Client -->|"POST_/task/validate"| VC
    VC -->|"validate_request"| IV
    IV -->|"parsed_data"| VC
    VC -->|"invoke_service"| VS
    VS -->|"fetchData"| EA
    VS -->|"validateMerkle"| MP
    VS -->|"return_response"| VC
    VC -->|"log"| Log1
    VS -->|"log"| Log2
    VM --> VC
    VM --> VS
    VM -->|"deploy"| DF
    DF --> DC
    DC --> ENV
    ENV --> SD

    click VC "https://github.com/zerufinance/zscore-attester-prod/blob/main/src/validator/validator.controller.ts"
    click IV "https://github.com/zerufinance/zscore-attester-prod/blob/main/src/validator/validator.controller.ts"
    click VS "https://github.com/zerufinance/zscore-attester-prod/blob/main/src/validator/validator.service.ts"
    click MP "https://github.com/zerufinance/zscore-attester-prod/blob/main/src/validator/validator.service.ts"
    click EA "https://github.com/zerufinance/zscore-attester-prod/blob/main/src/validator/validator.service.ts"
    click VM "https://github.com/zerufinance/zscore-attester-prod/blob/main/src/validator/validator.module.ts"
    click Log1 "https://github.com/zerufinance/zscore-attester-prod/blob/main/src/main.ts"
    click Log2 "https://github.com/zerufinance/zscore-attester-prod/blob/main/src/main.ts"
    click DF "https://github.com/zerufinance/zscore-attester-prod/tree/main/Dockerfile"
    click DC "https://github.com/zerufinance/zscore-attester-prod/blob/main/docker-compose.yml"
    click ENV "https://github.com/zerufinance/zscore-attester-prod/blob/main/.env.example"
    click SD "https://github.com/zerufinance/zscore-attester-prod/tree/main/src/Dockerfile"

    classDef client fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef controller fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef service fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef module fill:#e2e3e5,stroke:#41464b,stroke-width:2px;
    classDef utility fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef logging fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef external fill:#c3e6cb,stroke:#155724,stroke-width:2px;
    classDef library fill:#fefefe,stroke:#6c757d,stroke-width:2px;
    classDef deployment fill:#e2d6f7,stroke:#6f42c1,stroke-width:2px;
```
