go-faker/README.md

# Go-Faker

High-performance Ethiopian fake data generator for load testing and development.

## Features

- **Seeded randomness** - Reproducible datasets across runs
- **Batch generation** - Generate thousands of records in a single call
- **Rich Ethiopian data** - Names, cities, regions, phone numbers (+251), and more
- **Two modes** - Use as a Go library or HTTP API server
- **Fast** - ~150k records/second throughput

## Quick Start

### CLI

```bash
# Generate 10 person records
./gofaker -count 10 -type person

# Generate 100 product records with specific fields
./gofaker -count 100 -type product -fields name,price,sku

# Use a seed for reproducible data
./gofaker -count 50 -type person -seed my-test-seed
```

### API Server

```bash
# Start server
./gofaker -server -addr :8080

# Generate via HTTP
curl -X POST http://localhost:8080/generate \
  -H "Content-Type: application/json" \
  -d '{"seed":"test","count":10,"type":"person","fields":["first_name","phone","email"]}'
```

### Library

```go
import "go-faker"

f := faker.New("my-seed")

// Generate single record
person := f.GeneratePerson([]string{"first_name", "phone", "email"})

// Generate batch
persons := f.GenerateBatch(1000, "person", []string{"first_name", "email", "city"})
```

## Data Types

### person

| Field | Description |
|-------|-------------|
| first_name | Ethiopian first name |
| last_name | Ethiopian last name |
| full_name | First + last name |
| phone | Ethiopian mobile (+2519x...) |
| email | Generated email address |
| gender | Male/Female |
| age | 18-90 |
| language | Ethiopian language |
| city | Ethiopian city |
| region | Ethiopian region |
| nationality | Ethiopian/nearby |
| occupation | Job title |
| company | Ethiopian company |
| blood_type | Blood type |
| date_of_birth | YYYY-MM-DD |
| username | Generated username |
| password | Secure random password |

### address

| Field | Description |
|-------|-------------|
| street | Street name |
| city | City |
| region | Region |
| sub_city | Sub-city (Addis Ababa) |
| postal_code | 4-digit code |
| zone | Zone number |
| woreda | Woreda |
| kebele | Kebele number |
| house_number | House identifier |
| latitude | GPS coordinate |
| longitude | GPS coordinate |

### product

| Field | Description |
|-------|-------------|
| name | Product name |
| category | Product category |
| price | Price in ETB |
| sku | Stock keeping unit |
| brand | Brand name |
| description | Product description |
| weight | Weight in kg |
| stock | Stock quantity |
| expiry_date | Future date |
| manufactured_date | Past date |

### analytics

| Field | Description |
|-------|-------------|
| user_id | user-XXXXX |
| event | Event type |
| timestamp | RFC3339 timestamp |
| amount | Transaction amount |
| currency | ETB |
| session_id | Session identifier |
| page_url | Page URL |
| ip_address | IP address (10.x.x.x) |
| device_type | Device type |
| browser | Browser name |
| os | Operating system |
| country | Country |
| referrer | Referrer URL |

## API Reference

### POST /generate

Generate fake data.

**Request:**
```json
{
  "seed": "optional-seed-string",
  "count": 100,
  "type": "person",
  "fields": ["first_name", "email", "phone"]
}
```

**Response:**
```json
{
  "data": [
    {"first_name": "Tadesse", "email": "Tadesse@email.com", "phone": "+251911234567"}
  ],
  "meta": {
    "count": 100,
    "seed": "optional-seed-string",
    "generated_at": "2026-05-02T10:00:00Z"
  },
  "format": "json"
}
```

### GET /fields

List all valid fields per data type.

### GET /health

Health check endpoint.

## Performance

| Records | Time | Rate |
|---------|------|------|
| 10,000 | 0.4s | ~25k/s |
| 100,000 | 0.7s | ~143k/s |

## License

MIT