Soulib

서울 공공 전자도서관을 한 번에 검색하는 모바일 우선 웹 서비스입니다.

• Production: https://www.soulib.kr
• Repository: https://github.com/pkkong/soulibrary
• Runtime: Vercel Serverless Functions + Flask
• Persistence: Supabase Postgres for shared shelves
• Search: live connectors, no prebuilt search database required

Status

Soulib is running in production on Vercel. main pushes run smoke tests, deploy to Vercel, and then run a live smoke test against https://www.soulib.kr.

What It Does

Soulib은 사용자가 검색하는 순간 여러 전자도서관 공급사를 직접 조회합니다. 미리 만든 검색 DB에 의존하지 않기 때문에 검색 결과와 상세 화면은 가능한 한 현재 도서관 상태에 가깝게 구성됩니다.

핵심 기능:

• 서울 전자도서관 통합 검색
• 교보, YES24, 북큐브 등 공급사별 실시간 조회
• 도서 상세와 도서관별 대출 상태 확인
• 브라우저 로컬 기반 내 서재
• 공유 가능한 서재 링크
• 오류 신고와 블로그 댓글의 GitHub Issues 연동
• Apps in Toss용 미니앱 클라이언트

Architecture

GitHub main
-> GitHub Actions smoke test
-> Vercel production deploy
-> index.py
-> web/app_search.py
-> web/live_search/*

현재 production entrypoint는 vercel.json -> index.py -> web/app_search.py입니다. Cloudtype 설정과 SQLite 기반 검색 앱은 운영 경로에서 제거했습니다.

Why Live Search

전자도서관 보유 정보와 대출 상태는 플랫폼별로 자주 달라집니다. Soulib은 과거처럼 로컬 SQLite 검색 DB를 먼저 만들지 않고, 검색 시점에 공급사 커넥터를 호출해 결과를 묶습니다. 이 구조는 배포를 가볍게 유지하고, Vercel에서도 같은 검색 동작을 재현하기 쉽게 만듭니다.

Tech Stack

• Python, Flask, Gunicorn
• Vercel
• Supabase Postgres
• GitHub Actions
• Vanilla JS/CSS templates
• React + Vite for apps-in-toss/

Local Run

python -m pip install -r requirements.txt
python web/app_search.py

Open:

http://127.0.0.1:5001

Verify:

python scripts/smoke_test.py
git diff --check

Repository Layout

web/                    Flask app, templates, static assets
web/live_search/         Real-time search connectors
scripts/                 QA, operations, and data utility scripts
content/blog/            Service blog content
supabase/migrations/     Shared shelf database schema
apps-in-toss/            Apps in Toss miniapp client
docs/                    Development and operations notes

Crawler and data-admin scripts are kept as optional tooling. They are not part of the default production search path.

Public Repository Notes

This repository is safe to run without private data. Local .env, .secrets/, database files, crawler outputs, logs, and build artifacts are ignored.

Production secrets must live only in GitHub Actions, Vercel, Supabase, or local ignored files. Do not commit tokens, service-account JSON, SQLite databases, CSV exports, or generated crawl output.

Contributing And Issues

This is a production service repository, not a general-purpose library package. Issues and pull requests should stay focused on the live search experience, deployment safety, documentation, and Apps in Toss client behavior.

• Bug reports: use the GitHub issue template and include the search query or URL.
• Security or credential issues: follow SECURITY.md.
• Local setup and verification: see CONTRIBUTING.md.

More Docs

• Development guide: README_DEV.md
• Production operations: docs/production_operations.md
• Public repository inventory: docs/public_repository_inventory.md
• Operating inventory: docs/phase0_operating_inventory.md
• Apps in Toss: apps-in-toss/README.md