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

git clone https://github.com/your-org/apple-exchange.git
cd apple-exchange

2. Backend Setup

cd backend
uv sync
cp .env.example .env
# Configure your environment variables

3. Frontend Setup

cd frontend
bun install
cp .env.local.example .env.local
# Configure your environment variables

Development Mode

1. Start Dependencies

cd backend
docker-compose up -d redis postgres

2. Start Backend

cd backend
uv run python app/main.py

3. Start Frontend

cd frontend
bun run dev

4. Start Workers

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

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

# 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

# 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

cd frontend
bun run build

2. Build Backend

cd backend
docker build -t apple-exchange-backend .

3. Kubernetes Deployment

cd deploy/helm
helm install apple-exchange ./apple-exchange

Docker Compose Production

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

cd backend
uv run pytest
uv run pytest --cov=app
uv run pytest -m "not slow"

Frontend Tests

cd frontend
bun run test
bun run test:coverage

Integration Tests

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 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