kami_apple_exchage/README.md

# Apple Gift Card Exchange Platform

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Python](https://img.shields.io/badge/python-3.13+-blue.svg)
![Node.js](https://img.shields.io/badge/node-18+-green.svg)
![Docker](https://img.shields.io/badge/docker-ready-blue.svg)

A modern, scalable platform for Apple gift card exchange with real-time monitoring, distributed processing, and Apple-style user interface.

## 🌟 Features

### Frontend (Next.js)
- **Apple-style Design**: Beautiful, modern UI following Apple Human Interface Guidelines
- **Real-time Dashboard**: Live data updates with configurable refresh intervals
- **Order Management**: Complete order lifecycle management with status tracking
- **Task Monitoring**: Real-time task status and control interface
- **Link Management**: Dynamic link management system for different amounts
- **Dark/Light Theme**: Full theme support with smooth transitions
- **Responsive Design**: Works seamlessly across all device sizes
- **Accessibility**: WCAG compliant with ARIA support

### Backend (FastAPI)
- **Microservices Architecture**: Scalable distributed system design
- **Async Processing**: Full async/await support for high performance
- **Distributed Task Queue**: Celery with Redis for background processing
- **Browser Automation**: Playwright integration for Apple order processing
- **Real-time Monitoring**: OpenTelemetry observability stack
- **Database Management**: PostgreSQL with async SQLAlchemy ORM
- **Caching Layer**: Redis for distributed caching and state management
- **Health Checks**: Comprehensive health monitoring and graceful shutdown

## 🏗️ Architecture

### System Architecture
```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Backend API   │    │   Worker Pool   │
│   (Next.js)     │◄──►│   (FastAPI)     │◄──►│   (Celery)      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│     Browser     │    │   PostgreSQL    │    │   Playwright    │
│                 │    │   Database      │    │   Browsers      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌─────────────────┐
                       │      Redis      │
                       │   (Cache/Broker)│
                       └─────────────────┘
```

### Technology Stack

#### Frontend
- **Framework**: Next.js 15 with App Router
- **Language**: TypeScript
- **Styling**: Tailwind CSS + SASS
- **UI Components**: Radix UI + Custom Apple-style components
- **State Management**: TanStack Query + React Context
- **Animations**: Framer Motion
- **Package Manager**: Bun

#### Backend
- **Framework**: FastAPI
- **Language**: Python 3.13
- **Database**: PostgreSQL with asyncpg
- **ORM**: SQLAlchemy 2.0
- **Task Queue**: Celery with Redis
- **Browser Automation**: Playwright
- **Monitoring**: OpenTelemetry
- **Package Manager**: UV

## 🚀 Quick Start

### Prerequisites
- Python 3.13+
- Node.js 18+
- Docker & Docker Compose
- PostgreSQL
- Redis

### Environment Setup

1. **Clone the repository**
```bash
git clone https://github.com/your-org/apple-exchange.git
cd apple-exchange
```

2. **Backend Setup**
```bash
cd backend
uv sync
cp .env.example .env
# Configure your environment variables
```

3. **Frontend Setup**
```bash
cd frontend
bun install
cp .env.local.example .env.local
# Configure your environment variables
```

### Development Mode

1. **Start Dependencies**
```bash
cd backend
docker-compose up -d redis postgres
```

2. **Start Backend**
```bash
cd backend
uv run python app/main.py
```

3. **Start Frontend**
```bash
cd frontend
bun run dev
```

4. **Start Workers**
```bash
cd backend
uv run celery -A app.core.celery_app worker --loglevel=info
uv run celery -A app.core.celery_app beat --loglevel=info
```

### Docker Development

```bash
cd backend
docker-compose up -d
```

Access the application:
- Frontend: http://localhost:3000
- Backend API: http://localhost:8000
- API Documentation: http://localhost:8000/docs

## 📚 API Documentation

The backend provides comprehensive OpenAPI documentation:

- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc
- **OpenAPI JSON**: http://localhost:8000/openapi.json

### Key Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/v1/health` | GET | Health check |
| `/api/v1/orders` | GET/POST | Order management |
| `/api/v1/links` | GET/POST | Link management |
| `/api/v1/user-data` | GET/POST | User data management |
| `/api/v1/tasks` | GET | Task monitoring |

## 🔧 Configuration

### Backend Environment Variables
```env
# Database
DATABASE_URL=postgresql://user:password@localhost:5432/apple_exchange

# Redis
REDIS_URL=redis://localhost:6379/0

# Application
SERVICE_TYPE=api
LOG_LEVEL=INFO
ENVIRONMENT=development

# Security
SECRET_KEY=your-secret-key-here
```

### Frontend Environment Variables
```env
# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_ENV=development

# Monitoring
NEXT_PUBLIC_TELEMETRY_ENDPOINT=http://localhost:4318
```

## 🏗️ Deployment

### Production Deployment

1. **Build Frontend**
```bash
cd frontend
bun run build
```

2. **Build Backend**
```bash
cd backend
docker build -t apple-exchange-backend .
```

3. **Kubernetes Deployment**
```bash
cd deploy/helm
helm install apple-exchange ./apple-exchange
```

### Docker Compose Production
```bash
cd backend
docker-compose -f docker-compose.yml up -d
```

## 📊 Monitoring

### OpenTelemetry Integration
- **Distributed Tracing**: End-to-end request tracing
- **Metrics Collection**: Application and system metrics
- **Structured Logging**: JSON-formatted logs with context

### Health Checks
- **Liveness Probes**: Container health monitoring
- **Readiness Probes**: Service availability checks
- **Database Connectivity**: Real-time database health monitoring

### Monitoring Tools
- **Flower**: Celery task monitoring (http://localhost:5555)
- **Prometheus**: Metrics collection
- **Grafana**: Metrics visualization

## 🧪 Testing

### Backend Tests
```bash
cd backend
uv run pytest
uv run pytest --cov=app
uv run pytest -m "not slow"
```

### Frontend Tests
```bash
cd frontend
bun run test
bun run test:coverage
```

### Integration Tests
```bash
cd backend
uv run pytest -m integration
```

## 📝 Development Guidelines

### Code Quality

#### Backend
- **Formatting**: Black code formatter
- **Import Sorting**: isort
- **Type Checking**: MyPy
- **Linting**: Ruff
- **Testing**: pytest with coverage

#### Frontend
- **Formatting**: Prettier
- **Linting**: ESLint
- **Type Checking**: TypeScript
- **Testing**: Jest + React Testing Library

### Git Workflow
1. Create feature branch from `master`
2. Write code and tests
3. Run linting and formatting
4. Submit pull request
5. Code review and merge

### Commit Messages
Use conventional commits format:
```
feat: add new feature
fix: resolve issue
docs: update documentation
style: code formatting
refactor: code restructuring
test: add tests
chore: maintenance tasks
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Apple Human Interface Guidelines for design inspiration
- FastAPI team for the excellent framework
- Next.js team for the amazing React framework
- OpenTelemetry community for observability tools

## 📞 Support

For support and questions:
- Create an issue on GitHub
- Check the documentation
- Contact the development team

---

**Built with ❤️ using modern web technologies**