프로젝트 소개

«القرآن الكريم» 앱은 MIT 라이선스의 아랍어 오픈 소스 프로젝트로, 웹 브라우저와 안드로이드 기기에서 꾸란 읽기, 청취, 검색 및 해석 조회를 가능하게 합니다. 현재 저장소 버전은 3.1.20이며, 필드 테스트용 Debug 서명 APK 파일과 GitHub Pages에 게시된 웹 버전이 배포됩니다. 이 프로젝트는 아랍어, 영어, 프랑스어, 독일어, 러시아어, 터키어, 말레이어, 인도네시아어 등 8개 인터페이스 언어를 지원하며, 아랍어의 경우 RTL 방향을 지원합니다. 읽기 기능에서는 AlQuran.cloud에서 제공하는 오스만체로 114개 수라를 표시하며, 수라 간 이동, 마지막 위치 저장, 현재 구절 강조, 15개의 사즈다 표시, 30개 부분(Juz) 구분선 및 스크롤 연동 진행 표시줄을 제공합니다. 글꼴 크기(16–45px), 글꼴 종류(Amiri, Scheherazade New, Reem Kufi) 및 줄 간격을 조절할 수 있으며, 5가지 의미 번역, 낮/밤 모드의 18가지 색상 태즈위드(Tadjweed) 규칙, 암기 훈련을 위한 텍스트 숨김 모드, 그리고 요청 시 구절을 공개하는 커튼 기능이 포함된 «암기실»(낭독자, 속도, 범위 반복 설정 가능)을 제공합니다. 수라 모드에서는 킹 파흐드 글로리 꾸란 인쇄 단지의 공식 하프스 오스만 글꼴을 적용할 수 있으며, 페이지 모드는 QCF4를 유지합니다. 604페이지 레이아웃의 오프라인 꾸란 데이터는 각 파일의 SHA-256 지문 검사 후 선택적으로 다운로드할 수 있습니다. 청취 기능은 30인 이상의 낭송자를 포함하며, API를 통한 구절별 음원과 mp3quran.net의 수라 전체 MP3 파일(타이밍 포함)이라는 두 가지 소스를 사용합니다. quran.com API를 통해 단어별 강조 표시를 지원하며, 수라 간 연속 재생, 반복 모드(정지, 구절, 수라, 사용자 지정 범위), 1~180분 수면 타이머, 속도 제어, 잠금 화면 제어를 위한 MediaSession 통합, 자동 재시도, Canvas 기반 오디오 비주얼라이저, 구절 번호 시작 재생, 완독 알림 기능을 제공합니다. 오프라인 패키지는 꾸란 텍스트, 번역, 태즈위드 데이터, QCF4 글꼴 및 선택한 낭송자의 음원을 IndexedDB(최대 200MB, LRU 비우기 적용)에 저장하며, 저장소 통계 및 선택적/전체 삭제 기능을 제공합니다. 검색 기능은 6,236개 구절을 대상으로 하며, 모음 기호(Tashkeel) 유무와 상관없이 텍스트를 매칭하고 결과를 강조 표시합니다. 단어 접두사 제안, 최근 검색 기록 10개, Web Speech API를 통한 아랍어 음성 검색, 화면상 아랍어 키보드 및 페이지네이션 결과를 제공합니다. 해석(Tafsir)은 6가지 버전(Al-Muyassar, Ibn Kathir, Al-Tabari, Al-Saadi, Al-Baghawi, Al-Qurtubi)을 제공하며, 로컬에서 IndexedDB, API 순으로 단계적 로딩을 수행하고 QuranTafsirDB에 캐싱합니다. «구절 묵상» 기능은 세 가지 성찰 질문을 제시하며, 별도의 입력창, 계정, AI 서비스 전송 없이 로컬 데이터로 작동합니다. 이는 개인적 성찰 수단이며 공인된 해석이 아님을 알리는 경고가 표시됩니다. «꾸란 모드»는 Canvas를 통해 604페이지의 QCF V4 글꼴을 표시하며, 단어별 태즈위드 색상 적용, 클릭한 구절의 재생 및 해석 연결, 인접 페이지 사전 로딩 기능을 제공합니다. «전시 모드»는 단색, 자연, 기분/시간별 배경 및 Canvas 장면(별, 파도, 오로라, 입자, 비)을 통한 전체 화면 뷰를 제공하며, 구절별 와이드 이미지나 로컬 HD 비디오 배경(Mishary Al-Afasy 음성 포함)을 설정할 수 있고 모든 처리는 사용자 기기에서 이루어집니다. 추가적으로 Aladhan을 통한 6가지 기도 시간, 아잔 알림, Umm al-Qura 달력 기반 히즈라 날짜, 키블라 나침반, 카운터 및 알림이 포함된 아침/저녁 및 맞춤형 아즈카르, 텍스트/JSON 내보내기가 가능한 즐겨찾기 및 북마크, 읽기 통계, 딥 나이트 모드를 포함한 4가지 테마를 제공합니다. Capacitor Share 또는 Web Share API를 통해 WhatsApp, Telegram으로 공유할 수 있으며, 키보드 단축키 및 접근성 테마(포커스 트랩, ARIA 라이브 영역, 콘텐츠 건너뛰기 링크, 동작 감소 및 고대비 준수)를 지원합니다. 기술적으로 이 프로젝트는 엄격한 모드의 TypeScript 6.0, LightningCSS가 포함된 Vite 8, PWA를 위한 vite-plugin-pwa (Workbox), 안드로이드 패키징을 위한 Capacitor 8을 기반으로 합니다. 외부 프레임워크 없이 Proxy 기반의 반응형 상태 관리를 사용하며, localStorage와 3개의 IndexedDB(QuranAppDB, QuranAudioCacheDB, QuranTafsirDB)에 데이터를 저장합니다. 외부 API로는 AlQuran.cloud, Aladhan, jsDelivr(해석), mp3quran.net, quran.com을 사용합니다. CI/CD 파이프라인에는 린트, 타입 체크, 80% 이상의 커버리지를 갖춘 단위 테스트, 4개 프로젝트(chromium, firefox, webkit, mobile-chrome)에 대한 Playwright 테스트, CodeQL, 기본 OWASP ZAP 스캔, Lighthouse CI, WCAG 위반 없는 axe-core 스캔, 번들 크기 및 성능 예산 모니터링, TypeDoc 생성, npm audit 및 라이선스 검사, 태그 릴리스 시 자동 배포가 포함됩니다. 저장소에 따르면 3,812개의 단위 테스트와 284개의 UI 테스트 케이스를 보유하고 있으며, 로컬 프로덕션 빌드의 Lighthouse 결과는 성능 93, 접근성 100, 최적 사례 96, SEO 91을 기록했습니다(이는 내부 기술 평가이며 외부 독립 인증이 아님). 로컬 실행을 위해서는 Node.js 22 이상이 필요하며, npm install 후 개발(포트 3000), 빌드, 미리보기, 단위/E2E 테스트, 코드 검사, 안드로이드 빌드 명령어를 사용할 수 있습니다. 일반 사용자는 빌드 과정 없이 APK 파일을 직접 다운로드하면 됩니다. 또한 저장소는 검사 가능 항목, 오프라인 작동 범위 및 알려진 제한 사항을 설명하는 기술 평가 가이드를 제공합니다.