Developer documentation

Build with Seoul Doc.

Everything you need to run the conversational medical facility finder, understand its retrieval pipeline, and connect a client to the API.

Quick start Open the app

Overview

Medical search that understands context

Seoul Doc helps English and Korean speakers find medical facilities in Seoul. It combines conversational intent extraction, location intelligence, exact evidence retrieval, and semantic ranking to turn natural-language requests into useful facility recommendations.

Conversational

Maintains specialty, location, travel, and preference context across turns.

Hybrid retrieval

Combines specific BM25 evidence with dense semantic search.

Location aware

Supports GPS, districts, neighborhoods, addresses, and landmarks.

Safety first

Detects emergency language and clearly separates search from medical advice.

How it works

From question to recommendation

Understand

The router detects language and intent, then extracts specialty, location, travel distance, and preferences.

Resolve

Google Maps resolves the location, with Kakao Maps available as a Korea-focused fallback.

Retrieve

An agentic loop chooses broad semantic search, specific BM25 evidence search, refinement, or completion.

Rank and answer

Candidates are filtered and ranked before the response is formatted into practical facility suggestions.

Quick start

Run locally

Use Python 3.12+ and Node.js 18+. Start the API and web client in separate terminals.

1. Start the backend

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --reload --host 0.0.0.0 --port 8000

2. Start the frontend

cd frontend
npm ci
npm run dev

Open http://localhost:3000. The first backend startup downloads the facility dataset and initializes its local search index, so it may take longer than later starts.

Configuration

Environment variables

Backend `backend/.env`

GROQ_API_KEYRequired

Powers intent extraction and response generation.

OPENAI_API_KEYRequired

Creates embeddings for semantic search.

GOOGLE_MAPS_API_KEYRequired

Geocodes locations and resolves place names.

KAKAO_REST_API_KEYRecommended

Provides Korea-focused geocoding fallback.

NAVER_CLIENT_IDOptional

Reserved for Naver integrations.

NAVER_CLIENT_SECRETOptional

Secret paired with the Naver client ID.

Frontend `frontend/.env.local`

NEXT_PUBLIC_LOCAL_API_URL=http://localhost:8000
NEXT_PUBLIC_SITE_URL=http://localhost:3000

API reference

FastAPI endpoints

When the backend is running, interactive OpenAPI documentation is available at http://localhost:8000/docs.

POST/chat

Send a message and conversation state; receive the assistant response and updated state.

POST/set_travel_preference

Update the maximum travel preference for a conversation.

POST/consent

Persist analytics, advertising, and functional cookie choices.

Example request

curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"Find an English-speaking dentist in Gangnam","current_state":{}}'

Safety

A search tool, not medical advice

Seoul Doc helps people discover facilities; it does not diagnose conditions or replace a qualified clinician. Facility details may change and should be confirmed directly. For a medical emergency in Korea, call 119; for the medical information hotline, call 1339.

Ready to explore?

Try the live experience or return to the setup guide.

Open Seoul Doc Setup guide