Usage Model Documentation

Overview

The Usage model tracks resource consumption across the CODITECT platform, providing detailed metering for billing, cost allocation, and resource optimization. It captures usage of AI tokens, compute resources, storage operations, and network bandwidth with granular pricing information. The model supports both real-time tracking and historical analysis.

Model Structure

Core Fields

Field	Type	Description	Constraints
`usage_id`	UUID	Unique usage record identifier	Primary key, auto-generated
`tenant_id`	UUID	Associated tenant	Foreign key to Tenant
`user_id`	UUID	User who consumed resource	Foreign key to User
`service_type`	ServiceType (Enum)	Category of service	Required
`resource_type`	ResourceType (Enum)	Specific resource consumed	Required
`quantity`	f64	Amount consumed	Required, positive value
`unit`	String	Unit of measurement	Required (e.g., "tokens", "requests")
`cost_per_unit`	f64	Unit price in dollars	Required
`total_cost`	f64	Calculated total cost	Auto-calculated (quantity × cost_per_unit)
`timestamp`	DateTime	When usage occurred	Auto-set to current time
`metadata`	JSON (Optional)	Additional context	Flexible structure

ServiceType Enum

enum ServiceType {
    Ai,       // AI model usage
    Compute,  // Cloud Run, containers
    Storage,  // GCS, FDB storage
    Network,  // Bandwidth usage
    Database  // FDB operations
}

ResourceType Enum

enum ResourceType {
    // AI Resources - Separated by input/output for accurate pricing
    ClaudeInputTokens,
    ClaudeOutputTokens,
    GeminiInputTokens,
    GeminiOutputTokens,
    OpenAiInputTokens,
    OpenAiOutputTokens,
    OllamaInputTokens,
    OllamaOutputTokens,
    HuggingFaceInputTokens,
    HuggingFaceOutputTokens,
    
    // Legacy token types (deprecated)
    ClaudeTokens,
    GeminiTokens,
    OpenAiTokens,
    OllamaTokens,
    
    // Compute Resources
    CloudRunRequests,
    CloudRunCpu,
    CloudRunMemory,
    
    // Storage Resources
    FdbWrites,
    FdbReads,
    GcsStorage
}

Usage Examples

AI Token Usage

{
  "usage_id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "123e4567-e89b-12d3-a456-426614174000",
  "user_id": "456e7890-e89b-12d3-a456-426614174000",
  "service_type": "Ai",
  "resource_type": "ClaudeInputTokens",
  "quantity": 1500.0,
  "unit": "tokens",
  "cost_per_unit": 0.000003,
  "total_cost": 0.0045,
  "timestamp": "2025-08-29T10:30:00Z",
  "metadata": {
    "model": "claude-3-opus",
    "agent_type": "coder",
    "task_id": "task-789",
    "project_id": "project-123",
    "prompt_type": "code_generation"
  }
}

Compute Usage

{
  "usage_id": "660e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "123e4567-e89b-12d3-a456-426614174000",
  "user_id": "456e7890-e89b-12d3-a456-426614174000",
  "service_type": "Compute",
  "resource_type": "CloudRunCpu",
  "quantity": 0.25,
  "unit": "vCPU-hours",
  "cost_per_unit": 0.024,
  "total_cost": 0.006,
  "timestamp": "2025-08-29T11:00:00Z",
  "metadata": {
    "service_name": "coditect-api",
    "region": "us-central1",
    "instance_class": "standard",
    "container_id": "container-abc123"
  }
}

Storage Operations

{
  "usage_id": "770e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "123e4567-e89b-12d3-a456-426614174000",
  "user_id": "456e7890-e89b-12d3-a456-426614174000",
  "service_type": "Database",
  "resource_type": "FdbWrites",
  "quantity": 10000.0,
  "unit": "operations",
  "cost_per_unit": 0.0000001,
  "total_cost": 0.001,
  "timestamp": "2025-08-29T11:30:00Z",
  "metadata": {
    "operation_type": "batch_insert",
    "entity_type": "tasks",
    "batch_size": 100,
    "latency_ms": 45
  }
}

Pricing Structure

AI Model Pricing (per 1K tokens)

Model	Input Tokens	Output Tokens	Notes
Claude 3 Opus	$0.015	$0.075	Premium model
Claude 3 Sonnet	$0.003	$0.015	Balanced model
Gemini Pro	$0.0005	$0.0015	Cost-effective
GPT-4	$0.03	$0.06	OpenAI flagship
Ollama	$0.00	$0.00	Self-hosted

Compute Pricing

Resource	Unit	Price	Notes
Cloud Run Requests	per million	$0.40	First 2M free
Cloud Run CPU	per vCPU-hour	$0.024	Billed per 100ms
Cloud Run Memory	per GB-hour	$0.0025	Billed per 100ms

Storage Pricing

Resource	Unit	Price	Notes
FDB Writes	per million ops	$0.10	Transactional
FDB Reads	per million ops	$0.01	Eventually consistent
GCS Storage	per GB-month	$0.02	Standard tier

Database Schema

Primary Storage Pattern

Key: /{tenant_id}/usage/{YYYY-MM-DD}/{user_id}/{timestamp}:{usage_id}
Value: JSON serialized Usage object

Secondary Indexes

# Usage by service type
/{tenant_id}/usage_by_service/{service_type}/{YYYY-MM-DD} -> [usage_ids]

# Usage by resource type
/{tenant_id}/usage_by_resource/{resource_type}/{YYYY-MM-DD} -> [usage_ids]

# User daily usage
/{tenant_id}/user_usage/{user_id}/{YYYY-MM-DD} -> [usage_ids]

# Cost aggregation
/{tenant_id}/usage_costs/{YYYY-MM-DD}/{user_id} -> total_cost

Aggregation Patterns

# Hourly aggregates
/{tenant_id}/usage_hourly/{YYYY-MM-DD-HH}/{service_type} -> aggregated_data

# Daily summaries
/{tenant_id}/usage_daily/{YYYY-MM-DD}/{user_id} -> daily_summary

# Monthly billing
/{tenant_id}/usage_monthly/{YYYY-MM}/{user_id} -> monthly_total

Source Files

Model: /src/models/usage.rs
Repository: /src/db/repositories/usage_repository.rs
Service: /src/services/usage_tracking_service.rs
Pricing: /src/services/pricing_service.rs
API Handler: /src/api/handlers/usage_handlers.rs
Tests: /src/models/tests/usage_tests.rs

Key Methods

impl Usage {
    fn new(
        tenant_id: Uuid,
        user_id: Uuid,
        service_type: ServiceType,
        resource_type: ResourceType,
        quantity: f64,
        unit: String,
        cost_per_unit: f64
    ) -> Self
    
    fn with_metadata(self, metadata: serde_json::Value) -> Self
}

impl UsageTrackingService {
    async fn track_usage(&self, usage: Usage) -> Result<()>
    async fn get_user_usage(&self, user_id: Uuid, start: DateTime<Utc>, end: DateTime<Utc>) -> Result<Vec<Usage>>
    async fn calculate_costs(&self, tenant_id: Uuid, period: Period) -> Result<CostSummary>
}

API Endpoints

Usage Tracking

POST /api/usage - Record usage (internal)
GET /api/usage?start={date}&end={date} - Get usage history
GET /api/usage/summary - Get usage summary
GET /api/usage/costs - Get cost breakdown

Reports

GET /api/reports/usage/daily - Daily usage report
GET /api/reports/usage/monthly - Monthly billing report
GET /api/reports/usage/by-service - Service breakdown
GET /api/reports/usage/trends - Usage trends analysis

Administrative

GET /api/admin/usage/tenant/{tenant_id} - Tenant usage
POST /api/admin/usage/recalculate - Recalculate costs
GET /api/admin/usage/alerts - Usage anomalies

Metadata Patterns

AI Usage Metadata

{
  "model": "claude-3-opus",
  "model_version": "20240229",
  "agent_type": "test_writer",
  "agent_id": "agent-123",
  "task_id": "task-456",
  "project_id": "project-789",
  "prompt_tokens": 500,
  "completion_tokens": 1000,
  "temperature": 0.7,
  "execution_time_ms": 2500
}

Compute Metadata

{
  "service_name": "coditect-api",
  "instance_id": "instance-abc123",
  "container_id": "container-def456",
  "region": "us-central1",
  "zone": "us-central1-a",
  "machine_type": "n1-standard-1",
  "scaling_type": "automatic",
  "request_count": 150
}

Storage Metadata

{
  "operation_type": "batch_write",
  "entity_type": "users",
  "transaction_id": "tx-123456",
  "consistency_level": "strong",
  "replication_factor": 3,
  "compression_ratio": 0.65,
  "encryption": "aes-256"
}

Aggregation Strategies

Real-time Tracking

Write usage records immediately
Update running totals in memory
Flush to persistent storage periodically
Alert on threshold breaches

Batch Aggregation

// Hourly aggregation job
async fn aggregate_hourly_usage(hour: DateTime<Utc>) {
    let usage_records = fetch_usage_for_hour(hour).await?;
    
    let aggregates = usage_records
        .group_by(|u| (u.service_type, u.resource_type))
        .map(|group| calculate_aggregate(group))
        .collect();
        
    store_hourly_aggregates(hour, aggregates).await?;
}

Cost Optimization

Identify high-usage patterns
Suggest more efficient resources
Alert on unusual spikes
Provide cost forecasts

Billing Integration

Monthly Billing Cycle

Day 1: Start new billing period
Daily: Track and aggregate usage
Day 25: Send usage forecast
Day 30: Finalize usage, generate invoice
Day 31: Process payment

Invoice Generation

struct Invoice {
    tenant_id: Uuid,
    billing_period: Period,
    line_items: Vec<LineItem>,
    subtotal: f64,
    tax: f64,
    total: f64,
    due_date: DateTime<Utc>
}

struct LineItem {
    service_type: ServiceType,
    resource_type: ResourceType,
    quantity: f64,
    unit_price: f64,
    total: f64
}

Monitoring & Alerts

Usage Alerts

Threshold exceeded (80%, 100% of quota)
Unusual spike detection (3x normal)
New resource type usage
Cost projection warnings

Metrics

Usage by service type
Cost trends over time
Per-user consumption
Resource efficiency scores
Waste identification

Compliance & Audit

Data Retention

Raw usage: 90 days
Daily aggregates: 1 year
Monthly summaries: 7 years
Audit logs: 7 years

Audit Trail

Who consumed what resource
When consumption occurred
Cost at time of usage
Any manual adjustments

Performance Optimization

Write Optimization

Batch usage writes
Async processing pipeline
Compress old records
Archive to cold storage

Query Optimization

Pre-aggregated views
Time-series indexing
Materialized summaries
Caching layer

Future Enhancements

Advanced Features

Predictive Analytics: ML-based usage forecasting
Cost Allocation: Tag-based cost distribution
Budget Alerts: Proactive budget management
Reserved Capacity: Commitment-based discounts

Integration Improvements

Cloud Provider APIs: Direct usage import
FinOps Tools: Cost management platforms
Accounting Systems: Automated invoice sync
Analytics Platforms: Usage data export

Optimization Features

Smart Scheduling: Run tasks during off-peak
Resource Recommendations: Right-sizing suggestions
Waste Detection: Identify unused resources
Cost Anomaly Detection: ML-based alerting

Last Updated: 2025-08-29 Version: 1.0

Overview​

Model Structure​

Core Fields​

ServiceType Enum​

ResourceType Enum​

Usage Examples​

AI Token Usage​

Compute Usage​

Storage Operations​

Pricing Structure​

AI Model Pricing (per 1K tokens)​

Compute Pricing​

Storage Pricing​

Database Schema​

Primary Storage Pattern​

Secondary Indexes​

Aggregation Patterns​

Related Code​

Source Files​

Key Methods​

API Endpoints​

Usage Tracking​

Reports​

Administrative​

Metadata Patterns​

AI Usage Metadata​

Compute Metadata​

Storage Metadata​

Aggregation Strategies​

Real-time Tracking​

Batch Aggregation​

Cost Optimization​

Billing Integration​

Monthly Billing Cycle​

Invoice Generation​

Monitoring & Alerts​

Usage Alerts​

Metrics​

Compliance & Audit​

Data Retention​

Audit Trail​

Performance Optimization​

Write Optimization​

Query Optimization​

Future Enhancements​

Advanced Features​

Integration Improvements​

Optimization Features​