Infrastructure¶

Curaway runs on a lean, pay-as-you-grow infrastructure stack optimized for a pre-revenue medical travel platform. Every service is either free-tier or minimal-cost, with clear upgrade paths when traffic demands it.

Architecture Overview¶

graph TB
    subgraph "Client Layer"
        FE[Next.js Frontend<br/>Vercel]
    end

    subgraph "Compute"
        BE[FastAPI Backend<br/>Railway Pro]
    end

    subgraph "Data Stores"
        PG[(PostgreSQL<br/>Railway Internal)]
        N4J[(Neo4j Aura<br/>Free Tier)]
        QD[(Qdrant Cloud<br/>Free Tier)]
        RD[(Upstash Redis<br/>Free Tier)]
    end

    subgraph "Object Storage"
        R2[Cloudflare R2<br/>10GB Free]
    end

    subgraph "Async / Cron"
        QS[Upstash QStash<br/>Free Tier]
    end

    subgraph "External Services"
        CL[Clerk Auth]
        RS[Resend Email]
        LF[Langfuse]
        PH[PostHog]
        FS[Flagsmith]
    end

    FE -->|HTTPS| BE
    BE --> PG
    BE --> N4J
    BE --> QD
    BE --> RD
    BE --> R2
    QS -->|Webhooks| BE
    BE --> CL
    BE --> RS
    BE --> LF
    BE --> PH
    BE --> FS

Compute: Railway Pro¶

Deployment Pipeline¶

sequenceDiagram
    participant Dev as Developer
    participant GH as GitHub
    participant RW as Railway
    participant HC as Health Check

    Dev->>GH: Push to main
    GH->>RW: Webhook trigger
    RW->>RW: Build Docker image
    RW->>RW: Start new container
    RW->>HC: GET /ready
    HC-->>RW: 200 OK
    RW->>RW: Route traffic to new container
    RW->>RW: Stop old container

Health Check Endpoint¶

@router.get("/ready")
async def readiness_check():
    """Railway health check endpoint."""
    checks = {
        "database": await check_postgres(),
        "redis": await check_redis(),
    }
    all_healthy = all(checks.values())
    return JSONResponse(
        status_code=200 if all_healthy else 503,
        content={"status": "ready" if all_healthy else "degraded", "checks": checks},
    )

Railway waits for /ready to return 200 before routing traffic. If the new container fails health checks, the deployment is rolled back automatically.

Dockerfile Essentials¶

FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8000
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Frontend: Vercel¶

Vercel provides automatic preview deployments on pull requests and production deployments on merge to main. The frontend communicates with the Railway backend exclusively over HTTPS.

PostgreSQL (Railway Internal)¶

PostgreSQL is the primary relational store for all transactional data: patients, providers, procedures, consents, documents, conversations, and audit logs.

Connection Configuration¶

# Railway provides DATABASE_URL automatically for internal PostgreSQL
DATABASE_URL = os.environ["DATABASE_URL"]
# Example: postgresql://user:pass@postgres.railway.internal:5432/railway

engine = create_async_engine(
    DATABASE_URL,
    pool_size=10,
    max_overflow=5,
    pool_pre_ping=True,
)

Neo4j Aura (Free Tier)¶

Neo4j stores the relationship graph between providers, procedures, doctors, specialties, and geographic regions. It powers the semantic matching engine that connects patients to the right providers.

Current Graph Statistics¶

Connection¶

from neo4j import AsyncGraphDatabase

driver = AsyncGraphDatabase.driver(
    "neo4j+s://21eea64f.databases.neo4j.io",
    auth=(NEO4J_USER, NEO4J_PASSWORD),
)

Qdrant Cloud (Free Tier)¶

Qdrant stores vector embeddings for semantic search across providers, medical conditions, and travel requirements.

Collections¶

Connection¶

from qdrant_client import QdrantClient

qdrant = QdrantClient(
    url=QDRANT_URL,        # https://xxx.europe-west3-0.gcp.cloud.qdrant.io
    api_key=QDRANT_API_KEY,
)

Upstash Redis (Free Tier)¶

Two Usage Patterns¶

1. Pub/Sub Queue (RPUSH/LPOP)

Used for real-time message passing between services:

# Producer: Push message to queue
await redis.rpush(f"queue:{session_id}", json.dumps(message))

# Consumer: Pop message from queue
raw = await redis.lpop(f"queue:{session_id}")

2. Cache (GET/SET with TTL)

Used to cache expensive computations and avoid redundant API calls:

# Cache with 5-minute TTL
await redis.set(f"cache:provider:{provider_id}", json.dumps(data), ex=300)

# Read from cache
cached = await redis.get(f"cache:provider:{provider_id}")

Four Hot Paths¶

Upstash QStash (Free Tier)¶

QStash delivers HTTP requests to the Railway backend on a schedule. Each task is a POST to a specific endpoint.

Six Cron Tasks¶

QStash Verification¶

from upstash_qstash import Receiver

receiver = Receiver(
    current_signing_key=QSTASH_CURRENT_SIGNING_KEY,
    next_signing_key=QSTASH_NEXT_SIGNING_KEY,
)

@router.post("/cron/{task_name}")
async def handle_cron(task_name: str, request: Request):
    body = await request.body()
    signature = request.headers.get("upstash-signature")
    receiver.verify(body=body, signature=signature, url=str(request.url))
    # Process the cron task...

Cloudflare R2 (Object Storage)¶

Why R2 Over S3?¶

Zero egress fees. When patients download their documents (medical records, visa copies, insurance paperwork), there is no per-GB charge. For a medical travel platform where documents are uploaded once and downloaded many times, this significantly reduces costs.

Presigned URL Flow¶

sequenceDiagram
    participant FE as Frontend
    participant BE as Backend
    participant R2 as Cloudflare R2

    FE->>BE: POST /documents/presign {filename, size, type}
    BE->>BE: Validate metadata (ext, MIME, size)
    BE->>R2: Generate presigned URL
    R2-->>BE: Presigned PUT URL (15min expiry)
    BE-->>FE: {upload_url, document_key}
    FE->>R2: PUT file directly to R2
    R2-->>FE: 200 OK
    FE->>BE: POST /documents/confirm {document_key}
    BE->>BE: Record document in PostgreSQL

Cloudflare DNS¶

Email: Resend¶

GitHub Repositories¶

Both repositories deploy automatically on push to main.

CORS Configuration¶

ALLOWED_ORIGINS = [
    "http://localhost:3000",           # Local frontend dev
    "https://curaway.vercel.app",      # Production frontend
    "https://curaway-health-navigator.vercel.app",  # Alternative frontend URL
]

app.add_middleware(
    CORSMiddleware,
    allow_origins=ALLOWED_ORIGINS,
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Environment Variables Reference¶

All environment variables required by the backend. Values are set in Railway's dashboard.

Cost Summary¶