Apply Composer changes: comprehensive API updates, migrations, middleware, and infrastructure improvements

- Add comprehensive database migrations (001-024) for schema evolution - Enhance API schema with expanded type definitions and resolvers - Add new middleware: audit logging, rate limiting, MFA enforcement, security, tenant auth - Implement new services: AI optimization, billing, blockchain, compliance, marketplace - Add adapter layer for cloud integrations (Cloudflare, Kubernetes, Proxmox, storage) - Update Crossplane provider with enhanced VM management capabilities - Add comprehensive test suite for API endpoints and services - Update frontend components with improved GraphQL subscriptions and real-time updates - Enhance security configurations and headers (CSP, CORS, etc.) - Update documentation and configuration files - Add new CI/CD workflows and validation scripts - Implement design system improvements and UI enhancements
2025-12-12 18:01:35 -08:00
parent e01131efaf
commit 9daf1fd378
968 changed files with 160890 additions and 1092 deletions
--- a/docs/api/API_CONTRACTS.md
+++ b/docs/api/API_CONTRACTS.md
@@ -0,0 +1,215 @@
+# Sankofa Phoenix API Contracts
+
+This document defines the GraphQL API contracts for the Sankofa Phoenix platform. This serves as the contract between frontend and backend teams during parallel development.
+
+**Last Updated**: 2024  
+**Version**: 1.0.0
+
+## GraphQL Endpoint
+
+- **Development**: `http://localhost:4000/graphql`
+- **Production**: `https://api.sankofa.nexus/graphql`
+
+## Authentication
+
+All queries and mutations (except `login`) require authentication via JWT token:
+
+```http
+Authorization: Bearer <token>
+```
+
+## Core Types
+
+### Resource
+
+```graphql
+type Resource {
+  id: ID!
+  name: String!
+  type: ResourceType!
+  status: ResourceStatus!
+  site: Site!
+  metadata: JSON
+  createdAt: DateTime!
+  updatedAt: DateTime!
+}
+```
+
+### Site
+
+```graphql
+type Site {
+  id: ID!
+  name: String!
+  region: String!
+  status: SiteStatus!
+  resources: [Resource!]!
+  createdAt: DateTime!
+  updatedAt: DateTime!
+}
+```
+
+### ResourceInventoryItem
+
+```graphql
+type ResourceInventoryItem {
+  id: ID!
+  resourceType: String!
+  provider: ResourceProvider!
+  providerId: String!
+  providerResourceId: String
+  name: String!
+  region: String
+  site: Site
+  metadata: JSON
+  tags: [String!]!
+  discoveredAt: DateTime!
+  lastSyncedAt: DateTime!
+  createdAt: DateTime!
+  updatedAt: DateTime!
+}
+```
+
+## Queries
+
+### Get Resources
+
+```graphql
+query GetResources($filter: ResourceFilter) {
+  resources(filter: $filter) {
+    id
+    name
+    type
+    status
+    site {
+      id
+      name
+      region
+    }
+    createdAt
+    updatedAt
+  }
+}
+```
+
+### Get Resource Inventory
+
+```graphql
+query GetResourceInventory($filter: ResourceInventoryFilter) {
+  resourceInventory(filter: $filter) {
+    id
+    name
+    resourceType
+    provider
+    region
+    tags
+    metadata
+    lastSyncedAt
+  }
+}
+```
+
+### Get Sites
+
+```graphql
+query GetSites {
+  sites {
+    id
+    name
+    region
+    status
+    resources {
+      id
+      name
+      type
+    }
+  }
+}
+```
+
+## Mutations
+
+### Login
+
+```graphql
+mutation Login($email: String!, $password: String!) {
+  login(email: $email, password: $password) {
+    token
+    user {
+      id
+      email
+      name
+      role
+    }
+  }
+}
+```
+
+### Create Resource
+
+```graphql
+mutation CreateResource($input: CreateResourceInput!) {
+  createResource(input: $input) {
+    id
+    name
+    type
+    status
+    site {
+      id
+      name
+    }
+  }
+}
+```
+
+## Subscriptions
+
+### Resource Updates
+
+```graphql
+subscription ResourceUpdated($id: ID!) {
+  resourceUpdated(id: $id) {
+    id
+    name
+    status
+    updatedAt
+  }
+}
+```
+
+## Error Codes
+
+- `UNAUTHENTICATED`: Authentication required
+- `FORBIDDEN`: Insufficient permissions
+- `NOT_FOUND`: Resource not found
+- `VALIDATION_ERROR`: Input validation failed
+- `SERVER_ERROR`: Internal server error
+
+## Rate Limiting
+
+- 100 requests per minute per IP
+- 1000 requests per hour per authenticated user
+
+## Mock Data
+
+For frontend development, use the following mock responses structure:
+
+```typescript
+// Mock Resource
+{
+  id: "uuid",
+  name: "example-resource",
+  type: "VM",
+  status: "RUNNING",
+  site: {
+    id: "uuid",
+    name: "US East Primary",
+    region: "us-east-1"
+  },
+  createdAt: "2024-01-01T00:00:00Z",
+  updatedAt: "2024-01-01T00:00:00Z"
+}
+```
+
+See [examples.md](./examples.md) for more detailed examples.
+