CodeWave

• 

  project pipeline

Canva Link https://www.canva.com/design/DAGkcA9ANUQ/pRWtXTYj6z4Q9G5ClW8-Qg/view?utm_content=DAGkcA9ANUQ&utm_campaign=designshare&utm_medium=link2&utm_source=uniquelinks&utlId=h38a74e1d6a

Github Link https://github.com/dominhok/CodeWave

💡Inspiration

The inspiration behind CodeWave - Disaster Safety Alert System came from the limitations of traditional emergency alert systems.

CodeWave - 재난 안전 알림 시스템은 기존의 전통적인 재난 알림 시스템의 한계에서 출발했습니다.

---

❓ What it Does

CodeWave - Disaster Safety Alert System is a platform that delivers targeted alerts during disaster situations for the vulnerable classes. It notifies users based on their vulnerability type, disaster type and location using SMS and voice calls, interprets their voice responses for signs of distress, and routes critical information to emergency contacts when necessary. It also provides interactive map guidance to nearby shelters and offers summarized voice reports for real-time situational awareness. This system is especially designed to assist at-risk populations who may need tailored support during emergencies.

CodeWave - 재난 안전 알림 시스템은 재난 상황에서 취약 계층을 위한 맞춤형 알림을 제공하는 서비스입니다. 사용자 유형, 재난 유형, 위치 정보를 바탕으로 SMS와 음성 전화를 통해 알림을 전달하며, 사용자의 음성 응답을 분석해 위급 신호를 감지하고, 필요 시 긴급 연락처로 중요한 정보를 전송합니다. 또한, 주변 대피소로의 지도 안내와 실시간 상황 인식을 위한 요약 음성 리포트를 제공합니다. 이 시스템은 특히 재난 시 맞춤형 지원이 필요한 취약 계층을 돕기 위해 설계되었습니다.

---

🛠️ How We Built It

• Backend Framework: FastAPI for asynchronous web APIs.
• Database: SQLAlchemy with SQLite (default), ready for production upgrades like PostgreSQL.
• Vector Store & RAG: FAISS for semantic search across disaster manuals, powered by Upstage AI LLMs for Retrieval-Augmented Generation (RAG).
• Voice Interpretation: Upstage AI analyzes voice input for emergency intent.
• Communication Integration: Twilio handles SMS and voice calling (TTS, STT and voice response).
• Geolocation Services: KakaoMap API geocodes user addresses; shelter data is fetched from Korea’s Safety Data Portal.
• Maps: Naver Maps (JavaScript) provides a disaster map interface, showing epicenters, user locations, and nearby shelters.
• Multi-language Support: Basic KO→EN translation via Upstage AI.
• Deployment Support: Uvicorn ASGI server, dotenv for environment management, and Ngrok for local webhook tunneling.

• Frontend Support: HTML/CSS, JavaScript and React.js for interactive disaster maps (static folder setup).

• Backend Framework: FastAPI를 사용하여 비동기 웹 API를 구축

• Database: SQLAlchemy와 SQLite(기본값)를 사용했으며, 추후 PostgreSQL 같은 프로덕션 환경으로의 확장 가능.

• Vector Store & RAG: FAISS를 활용한 재난 매뉴얼의 시맨틱 검색과 Upstage AI LLM을 통한 RAG(Retrieval-Augmented Generation)를 구현

• Voice Interpretation: Upstage AI가 음성 입력을 분석해 긴급 상황 의도를 파악

• Communication Integration: Twilio를 통해 SMS 및 음성 통화(TTS, STT, 음성 응답)를 처리

• Geolocation Services: 카카오맵 API를 통해 사용자 주소를 지오코딩하고, 대피소 정보는 공공데이터포털(안전정보포털)에서 가져옴

• Maps: Naver Maps(JavaScript)를 사용해 재난 지도 인터페이스를 구현했으며, 진앙지, 사용자 위치, 인근 대피소를 전송

• Multi-language Support: Upstage AI를 통해 기본적인 한국어→영어 번역 기능을 제공

• Deployment Support: Uvicorn ASGI 서버, dotenv를 통한 환경 변수 관리, Ngrok으로 로컬 웹훅 터널링을 지원

• Frontend Support: HTML/CSS와 JavaScript, React.js를 사용해 인터랙티브 재난 지도를 구성

---

🚧 Challenges We Ran Into

• Emergency Escalation: Safely routing voice messages to emergency contacts without false positives or missed distress cases required rigorous intent classification logic.
• Voice Understanding: Accurately interpreting user responses over calls required careful prompt tuning and testing with Claude to differentiate between general queries and distress calls.
• Webhook Testing: Twilio's webhook system required stable public URLs, and free tunneling services (like Ngrok) sometimes introduced latency or blocking interstitials.

• Vector Store Preparation: Creating meaningful vector representations from diverse and sometimes unstructured disaster manuals was non-trivial. The quality of response from RAG heavily depended on the preprocessing of .txt content.

• 긴급 상황 대응: 음성 메시지를 긴급 연락처로 안전하게 전달하는 과정에서, 의도치 않은 신고나 긴급 상황을 놓치지 않도록 신고 분류 로직을 엄격하게 구현해야 했습니다.

• 음성 이해: 음성 통화에서 사용자의 응답을 정확히 해석하기 위해, 일반적인 질문과 긴급 통화를 구분할 수 있도록 Claude와 함께 프롬프트 튜닝과 테스트를 신중하게 진행해야 했습니다.

• 벡터 DB: 다양한 형식의 재난 매뉴얼에서 유의미한 벡터 표현을 생성하는 작업은 쉽지 않았으며, RAG 응답의 품질은 .txt 파일 전처리 수준에 크게 좌우되었기 때문에 이를 최적화하는 데 많은 시간이 소요되었습니다.

• 웹훅 테스트: Twilio의 웹훅 시스템은 안정적인 공개 URL을 요구했으며, Ngrok과 같은 무료 터널링 서비스는 때때로 지연 시간이나 서비스 차단 문제를 일으켜 안정성에 영향을 미쳤습니다.

---

🏆 Accomplishments That We're Proud Of

• Personalized, AI-Generated Alerts: Using large language models (LLMs) and Retrieval-Augmented Generation (RAG), alert messages are tailored to the user's personal status and the specific disaster situation, improving clarity and relevance.
• Automatic Escalation to Emergency Contacts: Upon receiving a response from the user, intelligent triage using Claude analyzes the situation to determine if it is an emergency and then escalates it to the appropriate emergency contacts, all without human intervention.
• Voice-Aware Safety System: We have seamlessly integrated voice AI into a real-time emergency alert system with an asynchronous workflow, enabling natural and efficient interaction for users in need of assistance.
• Multi-Modal Outreach: The system supports both SMS and voice delivery channels, making it accessible across a broad range of user abilities and preferences.

• Live Disaster Mapping: Real-time, browser-based interactive maps that allow users to track the current disaster location and evacuation routes to near shelters through a link provided via SMS.

• 개인화된 AI 생성 알림: 대규모 언어 모델(LLM)과 Retrieval-Augmented Generation(RAG)을 활용하여 알림 메시지를 사용자의 개인 상태와 특정 재난 상황에 맞게 맞춤화함으로써, 명확성과 관련성을 향상시켰습니다.

• 긴급 연락처로의 자동 신고 시스템: 사용자의 응답을 받은 후, Claude를 이용한 지능형 트리아지가 상황을 분석하여 긴급 상황 여부를 판단하고, 적절한 긴급 연락처로 자동으로 전달됩니다. 이 모든 과정은 사람의 개입 없이 진행됩니다.

• AI 음성 시스템: 음성 AI를 실시간 긴급 알림 시스템에 통합하여 비동기 워크플로우로 자연스럽고 효율적인 상호작용을 가능하게 했습니다. 이를 통해 도움이 필요한 사용자에게 동시다발적으로 더 나은 서비스를 제공합니다.

• 다중 모드 신고: 시스템은 SMS와 음성 전달 채널을 모두 지원하여, 사용자들의 상황과 선호도를 충족시킬 수 있습니다.

• 실시간 재난 지도: 실시간 브라우저 기반 인터랙티브 지도를 제공하여, 사용자가 현재 재난 위치와 대피소로 가는 경로를 SMS로 제공된 링크를 통해 추적할 수 있습니다.

---

📚 What We Learned

• LLMs for Emergency Use-Cases: With proper guardrails and prompt design, large language models can be powerful tools in high-stakes, time-sensitive scenarios like disaster response.
• API Interoperability: Building a resilient system that integrates multiple APIs (Twilio, Kakao, Naver, Upstage, Anthropic) involves error handling, retries, and good observability.
• Platform Integration is Crucial: Coordinating communication across different platforms (SMS, voice calls, maps, dashboards, emergency contact systems) requires clear interface contracts and reliable state management to ensure consistent, timely user experiences.
• Language Accessibility: Translation support, even basic, can make a significant difference in user reach and comprehension in multilingual communities.

• Preparedness is a Data Problem: The effectiveness of RAG systems hinges on the availability of clear, well-structured, and relevant disaster manuals.

• LLM의 재난시 활용: 적절한 가드레일과 프롬프트 설계를 통해 대형 언어 모델(LLMs)은 재난 대응과 같은 고위험, 시간에 민감한 시나리오에서 강력한 도구가 될 수 있습니다.

• API 통합: 여러 API(Twilio, Kakao, Naver, Upstage, Anthropic)를 통합하는 견고한 시스템을 구축하려면 오류 처리, 지속적인 관찰이 필요합니다.

• 플랫폼 통합의 중요성: SMS, 음성 통화, 지도, 대시보드, 긴급 연락처 시스템 등 다양한 플랫폼을 통합하려면 명확한 인터페이스 설계와 신뢰할 수 있는 상태 관리가 필수적입니다.

• 언어 접근성: 기본적인 번역 지원만으로도 대한민국에 거주하는 외국인들이 재난 상황에서 보다 효율적으로 신고하거나 안내를 받을 수 있도록 도울 수 있습니다.

• 기존에 잘 가공된 데이터 사용: RAG 시스템의 효율은 명확하고 잘 구조화된 관련 재난 매뉴얼 즉, 잘 정제된 데이터에 큰 힘을 발휘합니다.

---

🔮 What's Next for Our Project

• Real-Time Alert Service Improvements: Continuously enhance real-time notification services to ensure faster, more accurate delivery of disaster-related updates.
• Expanded Vulnerability Segmentation: Further refine user vulnerability categories to provide even more personalized services, targeting specific needs based on physical, visual, or cognitive impairments.
• International Expansion: Explore the potential for expanding the service to international markets, ensuring accessibility for users in different regions.
• Improved Multilingual Translation: Expand to more language pairs (e.g., EN↔JP, EN↔ZH) with backtranslation verification.
• Community Engagement and Feedback: Establish mechanisms for user feedback to inform ongoing improvements and ensure the system remains aligned with the needs of vulnerable populations.
• Admin mode : This mode is designed for public officials or system administrators to assist vulnerable individuals such as the elderly living alone. It allows bulk user registration via Excel upload and other administrative tools.

• Phone Call Retry System: In case the user does not answer the phone, the system will automatically retry calling every 5 minutes. Additionally, the data will be forwarded to fire departments or government agencies to ensure appropriate action is taken.

• 실시간 알림 서비스 고도화: 재난 관련 정보를 더욱 빠르고 정확하게 전달할 수 있도록 실시간 알림 서비스를 고도화 하는 방안을 생각해 볼 수 있습니다.

• 취약성 세분화 확대: 신체적, 시각적, 인지적 특성을 기반으로 사용자 유형을 보다 정밀하게 분류하여, 각 상황에 맞춘 세밀한 맞춤형 서비스를 제공할 수 있습니다.

• 시장 확대성: 서비스를 해외로 확장할 가능성을 모색하며, 다양한 지역의 사용자들도 쉽게 접근할 수 있도록 접근성과 호환성을 확보할 수 있습니다.

• 다국어 번역 기능 개선: 더 많은 언어를 지원하도록 확장하고, 역번역의 정확성과 신뢰도를 높일 수 있습니다.

• 커뮤니티 참여 및 피드백 반영: 사용자 의견을 반영할 수 있는 체계를 구축하여, 시스템이 실제 취약 계층의 요구에 부합하도록 지속적으로 점검하고 개선할 수 있습니다.

• 행정 모드(가칭) : 이 모드는 지역 담당 공무원 등 관리자 계정에서만 접근할 수 있으며, 엑셀 파일 등을 통해 복수 사용자를 대리로 등록할 수 있는 기능을 제공합니다. 독거노인 분들과 같이 스스로 등록 및 대리신청이 불가능한 분들을 위한 행정 지원 수단으로 활용됩니다.

• 전화 재시도 시스템: 사용자가 전화를 받지 않을 경우, 시스템은 5분마다 자동으로 전화를 재시도합니다. 또한, 해당 데이터는 소방서나 정부기관에 전달되어 적절한 조치가 이루어지도록 합니다.

---

🧰 Built With

• Python (FastAPI, SQLAlchemy, Uvicorn)
• Twilio (Programmable SMS, Voice, TTS)
• Upstage AI (Translation)
• Anthropic Claude (RAG, LLM, Voice Response Intent Classification)
• FAISS (Vector Search for Disaster Manual RAG)
• Langchain (LLM Orchestration)
• KakaoAPI (Address Geocoding)
• NaverMapsAPI (Interactive Shelter Maps)
• SQLite (Default DB for Development)
• Ngrok (Webhook Tunneling)
• Pydantic, dotenv, httpx (Validation and Config)

---

Built With

• claude
• faiss
• kakaoapi
• langchain
• navermapsapi
• ngrok
• python
• sqlite
• twilio
• upstage