Provider Storefront¶

Public, SEO-friendly marketplace where patients discover hospitals, doctors, treatments, and destinations. No authentication required. No pricing displayed — cost estimates happen inside the AI navigator conversation.

Architecture¶

graph LR
    subgraph "Public Web (curaway.ai)"
        A[Patient Browser]
    end

    subgraph "Backend (services.curaway.ai)"
        B[Public Router<br/>GET only, no auth]
        C[Cache Service<br/>Upstash Redis]
        D[PostgreSQL]
        E[Qdrant Search]
    end

    A -->|GET /api/v1/public/*| B
    B --> C
    C -->|MISS| D
    C -->|MISS| E
    C -->|HIT| A

    style B fill:#008B8B,color:#fff
    style C fill:#FF7F50,color:#fff

API Endpoints (9)¶

All under /api/v1/public/ — no authentication, rate limited to 60 req/min per IP.

No Pricing Rule¶

No response from the public API contains pricing data. Fields excluded: - cost, price, priceRange, cost_breakdown, cost_range_usd_cents - procedure_costs, procedure_costs_converted, cost_index

Procedures are returned as List[str] (names only, not objects with pricing).

Caching Strategy¶

graph TD
    A[Request] --> B{Redis Cache}
    B -->|HIT| C[Return cached + X-Cache: HIT]
    B -->|MISS| D[Query PostgreSQL]
    B -->|ERROR| E[Query PostgreSQL + X-Cache: MISS-ERROR]
    D --> F[Store in Redis]
    F --> G[Return + X-Cache: MISS]
    E --> G

• Non-fatal: Redis failure logs PUBLIC_010 but never blocks the request
• Cache keys: pub:{entity}:{md5(params)[:12]}
• Invalidation: QStash event on provider/doctor update → bust specific keys + Vercel ISR revalidation

Provider Completeness Scoring¶

13 weighted dimensions determine display tier:

Tiers:

Travel Defaults¶

Country and city-level travel information loaded from config/travel_defaults.yaml. Covers 8 countries (India, Turkey, Thailand, UAE, Spain, Mexico, South Korea, Costa Rica).

Provider-specific travel data takes precedence over defaults. The Travel tab always has content.

Missing Data UX Rules¶

1. Null fields are omitted from JSON (response_model_exclude_none=True)
2. No "N/A", dashes, empty sections, or placeholder text
3. Doctor photo null → initials avatar with specialty-colored gradient
4. Hero image null → brand gradient (teal → deep ocean)
5. Provider profile tabs conditional — hidden when insufficient data
6. Stats bar hides individual unknown metrics

Frontend Routes (10)¶

/treatments                                        → Treatment index
/treatments/:treatmentSlug                         → Treatment detail
/destinations                                      → Destination index
/destinations/:countrySlug                         → Country detail
/destinations/:countrySlug/hospitals               → Provider listing
/destinations/:countrySlug/hospitals/:providerSlug → Provider profile
/doctors                                           → Doctor listing
/doctors/:doctorSlug                               → Doctor profile
/search                                            → Search results
/how-it-works                                      → How it works

Error Codes¶

Feature Flags¶

SEO¶

• JSON-LD: MedicalOrganization (providers), Physician (doctors), MedicalProcedure (treatments), BreadcrumbList (all pages)
• Meta title + description on every page
• Open Graph tags on every page
• Canonical URLs, rel="next"/"prev" on paginated listings
• Sitemap at /sitemap.xml with priority weights
• robots.txt: allow storefront paths, disallow /api/