Prolo — API Design & Data Structures (Deliverable 4)

Each endpoint's IN/OUT as Pydantic models — validation layer + the OpenAPI (/docs) contract.

class LineItem(BaseModel):
    sku: str | None = None
    description: str
    quantity: Decimal = Field(gt=0)
    unitOfMeasure: str
    price: Decimal = Field(ge=0)
class Totals(BaseModel): tax: Decimal; shipping: Decimal; net: Decimal
class SupplierQuote(BaseModel):                    # == SupplierQuoteObject
    model_config = ConfigDict(extra="forbid")      # unknown field → 422
    vendorIdentifier: str; totals: Totals
    lineItems: list[LineItem] = Field(min_length=1)
class QuoteStatus(str, Enum): EXTRACTED; NEEDS_REVIEW; MATCHED; SUBMITTED; SUPERSEDED; FAILED
class ProblemDetails(BaseModel):                   # RFC-9457 — OUT for every 4xx/5xx
    type: str; title: str; status: int; detail: str | None; errors: list[dict] | None

# IN  QuoteSearchParams (query):
#   tenantId, vendor?, quoteNumber?, status?,
#   isLatest?, page, pageSize(≤100), expand[]
# OUT 200 QuoteSearchResponse:
#   items: list[QuoteMetadata]; page; pageSize

# IN  path quoteId · query expand[]
# OUT 200 QuoteResource = QuoteMetadata
#     + quote: SupplierQuote + provenance[]

# IN  path quoteId
# OUT 200 list[QuoteResource]

# IN  SubmitQuoteRequest:
#   tenantId, messageId, quote: SupplierQuote
# OUT 201/200 QuoteWriteResponse:
#   quoteId, quoteGroupId, revision, status

# IN  path quoteGroupId + SubmitQuoteRequest
# OUT 201 RevisionWriteResponse:
#   …WriteResponse + supersedesId

# IN  QuoteStatusPatch: status
# OUT 200 QuoteWriteResponse

extra="forbid" + Decimal/Field constraints → 422 at the boundary; the Σ = net check runs after Pydantic (business rule).

FastAPI-on-Lambda (Mangum / Web Adapter), behind an internal ALB (target_type="lambda", no API Gateway), direct to Aurora PostgreSQL (no RDS Proxy). No public ingress — the AXO373 lambda_fastapi_service shape.

flowchart TB
    subgraph CLIENTS["Clients — VPC only"]
        PIPE["Prolo pipeline
Stage 6 submitter"]
        UI["Procurement UI (reads)"]
    end
    R53["Route 53 → ALB"]
    subgraph VPC["🔒 AWS VPC — private (no public ingress)"]
        direction TB
        subgraph EDGE["Ingress — ALB, not API Gateway"]
            WAF["WAFv2"]
            ALB["Internal ALB · HTTPS:443 · ACM
host-header → lambda target group"]
        end
        subgraph PRIV["Private subnets"]
            LAMBDA["λ Lambda — FastAPI
JWT verify (app)"]
            AUR[("Aurora PostgreSQL
asyncpg direct, no RDS Proxy")]
        end
        subgraph SUP["Platform"]
            SECR["Secrets Manager / SSM"]
            CW["CloudWatch"]
            MIG["Alembic — one-shot"]
        end
    end
    PIPE & UI --> R53 --> WAF --> ALB
    ALB -->|host-header rule| LAMBDA
    LAMBDA ==>|"reserved concurrency bounds pool"| AUR
    MIG -.->|migrate| AUR
    SECR -.-> LAMBDA
    LAMBDA -.-> CW
    classDef db fill:#fde047,stroke:#ca8a04,color:#000
    class AUR db
    style CLIENTS fill:#f2f0ff,stroke:#8250df,color:#1f2328
    style VPC fill:#eef4ff,stroke:#2f6fd6,color:#1f2328
    style EDGE fill:#e6fbf0,stroke:#1a7f37,color:#1f2328
    style PRIV fill:#e2ecff,stroke:#3b7ddd,color:#1f2328
    style SUP fill:#fff4e6,stroke:#e8992e,color:#1f2328
        

• No API Gateway — Lambda registered directly as an ALB target; reuses the internal ALB.
• Direct asyncpg, no RDS Proxy — connections bounded by reserved concurrency (execs × pool ≤ max_connections).
• Idempotency at the DB (UNIQUE(tenant,messageId)); revisions in one transaction. Migrations out of the request path.
• Two DBs — this Aurora is the core's system of record, not Prolo's pipeline RDS; POST is the P2 projection across the boundary.

Internal envelope — the pipeline wraps the thin SupplierQuoteObject with trust/audit metadata (not part of the transmitted contract):

{ "quote": { /* SupplierQuoteObject — the only part the core validates */ },
  "status":"EXTRACTED|…|SUBMITTED", "confidence":{…},   // drives Human Review
  "provenance":[{ "field":"net","page":1,"bbox":[…] }] }   // no RFQ data on the quote