rust-backend

The Intuition Rust Monorepo

The intuition-rs repository is organized as a Rust workspace, which provides several key benefits:

Monorepo Architecture

A monorepo (monolithic repository) consolidates all backend services and shared code in a single repository, offering:

• Code sharing: Common utilities and models shared across all services
• Unified versioning: All services stay in sync with compatible versions
• Atomic changes: Update multiple services in a single commit
• Simplified dependencies: Internal dependencies managed through workspace
• Consistent tooling: Shared build, test, and lint configurations

Workspace Organization

The workspace is structured into logical layers:

Applications Layer (apps/)

Independent services that can be deployed separately:

• Each app has its own binary
• Shared dependencies managed at workspace level
• Services communicate through well-defined interfaces

Infrastructure Layer

Supporting services for data storage and APIs:

• Database migrations and schema management
• GraphQL API configuration
• Monitoring and observability tools

Shared Libraries

Common code used across multiple services:

• Domain models
• Utility functions
• Shared business logic

Development Benefits

• Faster builds: Cargo caches dependencies and only rebuilds what changed
• Type safety across services: Shared types ensure compatibility
• Easier refactoring: Changes to shared code immediately show impact
• Consistent testing: Run all tests with a single command

Project Structure

intuition-rs/
├── apps/                 # Custom Rust applications
│   ├── cli/             # Terminal UI client
│   ├── consumer/        # Event processing pipeline (Redis Streams)
│   ├── histocrawler/    # Historical data crawler
│   ├── image-guard/     # Image processing service
│   ├── models/          # Domain models & data structures
│   ├── rpc-proxy/       # RPC proxy with caching
│   └── shared-utils/    # Common utilities
├── infrastructure/      # Infrastructure components
│   ├── hasura/         # GraphQL API & migrations
│   ├── blockscout/     # Blockchain explorer
│   ├── drizzle/        # Database schema management
│   ├── geth/           # Local Ethereum node config
│   ├── indexer-and-cache-migrations/  # Database migrations
│   ├── migration-scripts/  # Migration utilities
│   └── prometheus/     # Monitoring configuration
├── docker/             # Docker configuration
│   ├── docker-compose-apps.yml   # Application services
│   ├── docker-compose-shared.yml # Shared infrastructure
│   └── Dockerfile      # Multi-stage build
├── scripts/            # Shell scripts
│   ├── start.sh        # System startup
│   ├── stop.sh         # System shutdown
│   ├── cli.sh          # CLI runner
│   ├── init-dbs.sh     # Database initialization
├── integration-tests/  # End-to-end tests
└── README.md          # Project documentation

Core Applications

CLI

Terminal UI client for interacting with the Intuition system

• Interactive command-line interface
• Real-time data verification
• Development and debugging tool

Consumer

Event processing pipeline using Redis Streams

• RAW Consumer: Ingests raw blockchain events
• DECODED Consumer: Decodes and parses events
• RESOLVER Consumer: Resolves and enriches data
• IPFS-UPLOAD Consumer: Manages IPFS content uploads

Histocrawler

Historical data crawler for blockchain indexing

• Fetches historical blockchain data
• Processes past events
• Builds complete data history

Image Guard

Image processing and validation service

• Image validation and security scanning
• Format conversion and optimization
• Content moderation

RPC Proxy

RPC call proxy with intelligent caching

• Caches eth_call method results
• Reduces load on upstream RPC providers
• Improves query performance

Models

Domain models and data structures

• Shared data types
• Business logic models
• Database entity definitions

Shared Utils

Common utilities used across services

• Helper functions
• Shared configurations
• Reusable components

Infrastructure Components

The infrastructure layer provides essential services:

• Hasura: GraphQL API engine with database migrations
• Blockscout: Blockchain explorer for network transparency
• Drizzle: Type-safe database schema management
• Geth: Local Ethereum node for development
• Prometheus: Metrics collection and monitoring

Development Tools

The repository includes comprehensive tooling:

• Docker Compose: Orchestrates all services for local development
• Cargo Make: Task automation and build scripts
• Integration Tests: End-to-end testing with pnpm
• Shell Scripts: Quick commands for common operations

Why Rust?

The Intuition backend is built with Rust, a systems programming language that offers unique advantages for blockchain infrastructure:

Performance and Efficiency

Zero-cost abstractions: Write high-level code without runtime overhead
Memory efficiency: Minimal memory footprint compared to garbage-collected languages
Concurrent processing: Built-in support for safe concurrent operations
Native performance: Compiles to machine code for maximum speed

Safety and Reliability

Memory safety: Eliminates entire classes of bugs (null pointer dereferences, buffer overflows, data races)
Type safety: Strong static typing catches errors at compile time
Error handling: Explicit error handling through Result types
No runtime crashes: Memory safety guarantees prevent unexpected crashes

Developer Experience

Modern tooling: Cargo package manager and build system
Rich ecosystem: Growing library ecosystem for blockchain and web services
Documentation: Built-in documentation tools and testing framework
Community: Active and supportive open-source community

Blockchain-Specific Benefits

Predictable performance: No garbage collection pauses during critical operations
Resource optimization: Efficient resource usage for indexing large amounts of blockchain data
WebAssembly support: Can compile to WASM for cross-platform compatibility
Security: Memory safety is crucial when handling financial transactions and user data