Contributing Guide

Welcome Contributors

Thank you for your interest in contributing to Deriverse! This guide will help you get started with contributing to the project.

Getting Started

Set up your development environment

Follow the Local Setup Guide to clone the repository and install dependencies.

Find an issue or feature to work on

Browse the GitHub Issues to find something to work on, or propose your own feature.

Create a branch

Create a new branch for your work:

git checkout -b feat/your-feature-name

Make your changes

Implement your changes following our code style guidelines.

Test your changes

Ensure everything works:

npm run dev
npm run lint

Commit and push

Commit using Conventional Commits and push to your fork.

Create a pull request

Open a PR against the main branch with a clear description of your changes.

Code Style

Deriverse follows consistent coding standards to maintain code quality and readability.

TypeScript Guidelines

// Good: Use explicit types
interface Trade {
  id: string;
  timestamp: number;
  pnl: number;
}

function calculateWinRate(trades: Trade[]): number {
  // Implementation
}

// Avoid: Using 'any'
function processData(data: any) { // ❌
  // Implementation
}

File Organization

Follow the established project structure:

src/
├── app/                       # Next.js pages (App Router)
│   ├── page.tsx              # Home page
│   ├── journal/page.tsx      # Journal page
│   └── layout.tsx            # Root layout
├── components/
│   ├── features/             # Feature-specific components
│   │   ├── Home/
│   │   ├── Journal/
│   │   └── Trades/
│   ├── layout/               # Layout components
│   │   ├── Header/
│   │   └── Sidebar/
│   └── ui/                   # Reusable UI components
│       ├── Button/
│       ├── Modal/
│       └── Card/
├── lib/                      # Utilities and hooks
│   ├── hooks/
│   │   └── useWalletConnection.ts
│   ├── constants.ts
│   └── utils.ts
├── services/                 # API and database clients
│   ├── SupabaseWalletService.ts
│   ├── SupabaseTradeService.ts
│   └── HeliusService.ts
└── providers.tsx             # Context providers

Component Guidelines

Component structure

// 1. Imports
import { useState } from 'react';
import { Button } from '@/components/ui/Button';

// 2. Types/Interfaces
interface TradeCardProps {
  trade: Trade;
  onEdit?: (id: string) => void;
}

// 3. Component
export function TradeCard({ trade, onEdit }: TradeCardProps) {
  // 4. Hooks
  const [isExpanded, setIsExpanded] = useState(false);
  
  // 5. Event handlers
  const handleToggle = () => setIsExpanded(!isExpanded);
  
  // 6. Render
  return (
    <div>
      {/* Component content */}
    </div>
  );
}

Styling with Tailwind

Use Tailwind CSS utility classes consistently:

// Good: Use Tailwind utilities
<div className="flex items-center gap-4 p-6 bg-slate-900 rounded-lg">
  <h2 className="text-xl font-semibold text-white">Title</h2>
</div>

// Avoid: Inline styles
<div style={{ display: 'flex', padding: '24px' }}> {/* ❌ */}
  <h2 style={{ fontSize: '20px' }}>Title</h2>
</div>

For complex components, use clsx for conditional classes:

import clsx from 'clsx';

<button
  className={clsx(
    'px-4 py-2 rounded-lg font-medium',
    isActive ? 'bg-blue-600 text-white' : 'bg-gray-200 text-gray-700'
  )}
>
  Click me
</button>

Custom hooks

Extract reusable logic into custom hooks:

// lib/hooks/useTradeFilters.ts
export function useTradeFilters(trades: Trade[]) {
  const [filters, setFilters] = useState<FilterState>({
    timeRange: 'all',
    outcome: 'all',
  });

  const filteredTrades = useMemo(() => {
    return trades.filter(trade => {
      // Filter logic
    });
  }, [trades, filters]);

  return { filteredTrades, filters, setFilters };
}

Commit Conventions

Deriverse follows the Conventional Commits specification.

Commit Message Format

<type>(optional scope): <short description>

[optional body]

[optional footer]

Commit Types

Type	Description	Example
`feat`	New feature	`feat(journal): add tag filtering`
`fix`	Bug fix	`fix(trades): handle null pnl values`
`docs`	Documentation changes	`docs(readme): update installation steps`
`style`	Code style changes (formatting, etc.)	`style(button): adjust padding`
`refactor`	Code refactoring	`refactor(services): extract common logic`
`perf`	Performance improvements	`perf(trades): optimize filter algorithm`
`test`	Adding or updating tests	`test(utils): add trade calculation tests`
`build`	Build system changes	`build(deps): update next to 16.2.0`
`ci`	CI/CD changes	`ci(github): add test workflow`
`chore`	Other changes	`chore(gitignore): add .env.local`

Examples

git commit -m "feat(journal): add streak tracking visualization

Implements a new component to display trading streaks with
animated counters and color-coded win/loss indicators."

Commit messages are enforced via automated checks. Commits that don’t follow the convention will be rejected.

Pull Request Process

Before Submitting

PR Template

When creating a pull request, include:

## Summary
Brief description of what this PR does.

## Changes
- List of changes made
- Another change

## Testing
How to test these changes:
1. Step one
2. Step two

## Screenshots (if applicable)
[Add screenshots for UI changes]

## Related Issues
Closes #123

Review Process

Automated checks: CI/CD runs linting and build checks
Code review: Maintainers review your code and provide feedback
Revisions: Address feedback and push updates
Approval: Once approved, your PR will be merged

Be patient and responsive to feedback. Code reviews help maintain quality and are a learning opportunity.

Testing

Manual Testing

Always test your changes manually:

# Start dev server
npm run dev

# Test in browser
# - Navigate to affected pages
# - Test different screen sizes
# - Check browser console for errors

Agentation for Visual Testing

Deriverse uses Agentation for visual feedback:

Run the app with npm run dev
Use the on-screen overlay to annotate UI issues
Share feedback with screenshots or recordings

Future: Unit Testing

Unit tests will be added using Jest and React Testing Library. When implemented:

# Run tests
npm test

# Run tests in watch mode
npm test -- --watch

Project-Specific Guidelines

Working with Supabase

When modifying database interactions:

Use services: Always use the service layer (src/services/) instead of direct Supabase calls
Type safety: Define TypeScript interfaces for database tables
Error handling: Always handle errors gracefully

// Good: Using service layer with error handling
try {
  const trades = await SupabaseTradeService.getTradesByWallet(walletAddress);
  return trades;
} catch (error) {
  console.error('Failed to fetch trades:', error);
  return [];
}

Working with Solana

When adding blockchain functionality:

Use devnet: Always test with devnet first
Handle connection errors: Network calls can fail
Consider rate limits: Especially with public RPC endpoints

// Good: Proper error handling for blockchain calls
try {
  const connection = new Connection(process.env.NEXT_PUBLIC_RPC_HTTP!);
  const balance = await connection.getBalance(publicKey);
  return balance;
} catch (error) {
  console.error('Failed to fetch balance:', error);
  throw new Error('Blockchain connection failed');
}

UI/UX Guidelines

Deriverse emphasizes premium, vibrant UI:

Animations: Use Framer Motion for smooth transitions
Colors: Follow the Tailwind config color palette
Responsive: Test on mobile, tablet, and desktop
Accessibility: Include ARIA labels and keyboard navigation

Development Workflow

Agentic Development (Recommended)

Deriverse is built using an agentic workflow:

Planning: Create an implementation plan for complex features
Execution: Break work into small, focused commits
Verification: Use Agentation for visual feedback
Documentation: Update relevant docs as you go

Branch Naming

Use descriptive branch names:

# Features
feat/add-portfolio-analytics
feat/export-journal-pdf

# Bug fixes
fix/wallet-connection-timeout
fix/trade-filter-crash

# Documentation
docs/update-api-reference
docs/add-contributing-guide

Resources

Architecture Docs

Understand the system architecture

Trade Types

Browse TypeScript type definitions

Service APIs

Explore service APIs and utilities

GitHub Repository

View source code on GitHub

Getting Help

If you need help or have questions:

Telegram: @yamparalarahul1
X (Twitter): @yamparalarahul1
GitHub Issues: Create an issue

Code of Conduct

Be respectful and professional in all interactions. We’re building together:

Be kind: Treat others with respect
Be constructive: Provide helpful feedback
Be patient: Everyone is learning
Be open: Welcome different perspectives

Credits

Deriverse is designed and engineered by Yamparala Rahul for the Superteam Earn bounty.

Thank you for contributing to Deriverse! Your contributions help make Solana trading analytics better for everyone.

Get Started

Core Features

Platform

Development

Contributing Guide

Welcome Contributors

Getting Started

Code Style

TypeScript Guidelines

File Organization

Component Guidelines

Commit Conventions

Commit Message Format

Commit Types

Examples

Pull Request Process

Before Submitting

PR Template

Review Process

Testing

Manual Testing

Agentation for Visual Testing

Future: Unit Testing

Project-Specific Guidelines

Working with Supabase

Working with Solana

UI/UX Guidelines

Development Workflow

Agentic Development (Recommended)

Branch Naming

Resources

Architecture Docs

Trade Types

Service APIs

GitHub Repository

Getting Help

Code of Conduct

Credits

Build docs developers (and LLMs) love

Get Started

Core Features

Platform

Development

​Welcome Contributors

​Getting Started

​Code Style

​TypeScript Guidelines

​File Organization

​Component Guidelines

​Commit Conventions

​Commit Message Format

​Commit Types

​Examples

​Pull Request Process

​Before Submitting

​PR Template

​Review Process

​Testing

​Manual Testing

​Agentation for Visual Testing

​Future: Unit Testing

​Project-Specific Guidelines

​Working with Supabase

​Working with Solana

​UI/UX Guidelines

​Development Workflow

​Agentic Development (Recommended)

​Branch Naming

​Resources

Architecture Docs

Trade Types

Service APIs

GitHub Repository

​Getting Help

​Code of Conduct

​Credits

Build docs developers (and LLMs) love

Welcome Contributors

Getting Started

Code Style

TypeScript Guidelines

File Organization

Component Guidelines

Commit Conventions

Commit Message Format

Commit Types

Examples

Pull Request Process

Before Submitting

PR Template

Review Process

Testing

Manual Testing

Agentation for Visual Testing

Future: Unit Testing

Project-Specific Guidelines

Working with Supabase

Working with Solana

UI/UX Guidelines

Development Workflow

Agentic Development (Recommended)

Branch Naming

Resources

Getting Help

Code of Conduct

Credits