Relevant source files

The following files were used as context for generating this wiki page: - [README.md](https://github.com/all0x0/onchainsage/blob/main/README.md) - [ARCHITECTURE.md](https://github.com/all0x0/onchainsage/blob/main/ARCHITECTURE.md) - [CONTRIBUTING.md](https://github.com/all0x0/onchainsage/blob/main/CONTRIBUTING.md) - [apps/frontend/README.md](https://github.com/all0x0/onchainsage/blob/main/apps/frontend/README.md) - [apps/backend/README.md](https://github.com/all0x0/onchainsage/blob/main/apps/backend/README.md) - [apps/data-processing/README.md](https://github.com/all0x0/onchainsage/blob/main/apps/data-processing/README.md) - [apps/dojo/README.md](https://github.com/all0x0/onchainsage/blob/main/apps/dojo/README.md) - [apps/frontend/components/Layout/features.tsx](https://github.com/all0x0/onchainsage/blob/main/apps/frontend/components/Layout/features.tsx) - [package.json](https://github.com/all0x0/onchainsage/blob/main/package.json)

# Welcome to OnChainSage OnChain Sage is an open-source, AI-driven, decentralized trading assistant designed to provide crypto traders with actionable insights. It achieves this by integrating real-time social sentiment analysis from sources like X (formerly Twitter) with on-chain market data from platforms such as Raydium and Dex Screener. The platform leverages AI and blockchain technologies to monitor trends, liquidity, volume, and whale activity, delivering reliable trading signals through a user-friendly dashboard. The project is built with a modular, data-first architecture to encourage community contributions and ensure scalable, robust performance. It utilizes the Starknet network for its decentralized components, including a payment model based on the STRK token. This document provides a high-level overview of the project's architecture, features, and development setup. Sources: [README.md:7-12](), [ARCHITECTURE.md:5-9]() ## Core Concept OnChain Sage is founded on three core principles that guide its development and functionality. * **Data-Driven Trading:** The system integrates social sentiment analysis with on-chain analytics to generate comprehensive trading signals. * **Decentralized Payment Model:** It uses the Starknet network and STRK tokens to manage gas fees and access to premium features, ensuring a decentralized operational framework. * **Open-Source Collaboration:** The project is structured as a modular monorepo, which simplifies maintenance and scalability, encouraging a vibrant community of contributors. Sources: [README.md:21-26]() ## Key Features The platform offers a suite of features designed to empower traders. | Feature | Description | Source File | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | **AI-Powered Analysis** | Utilizes advanced NLP and ML models to analyze Twitter data and detect emerging crypto trends. | `apps/frontend/components/Layout/features.tsx:15-18` | | **On-Chain Data Insights** | Monitors key on-chain metrics like liquidity, volume, and whale activity through various APIs. | `README.md:31-32` | | **Actionable Trading Signals** | Provides categorized signals (e.g., high-confidence, emerging, risky) to help guide trading decisions. | `README.md:33-34` | | **User-Friendly Dashboard** | A responsive interface built with Next.js, featuring dynamic data visualizations using Chart.js and D3.js. | `README.md:35-36` | | **Secure Blockchain Integration** | Employs smart contracts written in Cairo on the Starknet network to manage STRK token transactions and premium access securely. | `README.md:37-38` | | **Decentralized Payment** | Leverages the Starknet network and STRK tokens for handling gas fees and premium service payments. | `apps/frontend/components/Layout/features.tsx:39-42` | | **Community Signal Validation** | Allows users to vote on signal credibility, with votes weighted by reputation, influencing signal rankings and reward distribution. | `ARCHITECTURE.md:71-73` | | **Signal Staking** | Users can stake STRK tokens on trading signals to show confidence, with rewards distributed based on the signal's accuracy. | `ARCHITECTURE.md:69-70` | ## Architecture Overview OnChain Sage is built on a data-first, modular, and event-driven architecture. This design promotes scalability and loose coupling between components, making the system maintainable and adaptable for open-source contributors. The architecture is divided into five distinct layers, each with specific responsibilities. Sources: [ARCHITECTURE.md:11-16]() The following diagram illustrates the high-level system architecture and the interaction between its layers. ```mermaid graph TD subgraph User Interaction A[Frontend Layer
Next.js, React] end subgraph Core Services B[Backend Layer
NestJS, Node.js] end subgraph Data & AI C[Data Processing Layer
Python, TensorFlow, PyTorch] end subgraph Blockchain D[Blockchain Integration
Starknet, Dojo, Cairo] end subgraph Infrastructure E[Database & Infrastructure
PostgreSQL, Redis, Docker] end A -- REST API / WebSocket --> B B -- Caching / Persistence --> E B -- Signal Coordination --> C C -- Data Ingestion --> F[External APIs
X, Raydium, Dex Screener] C -- Data Aggregation --> E D -- Smart Contracts --> G[Starknet Network] B -- On-chain Interactions --> D ``` Sources: [ARCHITECTURE.md:18-24]() ### System Components & Tech Stack Each layer of the architecture utilizes a specific set of technologies to fulfill its role. | Layer | Technologies | Primary Responsibilities | Source Files - | | ----------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Frontend** | Next.js, React, Tailwind CSS, Chart.js/D3.js | UI/Dashboard, real-time data visualization, user interaction, WebSocket communication. | `ARCHITECTURE.md:30-38` - | | **Backend** | NestJS, Node.js, TypeScript, PostgreSQL, Redis | API request handling, user authentication, signal coordination, and caching. | `ARCHITECTURE.md:40-49` - | | **Data Processing** | Python, TensorFlow, PyTorch, OpenAI API | Data ingestion, sentiment analysis, signal generation, and data aggregation. | `ARCHITECTURE.md:51-60` - | | **Blockchain** | Starknet, Cairo, Dojo | Smart contract management, token transactions (staking, rewards), and community validation. | `ARCHITECTURE.md:62-81` - | - **Database & Infra** | PostgreSQL, Redis, Docker, Kubernetes | Data persistence, caching, scalable deployment, and infrastructure management. | `ARCHITECTURE.md:83-91` - | ## Data Flow The system's functionality is driven by its data-first approach, ensuring that data is processed efficiently and delivered in real-time. This diagram shows the sequential flow of data through the system. ```mermaid flowchart TD A[Data Ingestion
X API, Raydium, Dex Screener] --> B[Data Processing
NLP/ML Analysis, Signal Generation] B --> C[Storage
PostgreSQL, Redis, Event Logging] C --> D[Signal Delivery
REST API, WebSocket] D --> E[User Interaction
Dashboard, Signal Viewing] ``` Sources: [ARCHITECTURE.md:93-112]() ## Project Structure OnChain Sage is organized as a monorepo, managed with `npm` workspaces. This structure separates each major component into its own application directory under `apps/`, while shared utilities and packages are located in `packages/`. ```mermaid graph TD subgraph onchainsage A(apps) B(packages) C(docs) D(infrastructure) end A --> A1(frontend) A --> A2(backend) A --> A3(data-processing) A --> A4(dojo) B --> B1(ui) B --> B2(sdk) B --> B3(integrations) ``` This structure is detailed in the main `README.md`. Sources: [README.md:92-106]() ## Getting Started To begin contributing to OnChain Sage, you'll need to set up the development environment. ### Prerequisites * Node.js (v14+) * Python (3.8+) * Docker * A Starknet wallet (e.g., Argent or Braavos) Sources: [README.md:71-76](), [CONTRIBUTING.md:27-30]() ### Installation and Setup 1. **Fork and Clone:** Fork the repository on GitHub and clone it to your local machine. ```bash git clone https://github.com/your-username/onchainsage.git cd onchainsage ``` Sources: [CONTRIBUTING.md:16-19]() 2. **Install Dependencies:** Use `npm` to install dependencies for all workspaces. ```bash npm install ``` Sources: [README.md:82-84]() 3. **Environment Configuration:** Create `.env` files for each application in the `apps/` directory based on the examples provided. Sources: [README.md:86-87]() 4. **Run Applications:** Start the individual services using the workspace commands. * **Frontend:** `npm run dev --workspace=apps/frontend` * **Backend:** `npm run start:dev --workspace=apps/backend` For data processing and blockchain services, refer to the `README.md` files within their respective directories. Sources: [README.md:90-91](), [package.json:5-8]() ## Contributing Contributions from the community are highly encouraged. The development process follows a standard fork-and-pull-request model. 1. **Create a Branch:** Create a new feature or bugfix branch from `main`. 2. **Commit Changes:** Make your changes and write clear, concise commit messages. 3. **Run Tests:** Ensure all tests pass and that code is formatted according to project standards using linters like ESLint and Prettier. 4. **Submit a Pull Request:** Open a PR against the `main` branch with a detailed description of your changes. For more detailed guidelines on branching strategy, code standards, and communication channels, please refer to the [CONTRIBUTING.md](https://github.com/all0x0/onchainsage/blob/main/CONTRIBUTING.md) file. Sources: [CONTRIBUTING.md:10-40]()