# doyindev1/proof-of-contribution architecture

> Architecture diagram of the GitHub repository doyindev1/proof-of-contribution, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/doyindev1/proof-of-contribution
- Repository: https://github.com/doyindev1/proof-of-contribution

## Overview

##### Project type and purpose
- Proof of Contribution is an open-source Node.js backend service (a RESTful API) that computes a TEA Rank for open-source packages by building dependency graphs across multiple ecosystems. It is not a full-stack app (no UI), but rather a backend analytics tool with pluggable integrations to external package registries.

##### File structure
- Root files:
- index.js (entry point / server startup)
- example.js (usage demonstration)
- tea.yaml (algorithm/config parameters: kappa, delta)
- models/Project.js: in-memory representation of a project + its dependency graph
- services/
- PackageManagerService.js: abstracts calls to npm, PyPI, Crates.io, RubyGems registries
- ProofOfContribution.js: contains the TEA Rank algorithm & spam-detection logic
- package.json / package-lock.json: defines runtime dependencies (Express, HTTP clients, etc.)

##### Key interactions and external systems
- HTTP Client (curl or other services) → Express HTTP Server (index.js routes)
- Server → PackageManagerService → External Package Registries (npm, PyPI, Crates, RubyGems)
- PackageManagerService → models/Project → ProofOfContribution → results
- HTTP Server → JSON response (teaRank, flags, stats)

##### Main components
a. Client Layer
- REST client (curl, CLI, other services)
b. API Layer
- index.js / Express app (HTTP route handling)
c. Business Logic Layer
- ProofOfContribution service (TEA Rank algorithm, spam detection)
- Configuration loader (tea.yaml)
d. Integration Layer
- PackageManagerService with connectors/adapters for each ecosystem
e. Data Model
- Project model (in-memory graph structure)
f. External Dependencies
- npm registry
- PyPI registry
- Crates.io registry
- RubyGems registry

##### Relationships and data flows
1. Client → HTTP Server (“POST /analyze”)
2. Server → PackageManagerService (“fetch dependencies”)
3. PackageManagerService → External Registry (“registry API calls”)
4. Registry → PackageManagerService (dependency lists)
5. PackageManagerService → Project Model (build graph)
6. Project Model → ProofOfContribution (“run TEA algorithm”)
7. ProofOfContribution → Server (“computed TEA Rank & flags”)
8. Server → Client (“JSON response”)

##### Architectural patterns and design principles
- Layered architecture: Presentation (API), Service (business logic), Integration (external connectors), Model
- Strategy/Adapter pattern for supporting multiple package manager ecosystems
- Configuration-driven parameters (tea.yaml) to tune kappa, delta, depth/width thresholds
- Separation of concerns: routing vs. algorithm vs. data‐fetching vs. config

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client Layer"
        Client["REST Client (curl, CLI)"]:::client
        Example["Usage Demo"]:::client
    end

    subgraph "API Layer"
        API["Express API (index.js)"]:::internal
    end

    subgraph "Business Logic Layer"
        Proof["ProofOfContribution"]:::internal
        Config["tea.yaml"]:::config
    end

    subgraph "Integration Layer"
        PMS["PackageManagerService"]:::internal
    end

    subgraph "Data Model"
        Project["Project Model"]:::internal
    end

    subgraph "External Registries"
        Registries["Registry: npm, PyPI, Crates.io, RubyGems"]:::external
    end

    Client -->|"POST /analyze"| API
    Example -->|"POST /analyze"| API
    API -->|"fetchDependencies()"| PMS
    PMS -->|"registry API calls"| Registries
    Registries -->|"dependency lists"| PMS
    PMS -->|"build graph"| Project
    Project -->|"run TEA algorithm"| Proof
    Proof -->|"computed TEA Rank & flags"| API
    API -->|"JSON response"| Client

    click API "https://github.com/doyindev1/proof-of-contribution/blob/main/index.js"
    click Example "https://github.com/doyindev1/proof-of-contribution/blob/main/example.js"
    click Config "https://github.com/doyindev1/proof-of-contribution/blob/main/tea.yaml"
    click Proof "https://github.com/doyindev1/proof-of-contribution/blob/main/services/ProofOfContribution.js"
    click PMS "https://github.com/doyindev1/proof-of-contribution/blob/main/services/PackageManagerService.js"
    click Project "https://github.com/doyindev1/proof-of-contribution/blob/main/models/Project.js"

    classDef internal fill:#cce5ff,stroke:#004085,color:#004085
    classDef external fill:#d4edda,stroke:#155724,color:#155724
    classDef config fill:#fff3cd,stroke:#856404,color:#856404
    classDef client fill:#e2e3e5,stroke:#6c757d,color:#6c757d
```
