Sankofa/docs/infrastructure/API_DOCUMENTATION.md

# Infrastructure API Documentation

## Overview

The Infrastructure Documentation Dashboard uses a combination of GraphQL queries/mutations and REST API endpoints for data management.

## GraphQL API

### Queries

#### Get Network Topologies
```graphql
query GetNetworkTopologies($filter: TopologyFilter) {
  networkTopologies(filter: $filter) {
    id
    region
    entity
    nodes {
      id
      type
      label
      position { x y }
    }
    edges {
      id
      source
      target
      type
    }
  }
}
```

#### Get Compliance Requirements
```graphql
query GetComplianceRequirements($filter: ComplianceFilter) {
  complianceRequirements(filter: $filter) {
    country
    region
    frameworks
    status
    requirements
    lastAuditDate
  }
}
```

#### Get Deployment Milestones
```graphql
query GetDeploymentMilestones($filter: MilestoneFilter) {
  deploymentMilestones(filter: $filter) {
    id
    title
    region
    entity
    priority
    startDate
    endDate
    status
    dependencies
    cost
    description
  }
}
```

#### Get Cost Estimates
```graphql
query GetCostEstimates($filter: CostFilter) {
  costEstimates(filter: $filter) {
    region
    entity
    category
    monthly
    annual
    breakdown {
      compute
      storage
      network
      licenses
      personnel
    }
    currency
    lastUpdated
  }
}
```

### Mutations

#### Update Network Topology
```graphql
mutation UpdateNetworkTopology($id: ID!, $input: TopologyInput!) {
  updateNetworkTopology(id: $id, input: $input) {
    id
    nodes { id }
    edges { id }
  }
}
```

#### Update Compliance Requirement
```graphql
mutation UpdateComplianceRequirement($country: String!, $input: ComplianceInput!) {
  updateComplianceRequirement(country: $country, input: $input) {
    country
    status
  }
}
```

#### Update Deployment Milestone
```graphql
mutation UpdateDeploymentMilestone($id: ID!, $input: MilestoneInput!) {
  updateDeploymentMilestone(id: $id, input: $input) {
    id
    title
    status
  }
}
```

#### Update Cost Estimate
```graphql
mutation UpdateCostEstimate($region: String!, $entity: String!, $category: String!, $input: CostInput!) {
  updateCostEstimate(region: $region, entity: $entity, category: $category, input: $input) {
    region
    entity
    monthly
    annual
  }
}
```

### Subscriptions

#### Subscribe to Topology Changes
```graphql
subscription SubscribeTopologyChanges($id: ID!) {
  topologyChanged(id: $id) {
    id
    nodes { id }
    edges { id }
  }
}
```

## REST API

### Data Serving

#### GET `/api/infrastructure/data/[filename]`
Serves JSON data files with caching.

**Response**: JSON data with cache headers

### Backup/Restore

#### POST `/api/infrastructure/backup`
Creates a backup of all data files.

**Response**:
```json
{
  "success": true,
  "filename": "backup-2024-01-01.json.gz",
  "timestamp": "2024-01-01T00:00:00Z",
  "files": 5
}
```

#### GET `/api/infrastructure/backup`
Lists all available backups.

**Response**:
```json
{
  "backups": [
    {
      "filename": "backup-2024-01-01.json.gz",
      "size": 1024,
      "created": "2024-01-01T00:00:00Z"
    }
  ]
}
```

#### POST `/api/infrastructure/restore`
Restores from a backup file.

**Request**:
```json
{
  "filename": "backup-2024-01-01.json.gz"
}
```

**Response**:
```json
{
  "success": true,
  "filesRestored": 5,
  "timestamp": "2024-01-01T00:00:00Z"
}
```

### Import

#### POST `/api/infrastructure/import`
Imports data from CSV/JSON/Excel file.

**Request**: FormData with `file` and `targetFile`

**Response**:
```json
{
  "success": true,
  "filename": "smom_countries.json",
  "records": 115
}
```

## Data Structures

### NetworkTopology
```typescript
{
  id: string
  region: string
  entity: string
  nodes: TopologyNode[]
  edges: TopologyEdge[]
  lastUpdated: string
}
```

### ComplianceRequirement
```typescript
{
  country: string
  region: string
  frameworks: string[]
  status: 'Compliant' | 'Partial' | 'Pending' | 'Non-Compliant'
  requirements: string[]
  lastAuditDate?: string
  notes?: string
}
```

### DeploymentMilestone
```typescript
{
  id: string
  title: string
  region: string
  entity: string
  priority: 'Critical' | 'High' | 'Medium' | 'Low'
  startDate: string
  endDate: string
  status: 'Planned' | 'In Progress' | 'Complete' | 'Blocked'
  dependencies: string[]
  cost?: number
  description?: string
}
```

### CostEstimate
```typescript
{
  region: string
  entity: string
  category: string
  monthly: number
  annual: number
  breakdown: {
    compute?: number
    storage?: number
    network?: number
    licenses?: number
    personnel?: number
  }
  currency: string
  lastUpdated: string
}
```

## Error Handling

All API endpoints return standard error responses:

```json
{
  "error": "Error message",
  "message": "Detailed error description"
}
```

Status codes:
- `200`: Success
- `400`: Bad Request
- `404`: Not Found
- `500`: Internal Server Error

## Authentication

Currently, the API does not require authentication. In production, implement:
- JWT tokens for GraphQL
- API keys for REST endpoints
- Role-based access control