Architecture Overview

OnChain Sage is an AI-driven, decentralized trading assistant that provides crypto traders with actionable insights by combining real-time social sentiment analysis with on-chain market data. The platform is designed with a data-first, modular, and event-driven architecture to promote scalability, maintainability, and community contributions. This structure ensures that data processing is the core driver of the system's functionality, with loosely coupled components that can be developed and scaled independently.

The system is organized into five distinct layers, each with specific responsibilities, from data ingestion to user interaction. This layered approach facilitates a clear separation of concerns, making it easier for contributors to understand and extend the project. The core principles guiding the architecture are a data-first approach, modular design, and scalability through containerization and distributed processing.

Sources: ARCHITECTURE.md:3-20, README.md:16-22

System Architecture Diagram

The following diagram illustrates the high-level, five-layer architecture of OnChain Sage, showing the flow of data and interactions between the major components.

System Components and Layers

The architecture is divided into five main layers, each with a distinct set of responsibilities and technologies.

1. Frontend Layer

The Frontend Layer is responsible for the user interface, data visualization, and handling user interactions. It communicates with the backend via REST APIs and WebSockets for real-time data updates.

• Responsibilities:
  • User interface and dashboard.
  • Real-time data visualization.
  • User interaction handling.
  • WebSocket communication for live updates.
• Technology Stack:
  • Framework: Next.js, React
  • Styling: Tailwind CSS
  • Visualizations: Chart.js, D3.js
  • State Management: Zustand
  • Real-time: WebSocket

Sources: ARCHITECTURE.md:29-43, README.md:52-56, apps/frontend/README.md:5-10

2. Backend Layer

The Backend Layer serves as the central hub for API requests, user authentication, and business logic. It coordinates signal generation, manages caching, and interacts with both the database and the blockchain.

• Responsibilities:
  • Handling API requests from the frontend.
  • User authentication and authorization.
  • Coordinating signal generation and delivery.
  • Caching frequently accessed data with Redis.
• Technology Stack:
  • Framework: NestJS, Node.js
  • Language: TypeScript
  • Database: PostgreSQL with TypeORM
  • Authentication: JWT

Sources: ARCHITECTURE.md:45-59, README.md:58-61, apps/backend/README.md:11-16

3. Data Processing Layer

This layer is responsible for ingesting and processing data from various external sources. It uses machine learning models to perform sentiment analysis and generates trading signals that are then passed to the backend.

• Responsibilities:
  • Ingesting data from sources like the X API, Raydium, and Dex Screener.
  • Performing sentiment analysis on social data using NLP/ML models.
  • Aggregating data to generate trading signals.
• Technology Stack:
  • Language: Python
  • ML/AI: TensorFlow, PyTorch, OpenAI API

Sources: ARCHITECTURE.md:61-75, README.md:63-65, apps/data-processing/README.md:5-20

4. Blockchain Integration

This layer manages all interactions with the Starknet blockchain. It includes smart contracts for handling staking, signal validation, and reputation management, all built using the Dojo framework.

• Responsibilities:
  • Smart contract management for signals, staking, and validation.
  • Handling STRK token transactions for staking and rewards.
  • Managing user reputation scores based on validation accuracy.
• Technology Stack:
  • Network: Starknet
  • Language: Cairo
  • Framework: Dojo
• Key Smart Contract Models:
  • Signal: Stores trading signal data.
  • Stake: Tracks user stakes on signals.
  • ValidationVote: Records community votes on signal credibility.
  • UserReputation: Manages user reputation scores.

Sources: ARCHITECTURE.md:77-101, README.md:67-71, apps/dojo/README.md:18-24

5. Database and Infrastructure

This layer provides the foundational support for the entire system, including data persistence, caching, and scalable deployment infrastructure.

• Responsibilities:
  • Persistent storage of application data.
  • In-memory caching for performance.
  • Containerized, scalable deployment and infrastructure management.
• Technology Stack:
  • Database: PostgreSQL, Redis
  • Deployment: Docker, Kubernetes
  • Cloud: AWS/GCP

Sources: ARCHITECTURE.md:103-113, README.md:73-77

Data Flow

The system follows a data-first approach, where the flow and processing of data drive all functionality.

The data flow can be visualized as follows:

This flow ensures that data is ingested, processed, stored, and delivered efficiently to the user in real-time.

Sources: ARCHITECTURE.md:115-139

Technology Stack Summary

The following table summarizes the key technologies used across the different layers of the OnChain Sage architecture.

Sources: ARCHITECTURE.md:29-113, README.md:50-77