> For the complete documentation index, see [llms.txt](https://collabberry.gitbook.io/collabberry-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://collabberry.gitbook.io/collabberry-docs/technical/editor.md).

# 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://collabberry.gitbook.io/collabberry-docs/technical/editor.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.