Sankofa/docs/tenants/BILLING_GUIDE.md

# Billing Guide - Superior to Azure Cost Management

Comprehensive billing and cost management guide for Sankofa Phoenix.

## Overview

Sankofa Phoenix billing system provides features superior to Azure Cost Management:

- **Per-second granularity** (vs Azure's hourly)
- **Real-time cost tracking** (better than Azure)
- **ML-based forecasting** (predictive analytics)
- **Blockchain-backed billing** (immutable audit trail)
- **Multi-currency support**
- **Custom pricing models**

## Usage Tracking

### Per-Second Granularity

Unlike Azure's hourly billing, Sankofa tracks usage per-second:

```graphql
query {
  usage(
    tenantId: "tenant-id"
    timeRange: {
      start: "2024-01-01T00:00:00Z"
      end: "2024-01-01T23:59:59Z"
    }
    granularity: SECOND
  ) {
    totalCost
    currency
    byResource {
      resourceId
      resourceName
      cost
      quantity
    }
  }
}
```

### Granularity Options

- **SECOND**: Per-second tracking (most detailed)
- **MINUTE**: Per-minute aggregation
- **HOUR**: Per-hour aggregation (Azure equivalent)
- **DAY**: Daily aggregation

## Cost Breakdown

Get detailed cost breakdown with flexible grouping:

```graphql
query {
  costBreakdown(
    tenantId: "tenant-id"
    groupBy: ["resource", "service", "region"]
  ) {
    total
    byResource {
      resourceId
      resourceName
      cost
      percentage
    }
    byService {
      service
      cost
      percentage
    }
    byRegion {
      region
      cost
      percentage
    }
    allocations {
      key
      value
      cost
      percentage
    }
  }
}
```

## Cost Forecasting

ML-based cost forecasting (better than Azure):

```graphql
query {
  costForecast(
    tenantId: "tenant-id"
    timeframe: "30D"
    confidence: 0.8
  ) {
    currentCost
    predictedCost
    confidence
    trend
    recommendations
  }
}
```

## Cost Optimization

Get optimization recommendations:

```graphql
query {
  costOptimization(tenantId: "tenant-id") {
    id
    type
    title
    description
    potentialSavings
    impact
    effort
  }
}
```

## Budgets

Set and manage budgets (more granular than Azure):

```graphql
mutation {
  setBudget(
    tenantId: "tenant-id"
    budget: {
      name: "Monthly Budget"
      amount: 10000
      currency: "USD"
      period: MONTHLY
      startDate: "2024-01-01T00:00:00Z"
      alertThresholds: [0.5, 0.75, 0.9]
      filters: {
        resourceType: "VM"
        region: "us-west"
      }
    }
  ) {
    id
    name
    currentSpend
    remaining
  }
}
```

## Billing Alerts

Configure alerts (more flexible than Azure):

```graphql
mutation {
  createBillingAlert(
    tenantId: "tenant-id"
    alert: {
      name: "High Spending Alert"
      alertType: THRESHOLD
      threshold: 5000
      condition: {
        operator: "greater_than"
        value: 5000
      }
      notificationChannels: ["email", "slack"]
      enabled: true
    }
  ) {
    id
    name
    enabled
  }
}
```

## Invoices

View and manage invoices:

```graphql
query {
  invoices(
    tenantId: "tenant-id"
    filter: {
      status: PENDING
      startDate: "2024-01-01T00:00:00Z"
      endDate: "2024-01-31T23:59:59Z"
    }
  ) {
    id
    invoiceNumber
    total
    status
    dueDate
    lineItems {
      description
      quantity
      unitPrice
      total
    }
  }
}
```

## Reserved Capacity

Manage reserved instances (more flexible than Azure):

Reserved capacity is tracked in the database and automatically applied to usage calculations.

## Discounts

Custom discount rules per tenant:

Discounts can be configured with:
- Percentage-based
- Fixed amount
- Volume discounts
- Tier-based discounts

## Blockchain Integration

All billing records are optionally recorded on blockchain for:
- Immutable audit trail
- Multi-party verification
- Transparent cost breakdown
- Automated settlement

## Comparison to Azure Cost Management

| Feature | Azure | Sankofa Phoenix |
|---------|-------|-----------------|
| Billing Granularity | Hourly | Per-second |
| Real-time Tracking | Limited | Full real-time |
| Cost Forecasting | Basic | ML-based |
| Optimization | Manual | Automated recommendations |
| Blockchain | No | Yes (unique) |
| Multi-currency | Limited | Full support |
| Custom Pricing | Limited | Per-tenant models |

## Best Practices

1. **Set budgets early**: Configure budgets before deployment
2. **Use alerts**: Set up alerts for cost thresholds
3. **Review regularly**: Check cost breakdown weekly
4. **Optimize continuously**: Use optimization recommendations
5. **Monitor trends**: Use forecasting to plan capacity