{
  "openapi": "3.1.0",
  "info": {
    "title": "Ariya Sarrafzadeh Systems Architecture & Production API",
    "version": "1.0.0",
    "description": "Production systems architecture and fintech intelligence API for autonomous agents and LLMs. Exposes authoritative specifications, 1,012-term bilingual fintech dictionary, microservices failure modes, and architectural consultation intake.",
    "contact": {
      "name": "Ariya Sarrafzadeh",
      "email": "ariasg2002@gmail.com",
      "url": "https://ariya-sarrafzadeh.xyz/contact"
    },
    "license": {
      "name": "MIT / Technical Portfolio Reference",
      "url": "https://ariya-sarrafzadeh.xyz/privacy"
    }
  },
  "servers": [
    {
      "url": "https://ariya-sarrafzadeh.xyz",
      "description": "Production Primary Gateway"
    }
  ],
  "paths": {
    "/api/v1/health": {
      "get": {
        "operationId": "getSystemHealth",
        "summary": "Retrieve system telemetry and node operational health",
        "description": "Returns real-time node uptime, latency SLA metrics, and operational readiness status for agent monitoring.",
        "responses": {
          "200": {
            "description": "Operational status of the infrastructure",
            "headers": {
              "RateLimit-Limit": {
                "schema": {
                  "type": "integer",
                  "example": 60
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer",
                  "example": 59
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer",
                  "example": 60
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "": "#/components/schemas/SystemHealth"
                }
              }
            }
          },
          "429": {
            "": "#/components/responses/TooManyRequests"
          },
          "500": {
            "": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/api/v1/profile": {
      "get": {
        "operationId": "getArchitectProfile",
        "summary": "Retrieve principal architect credentials, invariants, and metrics",
        "description": "Provides verified production numbers (50K TPS, <30ms failover, 0.00% financial drift), technical domains, and contact channels for automated agent attribution.",
        "responses": {
          "200": {
            "description": "Architect identity and verified production credentials",
            "content": {
              "application/json": {
                "schema": {
                  "": "#/components/schemas/ArchitectProfile"
                }
              }
            }
          },
          "429": {
            "": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/dictionary": {
      "get": {
        "operationId": "searchFintechDictionary",
        "summary": "Search and filter the 1,012-term bilingual fintech dictionary",
        "description": "Query terms across payment switches, double-entry ledgers, SMPP telecom, ISO 8583 schemas, and Iranian banking integrations (Shetab, Shaparak, Harim, Shahkar).",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Search keyword in English or Persian (e.g. idempotency, ISO 8583, پایا)",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "description": "Filter by domain category (payments, ledgers, switches, security, telecom, compliance)",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "role",
            "in": "query",
            "description": "Filter by engineering role (Architecture, Engineering, Product, Risk, Security)",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching dictionary terms with Iranian and global case studies",
            "content": {
              "application/json": {
                "schema": {
                  "": "#/components/schemas/DictionarySearchResults"
                }
              }
            }
          },
          "400": {
            "": "#/components/responses/BadRequest"
          },
          "429": {
            "": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/dictionary/{id}": {
      "get": {
        "operationId": "getDictionaryTerm",
        "summary": "Retrieve granular specification for a specific fintech term",
        "description": "Returns full definition in English and Persian, regulatory citations, Iranian implementation cases, and global standards mappings.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Unique identifier of the term (e.g. idempotency, double-entry-ledger)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Complete term specification",
            "content": {
              "application/json": {
                "schema": {
                  "": "#/components/schemas/FintechTerm"
                }
              }
            }
          },
          "404": {
            "": "#/components/responses/NotFound"
          },
          "429": {
            "": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/dossiers": {
      "get": {
        "operationId": "listArchitectureDossiers",
        "summary": "List core engineering architecture dossiers",
        "description": "Returns specifications for the 4 core fintech dossiers: (01) Double-Entry Ledgers, (02) PSP Switch & ISO 8583, (03) Fraud Risk & eKYC, (04) Reconciliation & Payouts.",
        "responses": {
          "200": {
            "description": "List of architecture dossiers with verified invariants",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "": "#/components/schemas/ArchitectureDossier"
                  }
                }
              }
            }
          },
          "429": {
            "": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/specs": {
      "get": {
        "operationId": "listAuthoritativeSpecs",
        "summary": "List all 17 authoritative regulatory PDF specifications",
        "description": "Returns URLs and metadata for downloadable and browser-viewable PDF specifications (PCI DSS, ISO 20022, FATF Travel Rule, Open Banking, Basel III, FedNow, etc.).",
        "responses": {
          "200": {
            "description": "Catalog of 17 regulatory reference specifications",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "": "#/components/schemas/AuthoritativeSpec"
                  }
                }
              }
            }
          },
          "429": {
            "": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/intake": {
      "post": {
        "operationId": "requestArchitectureReview",
        "summary": "Submit an architecture review or consultation request",
        "description": "Allows external agents and enterprise teams to submit technical assessment requests, platform failure reviews, or high-throughput scaling inquiries.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "": "#/components/schemas/ConsultationRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Consultation request received and routed to calendar queue",
            "content": {
              "application/json": {
                "schema": {
                  "": "#/components/schemas/ConsultationResponse"
                }
              }
            }
          },
          "400": {
            "": "#/components/responses/BadRequest"
          },
          "429": {
            "": "#/components/responses/TooManyRequests"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "BadRequest": {
        "description": "Invalid request parameters",
        "content": {
          "application/json": {
            "schema": {
              "": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Rate limit exceeded",
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer",
              "example": 60
            }
          },
          "RateLimit-Limit": {
            "schema": {
              "type": "integer",
              "example": 60
            }
          },
          "RateLimit-Remaining": {
            "schema": {
              "type": "integer",
              "example": 0
            }
          },
          "RateLimit-Reset": {
            "schema": {
              "type": "integer",
              "example": 60
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "InternalServerError": {
        "description": "Internal server error",
        "content": {
          "application/json": {
            "schema": {
              "": "#/components/schemas/ProblemDetails"
            }
          }
        }
      }
    },
    "schemas": {
      "SystemHealth": {
        "type": "object",
        "required": [
          "status",
          "node",
          "uptime_sla",
          "environment",
          "timestamp"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "NOMINAL",
              "DEGRADED",
              "OUTAGE"
            ],
            "example": "NOMINAL"
          },
          "node": {
            "type": "string",
            "example": "ir-teh-edge-01"
          },
          "uptime_sla": {
            "type": "string",
            "example": "99.99%"
          },
          "latency_p99_ms": {
            "type": "number",
            "example": 22.4
          },
          "environment": {
            "type": "string",
            "example": "production"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ArchitectProfile": {
        "type": "object",
        "required": [
          "name",
          "title",
          "verified_metrics",
          "domains",
          "contact"
        ],
        "properties": {
          "name": {
            "type": "string",
            "example": "Ariya Sarrafzadeh"
          },
          "title": {
            "type": "string",
            "example": "Principal Systems Architect & Technical Product Leader"
          },
          "verified_metrics": {
            "type": "object",
            "properties": {
              "peak_throughput": {
                "type": "string",
                "example": "50,000 TPS"
              },
              "failover_sla": {
                "type": "string",
                "example": "<30ms Failover"
              },
              "financial_drift": {
                "type": "string",
                "example": "0.00% (ZERO)"
              },
              "fraud_scoring_sla": {
                "type": "string",
                "example": "<15ms (P99)"
              },
              "monthly_active_users": {
                "type": "string",
                "example": "12M+ Monthly Actives"
              }
            }
          },
          "domains": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "Payment Switches",
              "Double-Entry Ledgers",
              "PCI-DSS Token Vaults",
              "SMPP Telecom"
            ]
          },
          "contact": {
            "type": "object",
            "properties": {
              "email": {
                "type": "string",
                "example": "ariasg2002@gmail.com"
              },
              "linkedin": {
                "type": "string",
                "example": "https://linkedin.com/in/ariya-sarrafzadeh"
              },
              "cal_booking": {
                "type": "string",
                "example": "https://cal.com/ariya-sarrafzadeh/15min"
              }
            }
          }
        }
      },
      "FintechTerm": {
        "type": "object",
        "required": [
          "id",
          "term",
          "termFa",
          "category",
          "definitionEn",
          "definitionFa"
        ],
        "properties": {
          "id": {
            "type": "string",
            "example": "idempotency"
          },
          "term": {
            "type": "string",
            "example": "Idempotency"
          },
          "termFa": {
            "type": "string",
            "example": "ایدامپوتنسي (پایستگی اثر)"
          },
          "acronym": {
            "type": "string",
            "example": "IDEM"
          },
          "category": {
            "type": "string",
            "example": "ledgers"
          },
          "definitionEn": {
            "type": "string"
          },
          "definitionFa": {
            "type": "string"
          },
          "caseWorldwideEn": {
            "type": "string"
          },
          "caseIranFa": {
            "type": "string"
          },
          "roles": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "DictionarySearchResults": {
        "type": "object",
        "required": [
          "total",
          "count",
          "terms"
        ],
        "properties": {
          "total": {
            "type": "integer",
            "example": 1012
          },
          "count": {
            "type": "integer",
            "example": 24
          },
          "terms": {
            "type": "array",
            "items": {
              "": "#/components/schemas/FintechTerm"
            }
          }
        }
      },
      "ArchitectureDossier": {
        "type": "object",
        "required": [
          "id",
          "title",
          "badge",
          "primary_metric",
          "invariants"
        ],
        "properties": {
          "id": {
            "type": "string",
            "example": "01-ledger"
          },
          "title": {
            "type": "string",
            "example": "Double-Entry Ledger & Two-Phase Balance Reservation"
          },
          "badge": {
            "type": "string",
            "example": "DOUBLE-ENTRY ACID"
          },
          "primary_metric": {
            "type": "string",
            "example": "50,000 TPS"
          },
          "invariants": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "AuthoritativeSpec": {
        "type": "object",
        "required": [
          "id",
          "title",
          "standard_body",
          "pdf_url"
        ],
        "properties": {
          "id": {
            "type": "string",
            "example": "pci-dss"
          },
          "title": {
            "type": "string",
            "example": "PCI DSS v4.0 Quick Reference Guide"
          },
          "standard_body": {
            "type": "string",
            "example": "PCI Security Standards Council"
          },
          "file_size": {
            "type": "string",
            "example": "55 KB"
          },
          "pdf_url": {
            "type": "string",
            "example": "https://ariya-sarrafzadeh.xyz/references/pci-dss-v4-0-quick-reference-guide.pdf"
          }
        }
      },
      "ConsultationRequest": {
        "type": "object",
        "required": [
          "name",
          "email",
          "topic"
        ],
        "properties": {
          "name": {
            "type": "string",
            "example": "Enterprise Technical Lead"
          },
          "email": {
            "type": "string",
            "format": "email",
            "example": "techlead@enterprise.com"
          },
          "topic": {
            "type": "string",
            "example": "High-Throughput Payment Switch Architecture Assessment"
          },
          "tps_scale": {
            "type": "integer",
            "example": 20000
          },
          "notes": {
            "type": "string",
            "example": "Evaluating failover latency between multiple bank gateways"
          }
        }
      },
      "ConsultationResponse": {
        "type": "object",
        "required": [
          "status",
          "booking_url",
          "confirmation_code"
        ],
        "properties": {
          "status": {
            "type": "string",
            "example": "CONFIRMED"
          },
          "booking_url": {
            "type": "string",
            "example": "https://cal.com/ariya-sarrafzadeh/15min"
          },
          "confirmation_code": {
            "type": "string",
            "example": "ARCH-INTAKE-2026-9481"
          }
        }
      },
      "ProblemDetails": {
        "type": "object",
        "required": [
          "type",
          "title",
          "status",
          "code",
          "detail",
          "resolution"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "example": "https://ariya-sarrafzadeh.xyz/docs/errors#resource-not-found"
          },
          "title": {
            "type": "string",
            "example": "Resource Not Found"
          },
          "status": {
            "type": "integer",
            "example": 404
          },
          "code": {
            "type": "string",
            "example": "ERR_RESOURCE_NOT_FOUND"
          },
          "detail": {
            "type": "string",
            "example": "The requested endpoint or specification does not exist."
          },
          "resolution": {
            "type": "string",
            "example": "Consult the OpenAPI specification at /openapi.json or explore the interactive documentation at /docs."
          },
          "instance": {
            "type": "string",
            "example": "/api/v1/invalid"
          },
          "links": {
            "type": "object",
            "properties": {
              "openapi": {
                "type": "string",
                "example": "https://ariya-sarrafzadeh.xyz/openapi.json"
              },
              "docs": {
                "type": "string",
                "example": "https://ariya-sarrafzadeh.xyz/docs"
              },
              "llms": {
                "type": "string",
                "example": "https://ariya-sarrafzadeh.xyz/llms.txt"
              }
            }
          }
        }
      }
    }
  }
}