pwap/CLAUDE.md

CLAUDE.md - AI Assistant Guide for PezkuwiChain Web App Projects

Last Updated: 2025-11-17 Production Status: ~95% Complete Active Network: Beta Testnet (wss://rpc.pezkuwichain.io:9944)

---

🎯 Quick Start for AI Assistants

This is a production-grade blockchain monorepo for PezkuwiChain with live validators running on VPS. Exercise extreme caution when making changes that could affect blockchain operations.

Critical Rules (READ FIRST!)

⚠️ NEVER DO THESE WITHOUT EXPLICIT USER PERMISSION:

1. DO NOT restart or stop VPS validators (7 validators currently finalizing blocks)
2. DO NOT modify chain specs (/root/pezkuwi-sdk/chain-specs/beta/beta-testnet-raw.json)
3. DO NOT change blockchain base paths or validator configurations
4. DO NOT commit .env files or secrets to git
5. DO NOT deploy to production without testing locally first
6. DO NOT make assumptions about blockchain operations - ALWAYS ASK

User Preferences (MUST FOLLOW!)

1. Screenshot Location: When user says "ekrana bak" (look at screen), read /home/mamostehp/pwap/screenshot.png
2. Git Commits: NEVER add Claude signature/attribution to commit messages (no "🤖 Generated with Claude Code" or "Co-Authored-By: Claude")
3. Deploy Path: Web app deploys to root@37.60.230.9:/var/www/pezkuwichain/web/dist/ - Nginx config points here
4. Documentation: ALL docs go in /home/mamostehp/pwap/docs/ folder (subfolders: p2p/, commission/, reports/, testing/, presale/) - NEVER put .md files in project root except README.md and CLAUDE.md
5. Production Wallet: P2P Escrow wallet is 5DFwqK698vL4gXHEcanaewnAqhxJ2rjhAogpSTHw3iwGDwd3 - NEVER use dev/test addresses like Alice

VPS Infrastructure

• IP: 37.60.230.9
• Validators: 7 running (ports 30333-30339, RPC 9944-9950)
• Frontend: Nginx serving at /var/www/pezkuwichain/web/dist/
• Blockchain: LIVE on Beta Testnet - handle with care

---

📁 Repository Structure

pezkuwi-web-app-projects/
├── web/                    # Main React web app (Vite + TypeScript) - 90% complete
├── mobile/                 # React Native Expo app - 50% complete
├── pezkuwi-sdk-ui/        # Polkadot.js SDK UI (branded clone) - 47MB
├── shared/                 # Shared code library (types, utils, blockchain, i18n)
├── README.md              # Project overview
├── PRODUCTION_READINESS.md # Production status report
└── CLAUDE_README_KRITIK.md # CRITICAL operational guidelines (Turkish)

Directory Breakdown

Directory	Size	Status	Purpose
web/	3.8MB	90%	Main production web application
mobile/	737KB	50%	iOS/Android mobile app
pezkuwi-sdk-ui/	47MB	Active	Polkadot.js Apps clone
shared/	402KB	100%	Shared libraries & utilities

---

🛠️ Tech Stack

Web Application (/web/)

Category	Technology	Version	Purpose
Framework	React	18.3.1	UI framework
Language	TypeScript	5.5.3	Type safety
Build Tool	Vite	5.4.1	Fast bundler with HMR
Blockchain	Polkadot.js API	16.4.9	Blockchain integration
Backend	Supabase	2.49.4	Auth & Database
UI Library	shadcn/ui	Latest	Radix UI components
Styling	Tailwind CSS	3.4.11	Utility-first CSS
State	React Context	-	Global state management
Data Fetching	TanStack Query	5.56.2	Server state caching
Routing	React Router	6.26.2	Client-side routing
i18n	i18next	23.7.6	6-language support
Forms	React Hook Form	7.53.0	Form management
Validation	Zod	3.23.8	Schema validation
Charts	Recharts	2.12.7	Data visualization
Icons	Lucide React	0.462.0	Icon library
Notifications	Sonner	1.5.0	Toast notifications

Mobile Application (/mobile/)

Category	Technology	Version	Purpose
Framework	React Native	0.81.5	Mobile framework
Runtime	Expo	54.0.23	Development platform
Navigation	React Navigation	7.x	Native navigation
Blockchain	Polkadot.js API	16.5.2	Blockchain integration
Storage	AsyncStorage	2.2.0	Persistent storage
Security	Expo SecureStore	15.0.7	Encrypted storage
Biometrics	expo-local-authentication	17.0.7	Fingerprint/FaceID
i18n	i18next	25.6.2	Multi-language

Shared Library (/shared/)

• Language: TypeScript (100% typed)
• Runtime: Platform-agnostic (Node.js + Browser + React Native)
• Dependencies: Minimal (Polkadot.js only)

---

🔑 Key Files & Entry Points

Web Application

Entry Points:

• web/src/main.tsx - React root render
• web/src/App.tsx - Provider hierarchy & routing
• web/index.html - HTML template

Configuration:

• web/vite.config.ts - Vite bundler config with path aliases
• web/tailwind.config.ts - Tailwind with Kurdistan color theme
• web/tsconfig.json - TypeScript strict mode + path mappings
• web/postcss.config.js - PostCSS for Tailwind

State Management (6 Contexts):

• contexts/PolkadotContext.tsx - Blockchain API connection
• contexts/WalletContext.tsx - Wallet state & multi-token balances
• contexts/AuthContext.tsx - Supabase authentication
• contexts/AppContext.tsx - Global application state
• contexts/WebSocketContext.tsx - Real-time blockchain updates
• contexts/IdentityContext.tsx - User identity & KYC status

Backend:

• src/lib/supabase.ts - Supabase client initialization
• supabase/migrations/*.sql - Database schema migrations (9 files)

Mobile Application

Entry Points:

• mobile/index.ts - Expo registerRootComponent
• mobile/App.tsx - Root with i18n initialization
• mobile/src/navigation/AppNavigator.tsx - Navigation setup

Shared Library

Core Files:

• shared/blockchain/endpoints.ts - Network endpoint configurations
• shared/blockchain/polkadot.ts - Polkadot.js utilities
• shared/constants/index.ts - KNOWN_TOKENS, KURDISTAN_COLORS, LANGUAGES
• shared/i18n/index.ts - i18n configuration
• shared/types/blockchain.ts - Blockchain type definitions
• shared/lib/wallet.ts - Wallet utilities & formatters

Business Logic Libraries:

• shared/lib/citizenship-workflow.ts - KYC & citizenship workflow
• shared/lib/tiki.ts - 70+ government roles (Hemwelatî, Parlementer, etc.)
• shared/lib/perwerde.ts - Education platform logic
• shared/lib/p2p-fiat.ts - P2P fiat trading system (production-ready)
• shared/lib/staking.ts - Staking operations
• shared/lib/multisig.ts - Multisig treasury operations
• shared/lib/validator-pool.ts - Validator pool management

---

🚀 Development Workflows

Web Development

# Navigate to web directory
cd web

# Install dependencies
npm install

# Start development server (localhost:8081)
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Lint code
npm run lint

Environment Setup:

1. Copy .env.example to .env
2. Set VITE_NETWORK=local (or testnet/beta/mainnet)
3. Configure Supabase credentials:
   • VITE_SUPABASE_URL
   • VITE_SUPABASE_ANON_KEY
4. Set blockchain endpoint (optional, defaults to beta)

Mobile Development

# Navigate to mobile directory
cd mobile

# Install dependencies
npm install

# Start Expo development server
npm start

# Run on Android emulator
npm run android

# Run on iOS simulator
npm run ios

# Run in web browser
npm run web

Deploying to Production (Web)

# 1. Build locally
cd /home/mamostehp/pwap/web
npm run build

# 2. Deploy to VPS
rsync -avz dist/ pezkuwi-vps:/var/www/pezkuwichain/web/dist/

# 3. Reload Nginx (no restart needed)
ssh pezkuwi-vps "systemctl reload nginx"

Important: Always test locally with npm run build && npm run preview before deploying to VPS.

---

📂 Code Organization Patterns

Component Structure

Web Components:

web/src/components/
├── ui/                 # shadcn/ui primitives (50+ components)
│   ├── button.tsx
│   ├── card.tsx
│   ├── dialog.tsx
│   └── ...
├── auth/               # Authentication components
├── citizenship/        # Citizenship/KYC UI
├── dex/                # DEX/Swap interface
├── delegation/         # Delegation management
├── forum/              # Forum components
├── governance/         # Governance interface
├── p2p/                # P2P fiat trading
├── perwerde/           # Education platform
├── staking/            # Staking dashboard
└── wallet/             # Wallet components

Pattern: Feature-based organization with co-located types and utilities.

File Naming Conventions

• Components: PascalCase (StakingDashboard.tsx)
• Utilities: camelCase (wallet.ts, formatting.ts)
• Types: PascalCase interfaces/types (WalletAccount, TokenInfo)
• Constants: UPPER_SNAKE_CASE exports (ASSET_IDS, KURDISTAN_COLORS)

Import Patterns

Path Aliases (Web):

// Local imports
import { Component } from '@/components/ui/component';
import { useWallet } from '@/contexts/WalletContext';

// Shared library imports
import { formatBalance } from '@pezkuwi/lib/wallet';
import { WalletAccount } from '@pezkuwi/types';
import { KURDISTAN_COLORS } from '@pezkuwi/constants';
import { translations } from '@pezkuwi/i18n';

Import Order (Follow This!):

1. React imports
2. External libraries
3. Shared imports (@pezkuwi/*)
4. Local imports (@/)
5. Types
6. Styles/assets

Example:

import React, { useState, useEffect } from 'react';
import { useNavigate } from 'react-router-dom';
import { useQuery } from '@tanstack/react-query';
import { formatBalance } from '@pezkuwi/lib/wallet';
import { WalletAccount } from '@pezkuwi/types';
import { ASSET_IDS } from '@pezkuwi/constants';
import { useWallet } from '@/contexts/WalletContext';
import { Card } from '@/components/ui/card';
import type { PoolInfo } from '@/types/dex';
import '@/styles/dashboard.css';

TypeScript Conventions

Strict Mode Enabled:

{
  "strict": true,
  "noImplicitAny": true,
  "strictNullChecks": true,
  "noUnusedLocals": true,
  "noUnusedParameters": true
}

Type Patterns:

• Use interface for object shapes
• Use type for unions, intersections, and complex types
• Use enum for fixed sets of values
• Use as const for literal types
• Avoid any - use unknown and type guards instead

---

⛓️ Blockchain Integration

Network Endpoints

// shared/blockchain/endpoints.ts
const ENDPOINTS = {
  MAINNET: 'wss://mainnet.pezkuwichain.io',
  BETA: 'wss://rpc.pezkuwichain.io:9944',      // Currently active
  STAGING: 'wss://staging.pezkuwichain.io',
  TESTNET: 'wss://testnet.pezkuwichain.io',
  LOCAL: 'ws://127.0.0.1:9944'
};

// Default for development
DEFAULT_ENDPOINT = 'ws://127.0.0.1:9944';

Asset System

⚠️ CRITICAL: wUSDT uses 6 decimals, not 12!

// Native token (no Asset ID)
HEZ - Accessed via system.account.data.free

// Assets pallet (12 decimals except wUSDT)
ASSET_IDS = {
  WHEZ: 0,   // Wrapped HEZ - 12 decimals
  PEZ: 1,    // Utility token - 12 decimals
  WUSDT: 2,  // Wrapped USDT - 6 decimals ⚠️
}

// Display mapping (internal vs user-facing)
TOKEN_DISPLAY_SYMBOLS = {
  'wHEZ': 'HEZ',   // Show as HEZ to users
  'wUSDT': 'USDT', // Show as USDT to users
  'PEZ': 'PEZ'     // Keep as PEZ
}

Polkadot.js Connection Pattern

import { ApiPromise, WsProvider } from '@polkadot/api';

// Initialize API
const provider = new WsProvider(endpoint);
const api = await ApiPromise.create({ provider });
await api.isReady;

// Query native balance
const { data } = await api.query.system.account(address);
const balance = data.free.toString();

// Query asset balance
const assetData = await api.query.assets.account(ASSET_IDS.PEZ, address);
const amount = assetData.unwrap().balance.toString();

Transaction Pattern

// Simple transaction
const extrinsic = api.tx.balances.transfer(dest, amount);
const hash = await extrinsic.signAndSend(account, { signer });

// With event handling
const result = await new Promise((resolve, reject) => {
  let unsub;

  api.tx.module.method(params)
    .signAndSend(account, { signer }, ({ status, events, dispatchError }) => {
      if (dispatchError) {
        if (dispatchError.isModule) {
          const decoded = api.registry.findMetaError(dispatchError.asModule);
          reject(new Error(`${decoded.section}.${decoded.name}: ${decoded.docs}`));
        } else {
          reject(new Error(dispatchError.toString()));
        }
        if (unsub) unsub();
        return;
      }

      if (status.isInBlock) {
        // Extract data from events
        const event = events.find(e =>
          e.event.section === 'module' &&
          e.event.method === 'EventName'
        );
        resolve(event.data[0].toString());
        if (unsub) unsub();
      }
    })
    .then(unsubscribe => { unsub = unsubscribe; });
});

Custom Pallets

1. pallet-tiki - Governance roles (70+ roles: Hemwelatî, Parlementer, Serok, Wezir, etc.)
2. pallet-identity-kyc - Zero-knowledge citizenship & KYC
3. pallet-perwerde - Education platform (courses, enrollments, certificates)
4. pallet-validator-pool - Validator pool categories & staking
5. pallet-welati - P2P fiat trading with escrow

---

🎨 UI Patterns & Styling

shadcn/ui Components

Located in web/src/components/ui/ - 50+ components built on Radix UI primitives.

Component Variants (CVA Pattern):

import { cva } from 'class-variance-authority';

const buttonVariants = cva(
  'inline-flex items-center justify-center rounded-md font-medium',
  {
    variants: {
      variant: {
        default: 'bg-kurdish-green text-white',
        destructive: 'bg-kurdish-red text-white',
        outline: 'border border-input bg-background',
      },
      size: {
        default: 'h-10 px-4 py-2',
        sm: 'h-9 px-3',
        lg: 'h-11 px-8',
      }
    },
    defaultVariants: {
      variant: 'default',
      size: 'default',
    }
  }
);

Kurdistan Color System

Primary Colors:

KURDISTAN_COLORS = {
  kesk: '#00A94F',  // Green (Kesk) - Primary brand color
  sor: '#EE2A35',   // Red (Sor) - Danger/error
  zer: '#FFD700',   // Yellow/Gold (Zer) - Warning/accent
  spi: '#FFFFFF',   // White (Spî)
  res: '#000000',   // Black (Reş)
}

Tailwind Usage:

bg-kurdish-green
bg-kurdish-green-dark
bg-kurdish-green-light
text-kurdish-red
border-kurdish-yellow

---

🌍 Internationalization (i18n)

Supported Languages

Code	Language	Direction	Status
en	English	LTR	✅ Complete
tr	Türkçe (Turkish)	LTR	✅ Complete
kmr	Kurmancî (Kurdish Kurmanji)	LTR	✅ Complete
ckb	سۆرانی (Kurdish Sorani)	RTL	✅ Complete
ar	العربية (Arabic)	RTL	✅ Complete
fa	فارسی (Persian)	RTL	✅ Complete

Translation Files

• Web: web/src/i18n/locales/*.ts (TypeScript modules - local imports)
• Mobile: mobile/src/i18n/locales/*.ts
• Shared: shared/i18n/locales/*.json (JSON files)

⚠️ Important: Web uses .ts files with local imports, not shared JSON files. This was changed to fix loading issues.

RTL Support

import { isRTL } from '@pezkuwi/i18n';

// Detect RTL languages
const isRightToLeft = isRTL(currentLanguage); // true for ckb, ar, fa

// Apply direction
document.dir = isRightToLeft ? 'rtl' : 'ltr';

Usage Pattern

import { useTranslation } from 'react-i18next';

function Component() {
  const { t, i18n } = useTranslation();

  return (
    <div>
      <h1>{t('welcome.title')}</h1>
      <button onClick={() => i18n.changeLanguage('kmr')}>
        {t('language.kurdish')}
      </button>
    </div>
  );
}

---

🗄️ State Management

Provider Hierarchy

Order matters! This is the provider nesting in web/src/App.tsx:

<ThemeProvider>              // Dark/light mode
  <ErrorBoundary>            // Error handling
    <AuthProvider>           // Supabase authentication
      <AppProvider>          // Global app state
        <PolkadotProvider>   // Blockchain API connection
          <WalletProvider>   // Wallet state & balances
            <WebSocketProvider> // Real-time blockchain events
              <IdentityProvider> // User identity & KYC
                <Router />
              </IdentityProvider>
            </WebSocketProvider>
          </WalletProvider>
        </PolkadotProvider>
      </AppProvider>
    </AuthProvider>
  </ErrorBoundary>
</ThemeProvider>

Context APIs

PolkadotContext:

interface PolkadotContextType {
  api: ApiPromise | null;
  isApiReady: boolean;
  accounts: InjectedAccountWithMeta[];
  selectedAccount: InjectedAccountWithMeta | null;
  connectWallet: () => Promise<void>;
  disconnectWallet: () => void;
  error: string | null;
}

WalletContext:

interface WalletContextType {
  isConnected: boolean;
  account: string | null;
  accounts: InjectedAccountWithMeta[];
  balance: string;  // HEZ native balance
  balances: {
    HEZ: string;
    PEZ: string;
    wHEZ: string;
    USDT: string;
  };
  signer: Signer | null;
  connectWallet: () => Promise<void>;
  disconnect: () => void;
  switchAccount: (account: InjectedAccountWithMeta) => void;
  signTransaction: (tx: SubmittableExtrinsic) => Promise<string>;
  refreshBalances: () => Promise<void>;
}

TanStack Query (React Query)

Used for server state caching and automatic refetching:

import { useQuery } from '@tanstack/react-query';

const { data, isLoading, error } = useQuery({
  queryKey: ['proposals'],
  queryFn: () => fetchProposals(api),
  refetchInterval: 30000,  // Refresh every 30 seconds
  enabled: !!api,          // Only run when API is ready
});

---

🔐 Security Best Practices

Environment Variables

NEVER commit .env files!

# .env.example (commit this)
VITE_SUPABASE_URL=your_supabase_url
VITE_SUPABASE_ANON_KEY=your_anon_key
VITE_NETWORK=local

# .env (DO NOT commit)
VITE_SUPABASE_URL=https://actual-url.supabase.co
VITE_SUPABASE_ANON_KEY=actual_key_here
VITE_NETWORK=beta

Access in code:

// Web (Vite)
const supabaseUrl = import.meta.env.VITE_SUPABASE_URL;

// Mobile (Expo)
const supabaseUrl = process.env.EXPO_PUBLIC_SUPABASE_URL;

Sensitive Data Handling

• Wallet seeds: NEVER stored in app - Polkadot.js extension only
• Private keys: NEVER accessible to frontend code
• KYC data: AES-GCM encrypted → IPFS → Hash stored on-chain
• API keys: Environment variables only, never hardcoded

Error Handling

// ErrorBoundary for React errors
<ErrorBoundary>
  <App />
</ErrorBoundary>

// Try-catch for async operations
try {
  await api.tx.method(params).signAndSend(account, { signer });
  toast.success('Transaction successful!');
} catch (error) {
  console.error('Transaction failed:', error);
  toast.error(error.message || 'Transaction failed');
  // Don't expose sensitive error details to users
}

---

🧰 Utility Functions

Formatting

import { formatAddress, formatBalance, parseAmount } from '@pezkuwi/utils/formatting';

// Address formatting
formatAddress('5GrwVaEbzhSSC2biT...xQjz')
// → '5GrwV...xQjz'

// Balance formatting (with decimals)
formatBalance('1234567890000', 12)  // HEZ, PEZ, wHEZ
// → '1234.5679'

formatBalance('1234567', 6)  // wUSDT (6 decimals!)
// → '1.2346'

// Amount parsing (to BigInt)
parseAmount('100', 12)
// → 100000000000000n

Validation

import { isValidAddress, isValidAmount } from '@pezkuwi/utils/validation';

isValidAddress('5GrwVaEbzhSSC2biT...') // true
isValidAmount('100.5') // true
isValidAmount('abc') // false

---

🧪 Testing & Quality

Before Committing

1. Run linter: npm run lint
2. Check no .env committed: git status
3. Remove debug logs: Search for console.log
4. Update types: If API changed
5. Test i18n: Check all 6 languages
6. Test RTL: Check ckb, ar, fa layouts

Before Deploying

1. Test production build:

   npm run build
   npm run preview
   

2. Verify environment variables set correctly
3. Check Supabase migrations applied
4. Backup database (if schema changed)
5. Monitor blockchain validator status

---

📊 Database Schema (Supabase)

Core Tables

• profiles - User profiles (linked to auth.users)
• forum_categories - Forum categories
• forum_threads - Forum threads
• forum_posts - Forum posts with moderation
• courses - Perwerde education courses
• enrollments - Course enrollments
• p2p_offers - P2P fiat trading offers
• p2p_trades - Active trades with escrow
• p2p_reputation - User reputation scores
• payment_methods - Payment method registry

Hybrid Architecture

Blockchain = Source of Truth

User action → Blockchain transaction → Event emitted
     ↓
Event listener → Supabase sync (for indexing/caching)
     ↓
UI queries Supabase (fast) + Blockchain (verification)

Example Flow (Creating a Course):

1. User submits form
2. Frontend calls api.tx.perwerde.createCourse(...)
3. Transaction finalized on-chain
4. Event listener catches CourseCreated event
5. Sync to Supabase for UI display
6. UI reads from Supabase (fast) but trusts blockchain

---

🚨 Common Issues & Solutions

Issue: Polkadot.js API not connecting

Solution:

1. Check endpoint is reachable: curl -I http://37.60.230.9:9944
2. Verify WebSocket protocol (wss vs ws)
3. Check CORS settings on blockchain node
4. Ensure validators are running: ssh pezkuwi-vps "ps aux | grep pezkuwi"

Issue: Transaction fails with "BadOrigin"

Solution:

• User doesn't have required role (check pallet-tiki roles)
• Use dispatch_as if needed for elevated permissions

Issue: Balance shows as 0

Solution:

• Check correct Asset ID (wHEZ: 0, PEZ: 1, wUSDT: 2)
• Remember wUSDT uses 6 decimals, not 12
• Verify account has opted-in to asset (required for assets pallet)

Issue: i18n translations not loading

Solution:

• Web uses local .ts files (not shared JSON)
• Check import path: import en from './locales/en.ts'
• Not: import en from '@pezkuwi/i18n/locales/en.json'

Issue: Build fails with "Can't resolve @pezkuwi/..."

Solution:

• Check Vite path aliases in vite.config.ts
• Verify TypeScript path mappings in tsconfig.json
• Run npm install in shared directory if using symlinks

---

📝 Commit Guidelines

Commit Message Format

<type>: <subject>

<body (optional)>

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting)
• refactor: Code refactoring
• test: Adding tests
• chore: Build process, dependencies

Examples:

git commit -m "feat: add P2P fiat trading interface"
git commit -m "fix: wUSDT decimals now correctly use 6 instead of 12"
git commit -m "docs: update CLAUDE.md with blockchain integration patterns"

---

🎓 Learning Resources

Polkadot.js

• API Docs: https://polkadot.js.org/docs/
• Apps UI: https://github.com/polkadot-js/apps
• Extension: https://polkadot.js.org/extension/

UI/UX

• shadcn/ui: https://ui.shadcn.com/
• Radix UI: https://www.radix-ui.com/
• Tailwind CSS: https://tailwindcss.com/

Mobile

• Expo: https://docs.expo.dev/
• React Native: https://reactnative.dev/
• React Navigation: https://reactnavigation.org/

Backend

• Supabase: https://supabase.com/docs
• PostgreSQL: https://www.postgresql.org/docs/

---

🔧 Useful Commands

Blockchain Health Check

# Check validator logs
ssh pezkuwi-vps "tail -f /tmp/validator-1.log"

# Check finalization
ssh pezkuwi-vps "tail -30 /tmp/validator-1.log | grep -E 'peers|finalized' | tail -5"

# View all validators
ssh pezkuwi-vps "ps aux | grep pezkuwi"

Deployment

# Full web deployment
cd web && \
npm run build && \
rsync -avz dist/ pezkuwi-vps:/var/www/pezkuwichain/web/dist/ && \
ssh pezkuwi-vps "systemctl reload nginx"

Database

# Apply Supabase migrations
cd web/supabase
supabase db push

# Reset local database
supabase db reset

---

🎯 AI Assistant Guidelines

When Working on Features

1. Read critical docs first: CLAUDE_README_KRITIK.md
2. Check current branch: Verify you're on correct feature branch
3. Test blockchain connectivity: Before making blockchain changes
4. Use existing patterns: Follow component/context patterns
5. Maintain type safety: No any types
6. Test all languages: Check i18n keys exist
7. Test RTL layout: For ckb, ar, fa languages

When Making Blockchain Changes

1. Understand pallet first: Read Rust pallet code if needed
2. Test on local node: Before testnet
3. Handle errors properly: Extract dispatchError correctly
4. Update Supabase: If creating indexable data
5. Monitor events: Use WebSocketContext for real-time updates

When Deploying

1. Never deploy without testing
2. Check validator status first: Ensure blockchain is healthy
3. Deploy during low-traffic hours: If possible
4. Monitor logs after deploy: Watch for errors
5. Have rollback plan: Keep previous build

---

📞 Getting Help

Documentation Files

• README.md - Project overview
• CLAUDE_README_KRITIK.md - Critical operational guidelines (Turkish)
• PRODUCTION_READINESS.md - Production status report
• web/SECURITY.md - Security policies
• web/mimari.txt - Detailed system architecture (Turkish)

VPS Access

• IP: 37.60.230.9
• SSH: ssh pezkuwi-vps (alias assumed configured)
• Web Root: /var/www/pezkuwichain/web/dist/
• Nginx Config: /etc/nginx/sites-available/pezkuwichain.io

---

✅ Quick Reference Checklist

Starting a new feature:

• Create feature branch
• Read relevant shared libraries
• Check existing similar features
• Plan component structure
• Add i18n keys for all languages

Before committing:

• Run npm run lint
• Remove console.logs
• Check no .env changes
• Test in browser
• Write clear commit message

Before deploying:

• Test production build locally
• Verify environment variables
• Check blockchain connection
• Monitor validator status
• Plan rollback strategy

After deploying:

• Test live site
• Check browser console
• Monitor error logs
• Verify blockchain transactions work

---

Last Updated: 2025-11-17 Maintained By: PezkuwiChain Development Team Production Status: 95% Complete - Beta Testnet Active