# Architecture

## Overview

Collabberry combines **on-chain** and **off-chain** components to manage contributor compensation and peer-to-peer assessments:

* **On-Chain**:
  * Smart contracts hold the tokens and admin roles for each organization.
  * One **TeamPoints** contract is deployed per organization, enabling custom logic (transferability, role-based minting, etc.).
  * A **TeamPointsFactory** contract streamlines deployment of new TeamPoints tokens.
* **Off-Chain**:
  * A single **Backend** (Node.js/Express) hosts APIs for user registration, organization management, and assessment logic.
  * A **Database** (MySQL) stores user profiles, agreements, organizations, and other data not strictly required on-chain.
  * **Cron Jobs** (node-cron) automate round creation and completion based on your organization’s schedule.

This hybrid approach lets you keep critical ownership data in a decentralized, **trustless** manner, while storing less security-sensitive data in a **centralized** but scalable and flexible environment (the database).

***

### High-Level Diagram

Below is a conceptual diagram of how all the pieces fit together:

```
            ┌────────────────────┐
            │    User Wallet     │
            │ (MetaMask, etc.)   │
            └─────────┬──────────┘
                      │
    1) Sign TX/requests    2) API calls for user data
                      │
                      ▼
        ┌─────────────────────────┐
        │      Front-End UI       │
        │        (Web App)        │
        └─────────┬───────────────┘
                  │  (HTTP)
                  ▼
        ┌─────────────────────────┐
        │     Collabberry API     │
        │  (Node.js + Express)    │
        └─────────┬───────────────┘
                  │ 
     (Database IO)│               (Smart Contract IO)
                  ▼               ▼
┌──────────────────────┐     ┌─────────────────────────┐
│ Database (MySQL)     │     | Blockchain (Arbitrum)   │
│  - Users             │     │  - TeamPointsFactory    │
│  - Orgs, Rounds      │     │  - TeamPoints           │
│  - Agreements        │     │   (Deployed per org)    │
└──────────────────────┘     └─────────────────────────┘
```

### Components

1. **Smart Contracts (On-Chain)**
   * **Purpose:** Hold each organization’s “Team Points,” enforce admin roles, and perform final token minting.
   * **Stack:**
     * Solidity (v0.8.20)
     * **TeamPointsFactory** (deploys **TeamPoints** instances per org)
     * Deployed to Arbitrum
2. **Backend (Off-Chain)**
   * **Purpose:** Performs all core logic off-chain (round creation, assessment calculations). Interfaces with the blockchain only for contract deployments and calls.
   * **Stack:**
     * **Node.js + TypeScript** + **Express** for APIs
     * **TypeORM**  for database interactions
3. **Database (Off-Chain)**
   * **Purpose:** Stores user profiles, organization settings, rounds, and assessments.
   * **Stack: MySQL**
4. **Cron Jobs Server (Off-Chain)**
   * **Purpose:** Automate round start/end processes (createRounds, completeRounds). The Berry Algorithm and the core of the platform. Read more here. 
   * **Stack:**
     * **NodeJS + Typescript** 
     * node-cron
5. **User Wallet & Front-End**
   * **Purpose:**
     * **Wallet**: Provides cryptographic ownership (e.g., MetaMask) for admin minting or signing transactions.
     * **Front-End**: Simple web or mobile client for user interactions (submitting assessments, viewing org data).
   * **Stack:**
     * **Web3** integration (ethers.js & rainbow wallet) for on-chain calls
     * React JS

***

#### Why This Setup?

* **Security**: On-chain minting/roles stay under admin control (private keys not stored in the backend).
* **Low Gas Costs**: All assessment data and round logic remain off-chain, cutting down on transaction fees.
* **Scalability**: The backend and database can handle potentially large volumes of round/assessment data without incurring on-chain costs.
* **Modularity**: Each organization has its own **TeamPoints** contract, while a single backend + DB handle all off-chain needs.