• 제가 Aveliq를 만들기 위해 자리에 앉았을 때, 저에게는 단 하나의 목표가 있었습니다. 모든 나이지리아 학생들에게 실제로 더 스마트하게 공부할 수 있도록 돕는 도구에 대한 접근성을 제공하는 것이었습니다. 단순히 재포장된 ChatGPT wrapper(래퍼)가 아닙니다. 또 다른 일반적인 퀴즈 앱도 아닙니다. 매년 수백만 명의 나이지리아 학생들의 궤적을 실제로 결정하는 시험인 WAEC, JAMB, NECO 및 Post-UTME를 위해 특별히 구축된 무언가를 만드는 것이었습니다.

제 이름은 George Erubami입니다. GeoCode라는 이름으로 활동합니다. 저는 나이지리아 이바단에 거주하는 18세 독학 개발자입니다. 저는 프론트엔드(frontend), 백엔드(backend), AI integration(AI 통합), 디자인(design), 배포(deployment), 법적 페이지(legal pages), PWA 설정(PWA setup) 등 Aveliq의 모든 과정을 처음부터 끝까지 직접 구축했습니다. 이것은 제가 어떻게 그것을 해냈는지, 그리고 무엇을 배웠는지에 대한 이야기입니다.

What Aveliq Does (Aveliq가 하는 일)

Aveliq는 AI 기반의 학습 동반자입니다. 현재 제공하는 기능은 다음과 같습니다:

• AI Summaries (AI 요약) — 어떤 노트든 붙여넣으면 과목 및 시험 위원회에 맞춘 핵심 개념, 흔한 시험 실수, 복습 팁이 포함된 구조화된 학습 가이드를 얻을 수 있습니다.
• Exam Quizzes (시험 퀴즈) — 노트로부터 WAEC 및 JAMB 스타일의 문제를 생성하고, 답안을 제출하면 즉각적이고 상세한 피드백을 받습니다.
• 7-Day Revision Plans (7일 복습 계획) — 실제 노트를 기반으로 구축된 개인 맞춤형 학습 일정으로, 시간 제한이 있고 실행 가능합니다.
• Vexio AI Tutor (Vexio AI 튜터) — 학생들이 언제든 자신의 과목에 대해 무엇이든 물어볼 수 있는 전용 채팅 화면입니다.
• YouTube Analysis (YouTube 분석) — YouTube 링크를 붙여넣으면 비디오 콘텐츠로부터 전체 학습 가이드를 얻을 수 있습니다.
• PDF and Photo Upload (PDF 및 사진 업로드) — 교과서 페이지를 찍거나 PDF를 업로드하면, OCR(광학 문자 인식)이 텍스트를 추출하고 Vexio가 이를 처리합니다.
• Flashcards, Focus Timer, Streaks, Achievements (플래시카드, 집중 타이머, 연속 기록, 업적) — 학생들이 계속 돌아오게 만드는 일관성 계층입니다.

모든 것은 제가 GEOCODE Intelligence라고 부르는 것에 의해 구동됩니다. 이는 앱이 무료 티어에서도 항상 빠르고 항상 사용 가능하도록 제가 구축한 5개의 제공업체 AI 체인(AI chain)입니다.

The Tech Stack (기술 스택)

Frontend (프론트엔드): HTML, CSS, Vanilla JavaScript. 프레임워크(Framework) 없음. 빌드 도구(Build tool) 없음. 저는 Android에서 Termux와 Acode를 사용하여 개발하기 때문에, 툴체인(Toolchain)을 단순하게 유지하는 것이 의도적인 선택이었습니다.
Backend (백엔드): Express를 사용한 Node.js, Render에 배포.

Database and Auth (데이터베이스 및 인증): Firebase Firestore 및 Firebase Authentication.

Deployment (배포): 프론트엔드는 Vercel, 백엔드는 Render.

AI (인공지능): 다섯 개의 제공업체를 체인(Chain)으로 연결 — 이에 대한 자세한 내용은 아래에서 설명합니다.

가장 흥미로운 기술적 결정: AI 폴백 체인 (AI Fallback Chain)

Aveliq 백엔드의 핵심은 제가 'GEOCODE Intelligence 체인'이라고 부르는 것입니다. 모든 AI 요청은 다음과 같은 폭포수(Waterfall) 구조를 거칩니다:

Cerebras → Groq → OpenRouter → Mistral → Gemini

제가 왜 이런 방식으로 구축했는지에 대한 이유입니다.

단일 제공업체에 의존할 때의 문제점

모든 무료 티어(Free-tier) AI API에는 속도 제한(Rate limits)이 있습니다. Cerebras는 분당 일정 수의 요청을 허용합니다. Groq도 자체적인 제한이 있습니다. 만약 단일 제공업체를 기반으로 앱을 구축했는데 해당 제공업체가 제한에 도달하거나 다운된다면, 앱 전체가 작동을 멈추게 됩니다. 시험 전날 밤 학생들에게 사용되는 학습 앱에서 이는 용납될 수 없는 일입니다.

체인의 작동 방식

javascript
async function callAI(prompt) {
const result =
await callCerebras(prompt) ||
await callGroq(prompt) ||
await callOpenRouter(prompt) ||
await callMistral(prompt) ||
await callGemini(prompt);

if (!result) throw new Error('All AI providers failed.');
return result;
}

각 제공업체 함수는 실패하거나 속도 제한에 걸리면 null을 반환하며, 체인의 다음 제공업체가 자동으로 시도됩니다. 학생은 에러를 전혀 보지 못하며, 최악의 경우 응답이 약간 느려질 뿐 응답을 받게 됩니다.

왜 Cerebras가 첫 번째인가

Cerebras는 제가 발견한 가장 빠른 추론(Inference) 제공업체입니다. 그들의 Llama 3.3 70B 모델은 대부분의 요청에 대해 2초 미만으로 응답합니다. 이것이 Aveliq를 즉각적인 것처럼 느끼게 만드는 요소입니다. 대부분의 요청은 Groq에 도달조차 하지 않습니다.

속도 제한기 (The Rate Limiter)

여러 제공업체의 무료 티어를 사용하고 있기 때문에, 제 백엔드 자체를 남용으로부터 보호할 필요도 있었습니다. 저는 간단한 슬라이딩 윈도우(Sliding window) 방식의 속도 제한기를 구축했습니다:

const rl = new Map();

function rateLimiter(req, res, next) {
...

이것은 IP 기반(IP-based)이며, 인메모리(in-memory) 방식이고, 매시간 스스로 정리됩니다. 현재 규모에서는 단순하면서도 효과적입니다.

Android 기반 구축

이 이야기를 하고 싶은 이유는, 대부분의 튜토리얼이 여러분이 다룰 필요가 없다고 가정하는 부분이기 때문입니다.

저는 Aveliq를 전적으로 Android 상에서 구축했습니다. 저의 도구는 터미널을 위한 Termux, 코드 에디터인 Acode, 그리고 버전 관리(Version control)를 위한 GitHub입니다. MacBook도, 데스크톱도, 확장 프로그램이 설치된 VS Code도 없습니다. 오직 스마트폰뿐입니다.

이로 인해 저는 특정한 결정들을 내려야만 했습니다:

빌드 도구 없음. Webpack, Vite, 번들러(Bundlers)가 없습니다. 프론트엔드는 순수한 HTML, CSS, JavaScript로 구성됩니다. 이는 모든 파일이 서버에 제공되는 그대로라는 것을 의미합니다. 즉, 컴파일 단계(Compilation step), 소스 맵(Source maps), 빌드 에러(Build errors)가 없습니다. 또한 이것이 앱이 빠르게 로드되는 이유이기도 합니다.

로컬 서버 테스트 없음. 저는 초기 단계부터 자주 배포합니다. GitHub에 푸시(Push)하면 Vercel이 자동으로 배포(Auto-deploys)하고, 실제 라이브 URL에서 테스트합니다. 모든 푸시가 실제 배포이기 때문에, 저는 무엇을 커밋(Commit)할지에 대해 매우 신중해질 수밖에 없었습니다.

Node를 위한 Termux. Render에 푸시하기 전, Termux에서 로컬로 node server.js를 실행하는 방식으로 백엔드 로직을 테스트했습니다. 작동은 하지만, 스마트폰 화면에서 디버깅(Debugging)하는 것은 즐거운 일이 아니기에 깔끔하고 읽기 쉬운 서버 코드를 작성하는 법을 배웠습니다.

PWA 설정

Aveliq는 PWA (Progressive Web App)입니다. 이것이 실제로 의미하는 바는 다음과 같습니다:

• 적절한 192px 및 512px PNG 아이콘을 포함한 manifest.json (SVG가 아님 — iOS 홈 화면은 PNG를 요구함)
• 모든 정적 자산(Static assets)을 캐싱(Caching)하고, 연결이 없을 때 오프라인 폴백(Offline fallback) 페이지를 제공하는 서비스 워커(Service worker)
• beforeinstallprompt 이벤트를 통해 Android Chrome에서 자동으로 나타나는 설치 프롬프트(Install prompt)
• iOS 홈 화면을 위한 180x180 크기의 apple-touch-icon.png

오프라인 폴백(Offline fallback)은 제가 나이지리아 사용자들을 위해 특별히 신경 쓰는 부분입니다. 데이터 비용은 비싸고 연결은 자주 끊깁니다. 만약 학생이 이미 Aveliq를 불러온 상태에서 세션 도중 연결이 끊긴다면, 빈 화면을 보는 것이 아니라 캐시된 콘텐츠와 함께 어떤 일이 발생했는지에 대한 명확한 메시지를 보아야 합니다.

다음 단계

세션 3 — 기출문제 엔진 (Past Questions Engine)

이것은 제가 가장 기대하고 있는 기능입니다. 아키텍처는 커뮤니티에 의해 구동됩니다:

1. 학생이 실제 WAEC, JAMB 또는 NECO 기출문제 시험지의 사진이나 PDF를 업로드합니다.
2. OCR(광학 문자 인식)이 텍스트를 추출합니다.
3. Vexio가 이를 깔끔한 Q&A JSON 구조로 만듭니다.
4. 이를 공유된 Firestore 컬렉션에 저장합니다.
5. 해당 시험지를 검색하는 다른 모든 학생은 즉시 이를 받게 됩니다 — 다시 OCR을 수행할 필요가 없습니다.

사용자가 늘어남에 따라 데이터베이스는 스스로 구축됩니다. 시험지를 처음 업로드하는 사람이 한 번만 작업을 수행하면, 모든 사람이 영구적으로 혜틱을 누립니다. 또한 검증 레이어(Verification layer)를 추가합니다 — 만약 세 명의 서로 다른 사용자가 동일한 시험지를 업로드하고 질문이 일치하면, 자동으로 검증됩니다. 가짜 질문이 풀(Pool)에 들어오는 것을 방지합니다.

세션 8 — Paystack 연동 (Paystack Integration)

일일 제한이 있는 무료 티어(Free tier). 무제한 액세스를 위한 프리미엄은 월 ₦1,500. 3개월 시험 대비 과정은 ₦3,500. 결제는 Paystack을 통해 게이트웨이 방식으로 이루어지며, Firebase 웹훅(Webhook)을 통해 구독 상태를 업데이트합니다.

내가 배운 것들

빠르게 출시하고, 공개적으로 수정하라 (Ship fast, fix in public). 이전의 Aveliq에는 문제들이 있었습니다. 조용히 수정하는 대신, 저는 완전히 새로 만들고 그 과정을 문서화했습니다. 공개적으로 빌드하는 것(Building in public)은 스스로에게 책임감을 부여하며, 당신의 성공을 보고 싶어 하는 사람들을 끌어들입니다.

AI가 어려운 부분이 아니다. API를 호출하는 것은 코드 다섯 줄이면 충분합니다. 어려운 부분은 그 주변의 사용자 경험(User experience) — 로더(Loaders), 에러 상태(Error states), 폴백(Fallbacks), 신원 레이어(Identity layer), 속도 제한(Rate limiting) 등입니다. AI는 단지 엔진일 뿐입니다. 제품은 그 외의 모든 것입니다.

사용자의 현실에 맞춰 구축하세요. 제 사용자들은 데이터를 공유하며 월세 방에서 2G 연결로 공부합니다. PWA(Progressive Web App), 오프라인 폴백(Offline fallback), 빠른 AI 체인(AI chain), WhatsApp 공유 버튼 등 모든 디자인 결정은 상상 속의 이상적인 사용자가 아니라, 바로 그 구체적인 사람을 생각하며 내려진 것입니다.

적절한 도구가 필요한 것이 아닙니다. 시작하는 것이 필요합니다. 저는 이것을 휴대폰으로 만들었습니다. 도구는 장벽이 아닙니다.

한번 사용해 보세요

Aveliq는 **studypal.com.ng**에서 라이브 상태입니다.

앱은 **studypal.com.ng/app**에 있습니다.

제 포트폴리오 **george-erubami.vercel.app**에서 업데이트를 게시합니다.

당신이 나이지리아 학생이라면 — 사용해 보세요. 당신이 개발자라면 — 의견을 알려주세요. 구축 과정을 따라오고 싶다면 — 저는 모든 세션을 기록합니다.

George Erubami (GeoCode) 제작 — 나이지리아 이바단 출신의 18세 독학 개발자.

GitHub: Geocode-hub · X: @CoolRexy150983 · Instagram: @geocodedev · WhatsApp: +234 907 269 0451