# Ayvo — Clarity Before Treatment
## AI Agent Documentation

Ayvo is an asynchronous, doctor-verified medical second-opinion platform. Patients upload medical reports; Ayvo structures the case and routes it to a verified specialist who returns a structured second opinion within 48 hours. This is not telemedicine, an AI diagnostic, or a treatment provider. AI assists with document structuring; doctors make all clinical decisions.

## Public Pages

- **Home** — https://ayvo.life/ — Landing page with hero, how it works, decision moments, clarity layer explanation, sponsored programs, doctor recruitment
- **Submit a Case** — https://ayvo.life/submit — 7-step wizard: medical history, reports upload, specialist selection, contact info, pricing tier, promo code, review
- **Checkout** — https://ayvo.life/checkout — Stripe payment for case submission
- **Success** — https://ayvo.life/success — Post-payment confirmation, case submitted, OTP-gated report access
- **Case Status** — https://ayvo.life/status/[id] — OTP-verified case status and structured doctor opinion
- **Doctors Marketing** — https://ayvo.life/doctors — Doctor recruitment page
- **Doctor Application** — https://ayvo.life/doctors/apply — Specialist onboarding and verification
- **Doctor Dashboard** — https://ayvo.life/doctors/dashboard — Authenticated portal for verified specialists
- **Initiatives Listing** — https://ayvo.life/initiatives — Public health initiatives from verified doctors
- **Initiative Detail** — https://ayvo.life/initiatives/[slug] — Individual initiative with donation/attendance options
- **Host an Initiative** — https://ayvo.life/initiatives/host — Program organizer onboarding
- **Initiative Success** — https://ayvo.life/initiatives/success — Post-donation confirmation
- **Donors** — https://ayvo.life/donors — Sponsor access to public health programs
- **Founding Chair** — https://ayvo.life/founding-chair — Legacy-focused founding programme for families and builders preserving living history while funding healthcare
- **Founding Chair Nomination** — https://ayvo.life/founding-chair/nominate — Nominate a family or builder for the Founding Chair programme
- **Founding Chair Plan: Classic 196** — https://ayvo.life/founding-chair/plan/196 — Strategy and legacy details for the Classic 196 collection
- **Founding Chair Plan: Pioneer 360** — https://ayvo.life/founding-chair/plan/360 — Strategy and legacy details for the Pioneer 360 collection
- **Partnerships** — https://ayvo.life/partnerships — Organizational partnership opportunities
- **Global Reach** — https://ayvo.life/reach — Interactive 3D globe of global impact
- **Privacy Policy** — https://ayvo.life/privacy — HIPAA/GDPR compliance, data processing, rights
- **Terms of Service** — https://ayvo.life/terms — Medical disclaimer, consent, liability, governing law
- **Sub-processors** — https://ayvo.life/legal/sub-processors — GDPR transparency: third-party data processors
- **Platform Status** — https://ayvo.life/status — Real-time uptime metrics and SLA commitment
- **Demo** — development-only email template preview; not part of the production site

## Machine-readable discovery

- **robots.txt** — https://ayvo.life/robots.txt — crawl rules for public and private surfaces
- **sitemap.xml** — https://ayvo.life/sitemap.xml — canonical index of public pages
- **llms.txt** — this file — compact route and API map for agents

## API Endpoints (Public)

### POST /api/validate-promo
Validate a promo code for initiative-subsidized case pricing.
- Rate limited: 10 requests/minute/IP
- Input: `{ code: string, basePriceCents: number }`
- Output: `{ valid: boolean, initiativeId: string, discountPercentage: number, discountAmountCents: number, newPriceCents: number }` or error

### POST /api/upload
Secure file upload to Supabase Storage (patient reports, recordings, credentials).
- Rate limited: 10/min authenticated, 3/min anonymous
- Input: multipart/form-data with `file` and `bucket` (patient-reports | patient_recordings | doctor-credentials)
- Output: `{ success: true, filePath: string }` or error

### POST /api/create-payment-intent
Create Stripe PaymentIntent for case checkout.
- Rate limited: 5 requests/minute/IP
- Input: `{ caseId: string, email: string }`
- Output: `{ clientSecret: string, amountCents: number }` or error

### POST /api/create-funding-intent
Create Stripe PaymentIntent for initiative funding/donations.
- Rate limited: 5 requests/minute/IP
- Input: `{ initiativeId: string, amountCents: number, funderName?: string, funderEmail?: string, funderAddress?: string, funderOrganization?: string, isPublic?: boolean }`
- Output: `{ clientSecret: string, amountCents: number }` or error

### POST /api/cases/process-files
AI-assisted document processing (OCR, text extraction, structuring).
- Input: `{ filePaths: string[] }`
- Output: `{ extractedText: string, structuredData: object }` or error

### POST /api/cases/transcribe
Audio transcription for patient recordings.
- Input: `{ filePath: string }`
- Output: `{ transcript: string }` or error

### POST /api/cases/translate
Document translation.
- Input: `{ text: string, targetLanguage: string }`
- Output: `{ translatedText: string }` or error

### POST /api/cases/ai-recommendation
AI-assisted specialist matching (non-clinical, routing only).
- Input: `{ caseDescription: string, medicalHistory: string, specialistType: string }`
- Output: `{ recommendedSpecialty: string, confidence: number }` or error

### POST /api/initiatives/ai-polish
AI-assisted initiative copywriting (marketing text only).
- Input: `{ rawText: string }`
- Output: `{ polishedText: string }` or error

### POST /api/webhooks/stripe
Stripe webhook handler (payment completion, funding, payouts). Not for direct consumption.

### POST /api/verify-payment
Verify payment status for a case.
- Input: `{ sessionId: string }`
- Output: `{ paid: boolean, caseId: string }` or error

### GET /api/cron/cleanup
Scheduled cleanup of expired OTPs, stale cases. Internal use only.

## Data Model Highlights

- **Cases** (doctor_reviews): Patient medical reports, structured case description, specialist assignment, doctor opinion, clinical impression, next steps, payment status
- **Initiatives** (doctor_initiatives): Doctor-led public health programs with funding targets, location, date, target audience
- **Donations** (initiative_donations): Public contributions to initiatives with transparency
- **Doctor Profiles** (doctor_profiles): Verified specialists with specialty, availability, verification status
- **Promo Codes** (initiative_promo_codes): Subsidized pricing codes linked to initiatives

## Compliance & Security

- HIPAA-compliant PHI handling: TLS 1.3 in transit, AES-256 at rest, strict OTP-gated access, immutable audit logs
- GDPR-compliant: Right to erasure via "Delete Case" button, explicit consent for special category data, Standard Contractual Clauses for cross-border
- AI boundaries: Zero-data-retention OpenRouter config, AI never diagnoses/prescribes/writes clinical reports — only document structuring, transcription, translation, marketing polish
- Rate limiting on all public endpoints via Upstash Redis (with in-memory fallback)
- Security headers: HSTS preload, X-Frame-Options: DENY, CSP, Referrer-Policy

## Key Principles

1. **Clarity before action** — Every design decision prioritizes patient understanding over conversion
2. **AI assists, doctors decide** — No clinical decisions by AI; all opinions are human-verified
3. **Asynchronous by default** — No live appointments, no real-time pressure
4. **Privacy by design** — De-identification before routing, minimal data collection, user-controlled deletion
5. **Global access** — Structured second opinions across borders, languages, systems