aitbc/docs/advanced/03_architecture/5_marketplace-web.md

Marketplace Web - AITBC Documentation

Vite/TypeScript marketplace with offer/bid functionality, stats dashboard, and mock/live data toggle. Production UI ready.

● Live

Overview

The Marketplace Web is the primary interface for clients to submit AI compute jobs and for miners to offer their services. It provides a real-time trading platform with comprehensive job management and analytics.

Key Features

• Real-time job marketplace with offer/bid functionality
• Interactive statistics dashboard
• Mock/live data toggle for development
• Responsive design for all devices
• WebSocket integration for live updates
• Wallet integration for seamless payments

Technology Stack

• Framework: Vite 4.x
• Language: TypeScript 5.x
• UI: TailwindCSS + Headless UI
• State Management: Zustand
• Charts: Chart.js
• WebSocket: Native WebSocket API
• Icons: Lucide React

Getting Started

Prerequisites

• Node.js 18+
• npm or yarn

Installation

# Clone the repository
git clone https://github.com/oib/AITBC.git
cd aitbc/apps/marketplace-web

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

Environment Variables

Create .env.local:

VITE_API_URL=http://localhost:18000
VITE_WS_URL=ws://localhost:18000/ws
VITE_EXPLORER_URL=http://localhost:8009
VITE_NETWORK=mainnet

Architecture

Directory Structure

marketplace-web/
├── src/
│   ├── components/     # Reusable UI components
│   ├── pages/         # Page components
│   ├── hooks/         # Custom React hooks
│   ├── stores/        # Zustand stores
│   ├── types/         # TypeScript definitions
│   ├── utils/         # Utility functions
│   └── styles/        # Global styles
├── public/            # Static assets
└── dist/             # Build output

Core Components

JobCard

Display job information with real-time status updates.

interface JobCardProps {
  job: Job;
  onBid?: (jobId: string, amount: number) => void;
  showActions?: boolean;
}

StatsDashboard

Real-time statistics and charts.

interface StatsData {
  totalJobs: number;
  activeMiners: number;
  avgProcessingTime: number;
  totalVolume: number;
}

OfferPanel

Create and manage job offers.

interface OfferForm {
  model: string;
  prompt: string;
  parameters: JobParameters;
  maxPrice: number;
}

Features

1. Job Marketplace

Browse and submit AI compute jobs:

• Filter by model type and price
• Sort by deadline or reward
• Real-time status updates
• Bid on available jobs

2. Statistics Dashboard

Monitor network activity:

• Total jobs and volume
• Active miners count
• Average processing times
• Historical charts

3. Wallet Integration

Connect your AITBC wallet:

• Browser wallet support
• Balance display
• Transaction history
• One-click payments

4. Developer Mode

Toggle between mock and live data:

const isDevMode = import.meta.env.DEV;
const useMockData = localStorage.getItem('useMockData') === 'true';

API Integration

WebSocket Events

// Connect to WebSocket
const ws = new WebSocket(VITE_WS_URL);

// Listen for job updates
ws.on('job_update', (data: JobUpdate) => {
  updateJobStatus(data.jobId, data.status);
});

// Listen for new bids
ws.on('new_bid', (data: Bid) => {
  addBidToList(data);
});

REST API Calls

// Submit job
const submitJob = async (job: JobSubmission) => {
  const response = await fetch(`${VITE_API_URL}/v1/jobs`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': apiKey,
    },
    body: JSON.stringify(job),
  });
  return response.json();
};

// Get market stats
const getStats = async () => {
  const response = await fetch(`${VITE_API_URL}/v1/stats`);
  return response.json();
};

State Management

Using Zustand for state management:

// stores/marketplace.ts
interface MarketplaceStore {
  jobs: Job[];
  stats: StatsData;
  filters: FilterOptions;
  setJobs: (jobs: Job[]) => void;
  updateJob: (jobId: string, updates: Partial<Job>) => void;
  setFilters: (filters: FilterOptions) => void;
}

export const useMarketplaceStore = create<MarketplaceStore>((set) => ({
  jobs: [],
  stats: initialStats,
  filters: {},
  setJobs: (jobs) => set({ jobs }),
  updateJob: (jobId, updates) =>
    set((state) => ({
      jobs: state.jobs.map((job) =>
        job.id === jobId ? { ...job, ...updates } : job
      ),
    })),
  setFilters: (filters) => set({ filters }),
}));

Styling

TailwindCSS Configuration

// tailwind.config.js
module.exports = {
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {
      colors: {
        primary: '#2563eb',
        secondary: '#1e40af',
      },
    },
  },
  plugins: [],
};

CSS Variables

/* src/styles/globals.css */
:root {
  --color-primary: #2563eb;
  --color-secondary: #1e40af;
  --color-success: #10b981;
  --color-warning: #f59e0b;
  --color-danger: #ef4444;
}

Deployment

Docker Deployment

FROM node:18-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=0 /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/nginx.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Environment Configuration

Production

VITE_API_URL=https://aitbc.bubuit.net/api
VITE_WS_URL=wss://aitbc.bubuit.net/ws
VITE_NETWORK=mainnet

Staging

VITE_API_URL=https://staging.aitbc.bubuit.net/api
VITE_WS_URL=wss://staging.aitbc.bubuit.net/ws
VITE_NETWORK=testnet

Testing

Unit Tests

# Run tests
npm run test

# Run with coverage
npm run test:coverage

E2E Tests

# Install Playwright
npm run install:e2e

# Run E2E tests
npm run test:e2e

Performance Optimization

Code Splitting

// Lazy load components
const StatsDashboard = lazy(() => import('./components/StatsDashboard'));
const JobList = lazy(() => import('./components/JobList'));

// Use with Suspense
<Suspense fallback={<Loading />}>
  <StatsDashboard />
</Suspense>

Image Optimization

// Use next-gen formats
const optimizedImage = {
  src: '/api/og?title=Marketplace',
  width: 1200,
  height: 630,
  format: 'avif',
};

Troubleshooting

Common Issues

1. WebSocket Connection Failed

   • Check WS_URL in environment
   • Verify firewall settings
   • Check browser console for errors

2. Data Not Loading

   • Toggle mock/live data switch
   • Check API endpoint status
   • Verify API key configuration

3. Build Errors

   • Clear node_modules and reinstall
   • Check TypeScript version
   • Verify all imports

Debug Mode

Enable debug logging:

if (import.meta.env.DEV) {
  console.log('Debug info:', debugData);
}

Contributing

1. Fork the repository
2. Create feature branch
3. Make changes
4. Add tests
5. Submit PR

Code Style

• Use TypeScript strict mode
• Follow ESLint rules
• Use Prettier for formatting
• Write meaningful commit messages

Security

• Never commit API keys
• Use environment variables for secrets
• Implement rate limiting
• Validate all inputs
• Use HTTPS in production

Support

• Documentation: docs.aitbc.bubuit.net
• Discord: discord.gg/aitbc
• Issues: GitHub Issues