mirror of
https://git.oceanpay.cc/danial/kami_apple_exchage.git
synced 2025-12-18 21:53:06 +00:00
feat: Add deployment scripts and configuration for Apple Gift Card Exchange Platform
- Create README.md for deployment instructions including environment requirements and setup steps. - Implement deploy.sh script for automated deployment of development and production environments. - Add combined Docker Compose configuration for frontend and backend services. - Include Redis configuration file for optimized memory management and persistence. - Update frontend Dockerfile to handle Next.js asset paths and static files. - Remove obsolete deployment files and configurations from frontend directory.
This commit is contained in:
danial
328
README.md
Normal file
328
README.md
Normal file
@@ -0,0 +1,328 @@
|
||||
# Apple Gift Card Exchange Platform
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
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**
|
||||
Reference in New Issue
Block a user