Monorepo Structure

Relevant source files

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

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

The OnChain Sage project is organized as a modular monorepo. This structure is designed to manage the various distinct services—frontend, backend, data processing, and blockchain contracts—within a single repository. This approach promotes code sharing, simplifies dependency management, and streamlines the development and contribution process, which is a key goal for this open-source project.

The monorepo is managed using NPM workspaces, allowing for the installation of dependencies and execution of scripts across the different applications from the root directory. This modularity ensures that components are loosely coupled and can be developed, tested, and deployed independently.

Sources: README.md:21-25, README.md:73-76, ARCHITECTURE.md:12-16

High-Level Directory Structure

The project is divided into several top-level directories, each with a specific responsibility. The primary logic is contained within the apps and packages directories.

This diagram illustrates the main folder organization of the monorepo.

The following table describes the purpose of each main directory.

Directory	Purpose
apps/	Contains the main, runnable applications of the OnChain Sage platform.
packages/	Contains shared utilities, UI components, SDKs, and other common code used across the applications in apps/.
docs/	Holds project documentation, including architecture documents and setup guides.
infrastructure/	Contains scripts and configuration for deployment, such as Docker and Kubernetes files.
.github/	Stores GitHub-specific files, including issue templates and CI/CD workflow configurations.

Sources: README.md:78-88, apps/dojo/README.md:104-107, ARCHITECTURE.md:105-107

Core Applications (apps/)

The apps directory houses the individual services that constitute the OnChain Sage platform. Each application is a self-contained project with its own dependencies and scripts.

apps/frontend

The frontend is a Next.js application that serves as the user interface and dashboard for the platform.

• Purpose: Provides real-time data visualization, user interaction handling, and WebSocket communication for live updates.
• Tech Stack: Next.js, React, TypeScript, Tailwind CSS, Chart.js/D3.js, Zustand.
• Key Dependencies:
  • next: Core framework.
  • react, react-dom: UI library.
  • tailwindcss: CSS styling.
  • @starknet-react/core, starknet: Starknet wallet integration.
  • recharts: Charting library.
  • lucide-react: Icon library.

Sources: ARCHITECTURE.md:22-35, apps/frontend/README.md:3-9, apps/frontend/package.json:9-29

apps/backend

The backend is a NestJS application that functions as the API gateway and handles core business logic.

• Purpose: Manages API requests, user authentication, signal generation coordination, and caching with Redis.
• Tech Stack: NestJS, Node.js, TypeScript, PostgreSQL, TypeORM, JWT.
• Key Dependencies:
  • @nestjs/core: Core framework.
  • @nestjs/typeorm, pg: PostgreSQL database integration.
  • @nestjs/jwt, passport-jwt: Authentication.
  • @nestjs/websockets, socket.io: Real-time communication.
  • starknet: Starknet blockchain interaction.
  • ioredis: Redis client.

Sources: ARCHITECTURE.md:37-49, apps/backend/README.md:14-19, apps/backend/package.json:20-56

apps/data-processing

This is a Python-based service responsible for all data ingestion and analysis.

• Purpose: Ingests data from sources like the X API and on-chain providers, performs sentiment analysis using ML models, and aggregates data into trading signals.
• Tech Stack: Python, TensorFlow, PyTorch, OpenAI API.
• Key Dependencies:
  • pandas: Data manipulation.
  • tensorflow, pytorch: Machine learning.
  • python-twitter: X API client (inferred from X (Twitter) Scraper component).

Sources: ARCHITECTURE.md:51-63, apps/data-processing/README.md:3-23, apps/data-processing/setup.py:24-25

apps/dojo

This directory contains the Starknet smart contracts, built using the Dojo framework.

• Purpose: Manages on-chain logic, including signal registration, user staking, community validation, and reputation systems.
• Tech Stack: Cairo, Dojo, Starknet.
• Project Structure:
  • src/: Contains Cairo source for models, systems, and contracts.
  • scripts/: Deployment and utility shell scripts.
  • Scarb.toml: Cairo package manager configuration.
  • dojo_*.toml: Environment-specific configurations for the Dojo world.

Sources: ARCHITECTURE.md:65-83, apps/dojo/README.md:18-24, apps/dojo/README.md:98-107

Shared Packages (packages/)

The packages/ directory is intended for code that is shared across multiple applications. This promotes reusability and maintains a single source of truth for common functionalities.

Package	Intended Purpose
ui/	Shared React components for a consistent look and feel across frontends.
sdk/	A Software Development Kit for interacting with the backend API and smart contracts.
common/	Shared types, interfaces, and utility functions.
integrations/	Modules for integrating with third-party APIs (e.g., Dex Screener, Raydium).

Sources: README.md:85-88

Tooling and Scripts

The monorepo utilizes several tools and scripts to manage development workflows.

NPM Workspaces

NPM workspaces are used to manage the multiple projects within the apps/ directory. A single npm install command at the root of the repository will install dependencies for all workspaces.

Scripts for individual applications can be run from the root using the --workspace flag.
Sources: README.md:69-71, README.md:73-76

Key Scripts

The following table summarizes important scripts defined in the project's package.json files.

Script	Location	Description
backend	package.json	Starts the backend development server. Equivalent to cd apps/backend && npm run start:dev.
frontend	package.json	Starts the frontend development server. Equivalent to cd apps/frontend && npm run dev.
start:dev	apps/backend/package.json	Starts the NestJS backend with hot-reloading.
dev	apps/frontend/package.json	Starts the Next.js frontend development server.
build	apps/backend/package.json, apps/frontend/package.json	Builds the respective application for production.
migrate	apps/dojo/Scarb.toml	Builds and migrates the Dojo smart contracts.
test	apps/dojo/Scarb.toml, apps/backend/package.json	Runs the test suite for the respective application.

Sources: package.json:5-8, apps/backend/package.json:7-11, apps/frontend/package.json:4-8, apps/dojo/Scarb.toml:11-16

Dojo and Scarb Configuration

The apps/dojo project uses Scarb as its package manager. The configuration is defined in Scarb.toml.

# apps/dojo/Scarb.toml

[package]
cairo-version = "=2.10.1"
name = "onchainsage_dojo"
version = "0.1.0"

[dependencies]
dojo = { git = "https://github.com/dojoengine/dojo%22%2C tag = "v1.5.0" }

[[target.starknet-contract]]
build-external-contracts = ["dojo::world::world_contract::world"]

This file specifies the project's dependencies, such as the dojo engine, and configures the Starknet contract build targets.

Sources: apps/dojo/Scarb.toml:1-5, apps/dojo/Scarb.toml:18-22

Conclusion

The monorepo structure of OnChain Sage is a strategic choice that supports its goals of being a modular, scalable, and community-driven platform. By separating concerns into distinct applications (apps/) while encouraging code reuse through shared libraries (packages/), the architecture facilitates parallel development and simplifies maintenance. This well-defined structure provides clear entry points for new contributors, whether they are working on the frontend UI, backend services, data analysis pipelines, or on-chain smart contracts.

Sources: README.md:23-25, CONTRIBUTING.md:7-9, ARCHITECTURE.md:12-16