mirror of
https://github.com/pezkuwichain/pwap.git
synced 2026-04-22 07:57:55 +00:00
docs: add comprehensive CLAUDE.md guide for AI assistants
Created detailed documentation for AI assistants working with this codebase: - Repository structure and tech stack overview - Development workflows for web, mobile, and SDK UI - Code organization patterns and conventions - Blockchain integration guide with Polkadot.js - i18n setup with 6-language support - State management with Context API - Security best practices and common issues - Deployment guidelines and useful commands - Critical operational rules for production environment This guide provides everything AI assistants need to effectively work with the PezkuwiChain monorepo while maintaining code quality and safety.
This commit is contained in:
Claude
@@ -0,0 +1,983 @@
|
||||
# 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**
|
||||
|
||||
### 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
# 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):**
|
||||
```typescript
|
||||
// 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:**
|
||||
```typescript
|
||||
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:**
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
```typescript
|
||||
// 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!**
|
||||
|
||||
```typescript
|
||||
// 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
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
```typescript
|
||||
// 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):**
|
||||
```typescript
|
||||
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:**
|
||||
```typescript
|
||||
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:**
|
||||
```css
|
||||
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
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
```typescript
|
||||
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`:
|
||||
|
||||
```typescript
|
||||
<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:**
|
||||
```typescript
|
||||
interface PolkadotContextType {
|
||||
api: ApiPromise | null;
|
||||
isApiReady: boolean;
|
||||
accounts: InjectedAccountWithMeta[];
|
||||
selectedAccount: InjectedAccountWithMeta | null;
|
||||
connectWallet: () => Promise<void>;
|
||||
disconnectWallet: () => void;
|
||||
error: string | null;
|
||||
}
|
||||
```
|
||||
|
||||
**WalletContext:**
|
||||
```typescript
|
||||
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:
|
||||
|
||||
```typescript
|
||||
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!**
|
||||
|
||||
```bash
|
||||
# .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:**
|
||||
```typescript
|
||||
// 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
|
||||
|
||||
```typescript
|
||||
// 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
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
```typescript
|
||||
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:**
|
||||
```bash
|
||||
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:**
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
Reference in New Issue
Block a user