# 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**:
   ```bash
   git clone <repository-url>
   cd muhafidh/ziya
   ```

2. **Install dependencies**:
   ```bash
   pnpm install
   ```

3. **Set up Redis** (choose one):
   
   **Option A: Docker (Recommended)**
   ```bash
   # Run Redis in Docker container
   docker run -d --name bismillahdao-redis -p 6379:6379 redis:alpine
   ```
   
   **Option B: Local Installation**
   ```bash
   # 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**:
   ```bash
   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
```bash
# 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
```bash
# 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`
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](https://www.conventionalcommits.org/) with automated changelog generation and semantic versioning.

#### Branch Management
```bash
# 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:**
```bash
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:**
```bash
git commit -m "feat: redesign token card structure

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

#### Development Workflow
```bash
# 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)
```bash
# 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**
```bash
# 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)
```bash
# 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.

**Important Note for 0.x.x versions:**
- Before 1.0.0, breaking changes typically bump the **minor** version
- Example: `0.1.2` with `BREAKING CHANGE:` → `0.2.0` (not 1.0.0)
- Major version 1.0.0 is reserved for the first stable, production-ready release

#### 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](https://www.electronjs.org/docs)
- [Nuxt 3 Documentation](https://nuxt.com)
- [Vue 3 Documentation](https://vuejs.org)
- [Redis Documentation](https://redis.io/docs)

### 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! 🎉