Magic Market

A microservices-based marketplace platform built with Rust, Python, and Kubernetes. Each service owns its data domain and communicates asynchronously via NATS with Protobuf serialization.

⚡ Quick Start

Get up and running in ~2 minutes:

git clone https://github.com/desmitry/magic-market.git
cd magic-market
cp .env.example .env
docker compose up -d
curl http://localhost:8080/health

Access the interactive API documentation at http://localhost:8080/docs

Development mode with seed data

docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d

Seed data includes sample users:

• alice@example.com (buyer role)
• bob@example.com (admin role)

✨ Features

• JWT Authentication - Access tokens (15 min) + refresh tokens (7 days) with Redis blacklist
• Permission-based RBAC - Fine-grained permissions flattened from roles at login time
• Rate Limiting - SlowAPI + Redis with per-endpoint limits (brute force & spam prevention)
• Microservices Architecture - Rust (account service) + Python (API gateway)
• Event-Driven Communication - NATS with Protobuf serialization and request-reply pattern
• Kubernetes-Ready - Kustomize manifests with security-hardened production overlay
• Comprehensive Testing - 185+ tests covering unit, integration, security, and performance

🏗️ Architecture

graph LR
    Client[Client] --> GW[API Gateway:8080]
    GW --> NATS[NATS:4222]
    NATS --> ACC[Account Service]
    GW --> REDIS[Redis:6379]
    ACC --> DB[(PostgreSQL:5432)]

Service	Language	Port	Description
API Gateway	Python/FastAPI	8080	HTTP API, JWT auth, RBAC, routing
Account Service	Rust/Tokio	NATS only	User management, credentials, roles, permissions
PostgreSQL	18	5432	Primary database with uuidv7()
NATS	JetStream	4222	Message bus for service communication
Redis	7	6379	JWT token blacklist, rate limiting

📋 Prerequisites

• Docker & Docker Compose - For running the full stack locally
• Rust 1.90+ - For Account Service development
• Python 3.14.2 - For API Gateway development (use uv for package management)
• kubectl - For Kubernetes deployment
• Kustomize - For K8s manifest customization (optional, kubectl -k works)

🚀 Getting Started

Option 1: Docker Compose (Recommended)

# Clone and setup
git clone https://github.com/desmitry/magic-market.git
cd magic-market
cp .env.example .env

# Start all services
docker compose up -d

# Verify health
curl http://localhost:8080/health

# View logs
docker compose logs -f

Option 2: Local Development (without Docker for services)

# Start infrastructure only
docker compose up postgres redis nats -d

# Run Account Service (Rust)
cd services/account
export DATABASE_URL="postgresql://magic_market:changeme@localhost:5432/magic_market"
export NATS_URL="nats://localhost:4222"
cargo run

# Run API Gateway (Python)
cd services/api_gateway
export NATS_URL="nats://localhost:4222"
export REDIS_URL="redis://localhost:6379"
export JWT_SECRET_KEY="dev-secret-key"
uv run uvicorn src.__main__:app --reload --port 8080

⚙️ Configuration

Copy .env.example to .env and customize:

Variable	Default	Required	Description
DATABASE_URL	postgresql://magic_market:changeme@postgres:5432/magic_market	Yes	PostgreSQL connection string
NATS_URL	nats://nats:4222	Yes	NATS server URL
REDIS_URL	redis://redis:6379	Yes	Redis URL for JWT blacklist
JWT_SECRET_KEY	-	Yes	256-bit secret for JWT signing
JWT_ALGORITHM	HS256	No	JWT signing algorithm
JWT_ACCESS_TOKEN_EXPIRE_MINUTES	15	No	Access token lifetime
JWT_REFRESH_TOKEN_EXPIRE_DAYS	7	No	Refresh token lifetime
RUST_LOG	info	No	Rust logging level

🔌 API Reference

Interactive API documentation is available at http://localhost:8080/docs when running.

Authentication Endpoints

Endpoint	Method	Auth	Rate Limit	Description
/auth/register	POST	No	10/hour	Register new user
/auth/login	POST	No	10/minute	Get access + refresh tokens
/auth/refresh	POST	No	30/minute	Refresh access token
/auth/logout	POST	Yes	30/minute	Invalidate tokens

User Endpoints

Endpoint	Method	Auth	Rate Limit	Description
/users/me	GET	Yes	60/minute	Get current user profile
/users/me/email	PUT	Yes	60/minute	Update email
/users/me/password	PUT	Yes	60/minute	Update password

Admin Endpoints

Endpoint	Method	Auth	Rate Limit	Description
/admin/users/{id}	GET	Admin	30/minute	Get user by ID
/admin/dashboard	GET	Admin	30/minute	Admin dashboard

Service Communication

Services communicate via NATS using subject convention: {service}.{entity}.{action}

Examples:

• account.users.create
• account.users.verify
• account.users.permissions.get

🧪 Development

Running Tests

API Gateway (Python):

cd services/api_gateway

# Unit tests (~0.03s)
uv run pytest tests/unit/ -v

# Integration tests (~6s)
uv run pytest tests/integration/ -v

# Security tests
uv run pytest tests/security/ -v

# Performance tests
uv run pytest tests/performance/ -v
uv run pytest tests/performance/ -v -m "not slow"  # Skip slow tests

# All tests with coverage
uv run pytest --cov=src --cov-report=html

Account Service (Rust):

cd services/account
export DATABASE_URL="postgresql://magic_market:changeme@localhost:5432/magic_market_test"
export SQLX_MIGRATIONS="$PWD/../../db/migrations"

# Run tests (uses #[sqlx::test] for DB isolation)
cargo test

Code Quality

# Python (API Gateway)
cd services/api_gateway
uv run ruff check .
uv run ruff format .

# Rust (Account Service)
cd services/account
cargo fmt
cargo clippy

Pre-commit Hooks

Install pre-commit hooks to run checks locally before pushing:

# Install pre-commit
uv tool install pre-commit

# Install hooks for this repository
pre-commit install

Hooks run automatically before each commit:

• Python: ruff check, ruff format
• Rust: cargo fmt, cargo clippy

🚢 Deployment

Kubernetes Deployment

Prerequisites:

• Kubernetes cluster (1.28+)
• kubectl configured
• Kustomize (optional)

Create Secrets (before first deployment):

kubectl create secret generic postgres-secret \
  --from-literal=url='postgresql://user:pass@postgres-host:5432/magic_market'

kubectl create secret generic api-gateway-secret \
  --from-literal=jwt-secret='your-256-bit-secret-key-here'

Deploy:

# Preview generated manifests
kustomize build k8s/overlays/production

# Deploy to cluster
kubectl apply -k k8s/overlays/production

# Verify deployment
kubectl get pods -l app.kubernetes.io/name=magic-market

Security Features (Production Overlay)

The production overlay automatically applies:

• Non-root containers (UID 1000)
• Read-only root filesystem
• All capabilities dropped
• seccomp profile (RuntimeDefault)
• No privilege escalation

Kustomize Structure

k8s/
├── base/                    # Base manifests
│   ├── kustomization.yaml
│   ├── migrator-job.yaml
│   ├── account-deployment.yaml
│   └── api-gateway-deployment.yaml
├── components/
│   └── security/            # Security patches
└── overlays/
    └── production/          # Production overlay
        ├── kustomization.yaml
        └── patches/
            └── resources.yaml

🔄 CI/CD

Automated Checks

Check	Runs When	Duration
Unit tests (Account + API Gateway)	Every push to PR	~4 min
Integration tests	Pushes to main OR PRs with run-integration label	~11 min
Docker image build	Push to main	~5 min

Running Integration Tests

Integration tests run automatically on pushes to main. For pull requests, add the run-integration label:

1. Push your changes (unit tests run automatically, ~4 min)
2. Add the label: Go to your PR → Labels (right sidebar) → Select run-integration
3. Wait for completion (~11 min)
4. Merge once all checks pass

To re-run integration tests: Remove and re-add the run-integration label.

Skipping CI

Add [skip ci] or [ci skip] to your commit message to skip CI for that push:

git commit -m "WIP: refactoring auth routes [skip ci]"
git push

🤝 Contributing

We follow trunk-based development:

Workflow

1. Create a feature branch from main:

   git checkout -b feature/your-feature-name
   

2. Develop and test locally:

   • Write tests for new functionality
   • Run pre-commit hooks (or they'll be caught by CI)
   • Keep branches small and focused

3. Push and open a PR:

   git push -u origin feature/your-feature-name
   

4. CI runs automatically:

   • Unit tests run on every push to the PR
   • Add run-integration label for integration tests

5. Rebase merge into main:

   • Keep history linear
   • Resolve conflicts by rebasing on latest main

Guidelines

• Commit messages: Use conventional commits format
• Branch naming: feature/, fix/, docs/, refactor/ prefixes
• PR size: Keep PRs small and focused (< 400 lines ideal)
• Tests: Required for all new functionality
• Documentation: Update README.md for user-facing changes

Local Setup for Contributors

# Clone and setup
git clone https://github.com/desmitry/magic-market.git
cd magic-market
cp .env.example .env

# Install pre-commit hooks
uv tool install pre-commit
pre-commit install

# Start infrastructure
docker compose up postgres redis nats -d

📊 Project Status

Component	Status	Notes
API Gateway	✅ Implemented	JWT auth, RBAC, routing, rate limiting
Account Service	✅ Implemented	User management, credentials, roles, permissions
Frontend	✅ Implemented	React + Vite + TypeScript, theme toggle
Order Service	📋 Planned	Order management
Payment Service	📋 Planned	Payment processing
Search Service	📋 Planned	Product search
Logger Service	📋 Planned	Centralized logging

📁 Directory Structure

magic-market/
├── db/
│   ├── migrations/          # SQL migrations (sqlx format)
│   ├── mock-db/             # Seed data for development
│   └── Dockerfile           # Migrator container image
├── k8s/
│   ├── base/                # Base Kubernetes manifests
│   ├── components/          # Reusable Kustomize components
│   └── overlays/            # Environment-specific overlays
├── proto/                   # Protobuf definitions
├── rust_common/             # Shared Rust utilities
├── scripts/                 # Build scripts
├── services/
│   ├── account/             # Rust: Account microservice
│   ├── api_gateway/         # Python: FastAPI Gateway
│   └── frontend/            # React + Vite + TypeScript
├── .github/workflows/       # CI/CD pipelines
├── docker-compose.yml       # Production-like setup
├── docker-compose.dev.yml   # Development with seed data
└── .env.example             # Environment variable template

📄 License

MIT