Ziya/CONTRIBUTORS.md

Contributors Guide

Welcome to the Ziya Token Monitor development team! This guide will help you get up and running quickly with the project.

🚀 Quick Start for New Developers

Prerequisites

Make sure you have these installed:

• Node.js >= 18.0.0
• pnpm >= 8.0.0 (package manager)
• Redis (for local development)
• Git for version control

Installation Steps

1. Clone the repository:

   git clone <repository-url>
   cd muhafidh/ziya
   

2. Install dependencies:

   pnpm install
   

3. Set up Redis (choose one):

   Option A: Docker (Recommended)

   # Run Redis in Docker container
   docker run -d --name bismillahdao-redis -p 6379:6379 redis:alpine
   

   Option B: Local Installation

   # Install Redis locally (varies by OS)
   # macOS: brew install redis
   # Ubuntu: sudo apt install redis-server
   # Windows: Use WSL or Redis for Windows
   

4. Start development:

   pnpm run dev
   

The application will start with:

• Nuxt dev server at http://localhost:3000
• Electron desktop app will launch automatically
• Hot reload enabled for both frontend and Electron

🏗️ Development Architecture

Tech Stack Overview

• Frontend: Vue 3 (Vapor Mode), Nuxt 3, TypeScript
• Desktop: Electron with secure IPC communication
• Styling: TailwindCSS + DaisyUI
• State Management: Pinia
• Backend Integration: Redis (ioredis) for real-time events
• Build Tools: Vite, Electron Forge

Project Structure Deep Dive

ziya/
├── app/                      # Nuxt 3 application
│   ├── components/           # Vue components
│   │   ├── TokenCard.vue     # Individual token display cards
│   │   ├── CexAnalysisCard.vue # CEX analysis results
│   │   └── ...
│   ├── pages/                # Nuxt pages/routes
│   │   └── hunting-ground.vue # Main dashboard
│   ├── stores/               # Pinia state management
│   ├── utils/                # Utility functions
│   │   ├── address.ts        # Solana address handling
│   │   ├── format.ts         # Data formatting
│   │   └── ...
│   └── types/                # TypeScript definitions
├── electron/                 # Electron main process
│   ├── main.ts              # Electron entry point
│   ├── config/              # Configuration files
│   │   ├── environment.ts   # Environment settings
│   │   └── redis.ts         # Redis configuration
│   ├── handlers/            # Event handlers
│   ├── utils/               # Electron utilities
│   │   └── redis.ts         # Redis connection logic
│   └── preload.ts           # Preload script for IPC
├── types/                   # Shared TypeScript types
│   └── redis-events.ts      # Redis event definitions
└── .config/                 # Configuration files
    └── nuxt.ts              # Nuxt configuration

🔧 Development Workflow

Available Scripts

# Development
pnpm run dev              # Start development with hot reload
pnpm run dev:nuxt         # Start only Nuxt dev server
pnpm run dev:electron     # Start only Electron (requires built Nuxt)

# Building
pnpm run build            # Production build
pnpm run build:dev        # Development build
pnpm run build:prod       # Production build (explicit)

# Utilities
pnpm run lint             # Run ESLint
pnpm run type-check       # TypeScript type checking

Environment Configuration

The application automatically detects the environment and configures Redis accordingly:

Development Mode (NODE_ENV=development):

• Redis: localhost:6379 or bismillahdao-redis:6379 (Docker)
• Hot reload enabled
• Debug logging active

Production Mode (NODE_ENV=production):

• Redis: 154.38.185.112:6379 (production server)
• Optimized builds
• Minimal logging

Key Configuration Files

• electron/config/environment.ts - Environment-specific settings
• electron/config/redis.ts - Redis connection configuration
• .config/nuxt.ts - Nuxt configuration
• package.json - Build scripts and dependencies

🎯 Core Features & Components

Real-time Token Dashboard

Location: app/pages/hunting-ground.vue

• Displays three columns of token events
• Real-time updates via Redis subscriptions
• Individual and bulk card management

Token Cards System

Components:

• TokenCard.vue - New token creation events
• CexAnalysisCard.vue - CEX analysis and max depth events

Features:

• Duration calculation from timestamps
• Creator information display
• Graph visualization with hover tooltips
• Click-to-open in browser functionality
• Individual close buttons and "Clear All" actions

Redis Integration

Location: electron/utils/redis.ts

• Subscribes to channels: new_token_created, token_cex_updated, max_depth_reached
• Handles connection management and error recovery
• Forwards events to renderer process via IPC

🐛 Common Development Issues & Solutions

Redis Connection Issues

Problem: ECONNREFUSED when connecting to Redis Solutions:

1. Ensure Redis is running: redis-cli ping
2. Check Docker container: docker ps | grep redis
3. Verify port 6379 is not blocked

Build Errors

Problem: TypeScript compilation errors Solutions:

1. Run type check: pnpm run type-check
2. Clear node_modules: rm -rf node_modules && pnpm install
3. Check for missing dependencies

Hot Reload Not Working

Problem: Changes not reflecting in development Solutions:

1. Restart dev server: Ctrl+C then pnpm run dev
2. Clear Nuxt cache: rm -rf .nuxt
3. Check if both Nuxt and Electron processes are running

📝 Code Style & Best Practices

TypeScript Guidelines

• Use strict type definitions for all Redis events
• Prefer interfaces over types for object shapes
• Use proper error handling with try-catch blocks

Vue Component Guidelines

• Use Composition API with <script setup>
• Keep components focused and single-responsibility
• Use proper TypeScript props definitions

Electron Security

• Never expose Node.js APIs directly to renderer
• Use contextIsolation and sandboxed renderers
• Validate all IPC messages

🔍 Debugging Tips

Electron DevTools

• Main process: Use VS Code debugger or console logs
• Renderer process: Open DevTools in Electron app (Ctrl+Shift+I)

Redis Debugging

• Monitor Redis: redis-cli monitor
• Check subscriptions: redis-cli pubsub channels
• Test publishing: redis-cli publish channel_name "test message"

Common Debug Commands

# Check Redis connection
redis-cli ping

# Monitor Redis events
redis-cli monitor

# Check running processes
ps aux | grep electron
ps aux | grep node

# Check ports
netstat -tulpn | grep :6379
netstat -tulpn | grep :3000

🚀 Deployment & Production

Production Build Process

1. Environment: Automatically uses production Redis server (154.38.185.112:6379)
2. Build: pnpm run build:prod
3. Output: Electron distributables in out/ directory

Production Checklist

• Redis server is accessible at 154.38.185.112:6379
• All dependencies are production-ready
• Environment variables are set correctly
• Build passes without warnings
• Application connects to production Redis successfully

🤝 Contributing Guidelines

Before Starting Development

1. Pull latest changes: git pull origin master
2. Create feature branch: git checkout -b feature/your-feature-name
3. Install dependencies: pnpm install
4. Start development server: pnpm run dev

Code Review Process

1. Ensure all TypeScript types are properly defined
2. Test Redis connectivity in both dev and prod modes
3. Verify Electron security best practices
4. Check for memory leaks in long-running processes
5. Test hot reload functionality

Git Workflow & Release Process

This project uses Conventional Commits with automated changelog generation and semantic versioning.

Branch Management

# Create feature branch from master
git checkout master
git pull origin master
git checkout -b feat/your-feature-name
# or
git checkout -b fix/bug-description

Commit Convention

Follow the conventional commit format:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Available Types:

Type	Emoji	Description	Version Bump
feat	🚀	New features	minor
fix	🐛	Bug fixes	patch
docs	📖	Documentation changes	patch
style	💄	Code style changes	patch
refactor	♻️	Code refactoring	patch
perf	⚡	Performance improvements	patch
test	✅	Adding tests	patch
build	🏗️	Build system changes	patch
ci	🤖	CI/CD changes	patch
chore	🧹	Maintenance tasks	patch
revert	⏪	Reverting changes	patch

Example Commits:

git commit -m "feat: add CEX analysis card component"
git commit -m "fix: resolve timestamp type inconsistency"
git commit -m "docs: update contributors guide"
git commit -m "feat(redis): add production environment configuration"

Breaking Changes:

git commit -m "feat: redesign token card structure

BREAKING CHANGE: TokenCard props have changed from 'data' to 'token'"

Development Workflow

# 1. Create and switch to feature branch
git checkout -b feat/new-feature

# 2. Make changes and commit with conventional format
git add .
git commit -m "feat: add new feature description"

# 3. Push branch and create PR
git push origin feat/new-feature

# 4. After review approval, merge to master

Release Process (Maintainers Only)

Option 1: Full Automated Release (Recommended)

# This will:
# - Generate changelog
# - Update version in package.json
# - Create git tag
# - Commit changes
# - Push to remote
pnpm run release

# Dry run to preview changes
pnpm run release:dry

Option 2: Manual Step-by-Step Release

# Step 1: Generate changelog and update version
pnpm run changelog:release

# Step 2: Review the generated CHANGELOG.md
# Step 3: Create and push tag manually
git tag v0.2.0
git push origin v0.2.0
git push origin master

Option 3: Changelog Only (No version bump)

# Generate changelog without releasing
pnpm run changelog

Version Bumping Rules

• Major (1.0.0): Breaking changes (BREAKING CHANGE: in commit footer)
• Minor (0.1.0): New features (feat: commits)
• Patch (0.0.1): Bug fixes, docs, style, refactor, etc.

Tagging Convention

• Tags follow semantic versioning: v0.1.2, v1.0.0
• Tags are automatically created during release process
• Each tag corresponds to a changelog entry
• Tags trigger automated builds and deployment

Best Practices

• Use present tense: "add feature" not "added feature"
• Use imperative mood: "fix bug" not "fixes bug"
• Keep first line under 72 characters
• Reference issues: "fix: resolve login issue (#123)"
• Always document breaking changes in commit footer
• Be descriptive: Explain what and why, not how

Common Scopes

Use these optional scopes for better organization:

• redis - Redis-related changes
• ui - User interface components
• electron - Electron-specific changes
• build - Build system changes
• docs - Documentation updates

📚 Additional Resources

Documentation

• Electron Documentation
• Nuxt 3 Documentation
• Vue 3 Documentation
• Redis Documentation

Tools & Extensions

• VS Code Extensions: Vue Language Features, TypeScript Vue Plugin
• Redis GUI: RedisInsight, Redis Desktop Manager
• Debugging: Vue DevTools, Electron DevTools

---

🆘 Need Help?

If you encounter issues not covered in this guide:

1. Check the existing issues in the repository
2. Review the error logs carefully
3. Test with a fresh installation
4. Ask for help from the team

Welcome to the team! 🎉