Getting Started

Relevant source files

The following files were used as context for generating this wiki page:

• ARCHITECTURE.md
• CONTRIBUTING.md
• README.md
• apps/backend/README.md
• apps/data-processing/README.md
• apps/dojo/README.md
• apps/frontend/README.md
• package.json

OnChain Sage is an AI-driven, decentralized trading assistant that provides actionable insights by combining real-time social sentiment analysis with on-chain market data. It is built as an open-source, modular system to encourage community contributions for scalability and innovation.

This guide provides a comprehensive walkthrough for setting up the development environment, running the various services, and understanding the project structure. It is intended for developers who wish to contribute to the project or run a local instance for evaluation. For a deeper dive into the system's design, refer to the Architecture documentation.

Sources: README.md:5-18, ARCHITECTURE.md:5-11

Prerequisites

Before you begin, ensure you have the following tools installed on your system. This setup is required to run all components of the OnChain Sage platform, including the frontend, backend, data processing services, and Starknet smart contracts.

Tool	Version	Notes	Source
Node.js	14+ / 16+	Required for frontend and backend services.	README.md:51, apps/backend/README.md:31
npm		Comes with Node.js. Used for dependency management.	README.md:52
Python	3.8+	Required for the data processing services.	README.md:53, apps/data-processing/setup.py:20
Docker		Recommended for containerized development and running services like PostgreSQL.	README.md:54
Dojo	v1.2.2+	The toolchain for Starknet smart contracts written in Cairo.	ARCHITECTURE.md:60, apps/dojo/README.md:25
Starknet Wallet		e.g., Argent or MetaMask, for interacting with the Starknet blockchain.	README.md:55
Starknet Foundry	(Optional)	Used for testing smart contracts.	apps/dojo/README.md:26

Installation and Setup

The project is a monorepo managed with npm workspaces. The initial setup involves cloning the repository and installing all dependencies from the root directory.

Sources: README.md:58-65, CONTRIBUTING.md:20-22

1. Clone the Repository

First, clone the forked repository to your local machine.

git clone https://github.com/your-username/onchainsage.git
cd onchainsage

Sources: README.md:62-63, CONTRIBUTING.md:20-22

2. Install Dependencies

Install all necessary dependencies for all workspaces (frontend, backend, etc.) by running npm install from the root of the project.

npm install

Sources: README.md:65-67

3. Environment Configuration

Each application within the apps/ directory requires its own environment configuration file (e.g., .env). You should create these files based on the provided examples. For instance, for the backend service:

cd apps/backend
cp .env.development.example .env.development

After copying, you must edit the .env.development file to include your specific credentials, such as database connection details.

Sources: README.md:69-71, apps/backend/README.md:52-56

Project Structure

OnChain Sage uses a monorepo structure to manage its different services. This modular design promotes separation of concerns and simplifies development across the stack.

The diagram below illustrates the high-level folder structure.

This diagram shows the main directories within the monorepo.

• apps/: Contains the individual, runnable applications like the frontend, backend, and data processing services.
• packages/: Holds shared code, such as UI components, SDKs, and common utilities used across different apps.

Sources: README.md:83-95

Running the Applications

Each service can be run locally from the project root using npm workspace commands or from their respective directories.

Frontend

The frontend is a Next.js application.

• To run:

  npm run dev --workspace=apps/frontend
  

• URL: The application will be available at http://localhost:3000.
• The main page can be edited by modifying apps/frontend/app/page.tsx.

Sources: README.md:74-75, apps/frontend/README.md:17-23, apps/frontend/README.md:30

Backend

The backend is a NestJS application that requires a PostgreSQL database.

1. Database Setup:

   -- Connect to PostgreSQL
   psql -U postgres
   
   -- Create the database
   CREATE DATABASE onchainsage;
   

2. Run the server:

   npm run start:dev --workspace=apps/backend
   

   This command starts the server in development mode with hot-reloading.

Sources: README.md:78-79, apps/backend/README.md:44-50, apps/backend/README.md:61-62

Data Processing

The data processing pipeline is built with Python.

1. Setup Virtual Environment:

   cd apps/data-processing
   python -m venv venv
   source venv/bin/activate  # On Unix/macOS
   

2. Install Dependencies:

   pip install -e .
   

3. Run Tests (as an example of execution):

   pytest tests/
   

Sources: apps/data-processing/README.md:33-43

Dojo (Smart Contracts)

The Starknet smart contracts are managed with the Dojo toolchain.

1. Install/Update Dojo:

   curl -L https://install.dojoengine.org | bash
   dojoup
   

2. Start Local Devnet: Run a local Starknet node using Katana.

   katana
   

3. Build and Deploy:

   cd apps/dojo
   sozo build
   sozo migrate
   

   This builds the contracts and deploys them to the local Katana node.

Sources: apps/dojo/README.md:29-33, apps/dojo/README.md:66-72

Development and Contribution Workflow

The project encourages community contributions. The standard workflow follows a fork-and-pull model.

The sequence diagram below outlines the contribution process.

Key Steps

1. Fork & Clone: Fork the repository on GitHub and clone it locally.
2. Create a Branch: Create a new branch for your feature or bugfix (e.g., feature/your-feature-name).
3. Commit Changes: Make your changes and commit them with a descriptive, conventional commit message (e.g., feat:, fix:, docs:).
4. Run Tests: Ensure all tests pass before submitting. Use npm test for frontend/backend and pytest for Python services.
5. Push and PR: Push your branch to your fork and open a pull request against the main branch of the original repository.

Sources: CONTRIBUTING.md:17-40, ARCHITECTURE.md:126-136