{"id":50375810,"url":"https://github.com/fisayo-dev/verifyng","last_synced_at":"2026-05-30T09:30:50.583Z","repository":{"id":356509013,"uuid":"1232766121","full_name":"fisayo-dev/verifyng","owner":"fisayo-dev","description":"Nigerian certificate verification  - Squad Hackathon 3.0","archived":false,"fork":false,"pushed_at":"2026-05-15T12:54:35.000Z","size":753,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-15T13:21:03.210Z","etag":null,"topics":["ai","certificate","squad","verification"],"latest_commit_sha":null,"homepage":"https://verifyng-three.vercel.app","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fisayo-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-08T08:47:30.000Z","updated_at":"2026-05-15T11:38:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fisayo-dev/verifyng","commit_stats":null,"previous_names":["fisayo-dev/verifyng"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/fisayo-dev/verifyng","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fisayo-dev%2Fverifyng","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fisayo-dev%2Fverifyng/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fisayo-dev%2Fverifyng/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fisayo-dev%2Fverifyng/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fisayo-dev","download_url":"https://codeload.github.com/fisayo-dev/verifyng/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fisayo-dev%2Fverifyng/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33687717,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","certificate","squad","verification"],"created_at":"2026-05-30T09:30:49.616Z","updated_at":"2026-05-30T09:30:50.570Z","avatar_url":"https://github.com/fisayo-dev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# VerifyNG\n\nAI-powered academic certificate verification for Nigerian employers, schools,\nrecruiters, and institutions.\n\nVerifyNG was built by **Team Finsense** for **Squad Hackathon 3.0,\nChallenge 01: Proof of Life**. The product helps a user upload an academic\ndocument, pay a verification fee through Squad, and receive an explainable AI\ntrust score with a verdict, confidence level, and risk flags.\n\n## Live Product\n\n- Frontend: https://verifyng-three.vercel.app\n- Backend API: https://olatunjitobi-verifyng-api.hf.space\n- Health check: https://olatunjitobi-verifyng-api.hf.space/health\n- Repository: https://github.com/fisayo-dev/verifyng\n\n## Why This Exists\n\nThe hackathon brief asks teams to build an AI system that helps people,\nbusinesses, or institutions verify, trust, or authenticate something where fraud\nor opacity is common. VerifyNG chooses the **education** domain: fake academic\ncertificates, exam results, and altered scans.\n\nManual certificate verification is slow, expensive, and difficult to scale.\nEmployers may need to contact institutions one by one, while applicants and HR\nteams wait days for a decision. VerifyNG provides a fast first-pass screening\nlayer: it does not replace the institution of record, but it helps organizations\nidentify high-risk documents before they spend time and money on manual review.\n\n## The Core User Journey\n\n1. A user opens the PWA and uploads a certificate or result image.\n2. The backend creates a verification job and starts a Squad checkout.\n3. The user pays the verification fee through Squad.\n4. Squad redirects/calls back to the backend with the transaction reference.\n5. The backend confirms the payment, uploads the file to Supabase Storage, and\n   triggers the AI pipeline.\n6. The AI engine runs visual forensics, OCR/content validation,\n   template matching, and a custom ML classifier.\n7. The frontend polls the result endpoint until the status is `COMPLETE` or\n   `FAILED`.\n8. The user sees a trust score, verdict, confidence level, and explanation\n   flags.\n\n## Challenge Criteria Fit\n\n| Squad Hackathon Criterion | Weight | How VerifyNG Addresses It |\n| --- | ---: | --- |\n| AI Technical Depth | 30% | Four-layer verification engine: visual forensics, OCR/content validation, template/layout matching, and a custom NumPy ML classifier. |\n| Squad API Integration | 20% | Squad checkout is the gatekeeper for verification. The AI does not run until payment is confirmed. |\n| Problem Relevance and Domain Insight | 15% | Targets certificate/result fraud in Nigerian hiring and education workflows, a direct match for the guide's education verification domain. |\n| Solution Design and Scalability | 15% | Stateless FastAPI backend, Supabase persistence/storage, Vercel PWA, Hugging Face deployment, idempotent payment handling, timeout-protected AI jobs. |\n| Presentation and Demo | 15% | Live PWA and live API demonstrate upload, payment, callback, polling, and result display end to end. |\n| Impact Potential Bonus | 10% | Pay-per-check model can expand into employer subscriptions, university partnerships, NYSC screening, and API verification for HR platforms. |\n\n## Four Pillars\n\n| Pillar | VerifyNG Implementation |\n| --- | --- |\n| AI Automation | The system automatically analyzes visual tampering, extracted text, certificate structure, and ML authenticity signals after payment. |\n| Squad APIs | Squad payment initiation and callback/webhook flow sit in the critical path. No payment means no AI run. |\n| Use of Data | The trust score is built from OCR confidence, ELA anomaly score, template fields, content validation, metadata signals, and classifier probability. |\n| Financial Innovation | Certificate verification becomes a low-cost, payment-gated service that can support pay-per-use, subscriptions, and institutional bulk verification. |\n\n## AI Verification Engine\n\nVerifyNG is not a chatbot wrapper. The AI layer performs the verification work.\n\n### 1. Visual Forensics\n\n- Error Level Analysis checks compression inconsistencies that may indicate\n  edits.\n- Metadata checks detect missing or suspicious document metadata.\n- Visual consistency scoring flags sharpness and pixel-level differences.\n\n### 2. OCR and Content Validation\n\n- Tesseract OCR extracts text from uploaded scans or images.\n- The backend checks institution keywords, certificate language, candidate name\n  patterns, year signals, and exam/result terminology.\n- Low-quality scans still produce an interpretable outcome rather than silently\n  failing.\n\n### 3. Template and Layout Matching\n\n- The template layer checks whether the OCR output resembles expected WAEC or\n  certificate result structure.\n- It scores expected fields such as candidate name, examination number, year,\n  institution label, and grade-table evidence.\n\n### 4. Custom ML Classifier\n\n- A lightweight NumPy softmax classifier combines engineered features from the\n  previous layers.\n- Features include visual score, content score, template score, OCR confidence,\n  ELA anomaly score, metadata suspicion, missing field count, and word count.\n\nFor deeper AI detail, see [AI_TECHNICAL_DEPTH.md](AI_TECHNICAL_DEPTH.md).\n\n## Explainable Output\n\nEvery completed verification returns:\n\n- `trust_score`: 0-100 score\n- `verdict`: `LIKELY AUTHENTIC`, `REQUIRES MANUAL REVIEW`, `SUSPICIOUS`, or\n  `LIKELY FORGED`\n- `confidence`: `HIGH`, `MEDIUM`, or `LOW`\n- `flags`: human-readable reasons for the score\n- `layers_run`: AI layers that successfully executed\n\nThis matters for responsible AI. The system does not claim perfect truth. It\nshows evidence, flags uncertainty, and supports manual review when confidence is\nnot high enough.\n\n## Squad Integration\n\nSquad is central to the product, not a checkbox.\n\n### Payment Flow\n\n1. `POST /api/verify` creates a verification job.\n2. The backend calls Squad transaction initiation with:\n   - amount in kobo\n   - customer email\n   - transaction reference: `VNG-{verification_id}`\n   - callback URL\n   - verification metadata\n3. The frontend opens the returned `checkout_url`.\n4. Squad confirms payment through the callback/webhook path.\n5. The backend marks the payment confirmed and starts AI analysis.\n\n### Why It Is Meaningful\n\n- Squad controls access to the paid verification workflow.\n- The business model depends on Squad, because verification compute runs only\n  after payment.\n- The same architecture can support B2B employer subscriptions, bulk checks, and\n  virtual-account based institutional workflows.\n\n## API Contract\n\nThe frontend depends on this schema. Do not change these fields without\ncoordinating with the frontend.\n\n### `POST /api/verify`\n\nRequest:\n\n```http\nContent-Type: multipart/form-data\nfile=\u003ccertificate image or PDF\u003e\n```\n\nResponse:\n\n```json\n{\n  \"job_id\": \"uuid\",\n  \"checkout_url\": \"https://sandbox-pay.squadco.com/...\",\n  \"status\": \"PENDING_PAYMENT\",\n  \"poll_url\": \"https://olatunjitobi-verifyng-api.hf.space/api/result/{job_id}\"\n}\n```\n\n### `GET /api/result/{verification_id}`\n\nPending payment:\n\n```json\n{\n  \"verification_id\": \"uuid\",\n  \"status\": \"PENDING_PAYMENT\",\n  \"message\": \"Awaiting payment confirmation\"\n}\n```\n\nProcessing:\n\n```json\n{\n  \"verification_id\": \"uuid\",\n  \"status\": \"PROCESSING\",\n  \"message\": \"AI is analyzing your certificate...\"\n}\n```\n\nComplete:\n\n```json\n{\n  \"verification_id\": \"uuid\",\n  \"status\": \"COMPLETE\",\n  \"trust_score\": 87,\n  \"verdict\": \"LIKELY AUTHENTIC\",\n  \"flags\": [],\n  \"confidence\": \"HIGH\",\n  \"layers_run\": [\n    \"visual_forensics\",\n    \"content_validation\",\n    \"template_layout_matching\",\n    \"custom_ml_classifier\"\n  ],\n  \"report_url\": null\n}\n```\n\nFailed:\n\n```json\n{\n  \"verification_id\": \"uuid\",\n  \"status\": \"FAILED\",\n  \"message\": \"Verification failed. Please contact support.\",\n  \"refund_eligible\": true\n}\n```\n\n### `GET /api/payment/callback?reference=VNG-{verification_id}`\n\nHandles the browser callback after Squad sandbox payment and redirects the user\nto:\n\n```text\nhttps://verifyng-three.vercel.app/results/{verification_id}\n```\n\n### `POST /api/webhook/squad`\n\nHandles server-side Squad webhook payloads and queues verification analysis.\n\n### `POST /api/trigger/{verification_id}`\n\nManual testing endpoint. Requires:\n\n```http\nX-API-Key: \u003cAPI_KEY\u003e\n```\n\nThis endpoint is for integration testing only. The demo flow should use Squad\npayment/callback.\n\n## System Architecture\n\n```text\nUser\n  -\u003e VerifyNG PWA on Vercel\n  -\u003e FastAPI backend on Hugging Face Spaces\n  -\u003e Squad checkout\n  -\u003e Squad callback/webhook\n  -\u003e Supabase database + storage\n  -\u003e AI pipeline\n  -\u003e /api/result polling\n  -\u003e Result UI\n```\n\n### Production Design Choices\n\n- **Failure-first design:** failed downloads, missing files, timeouts, and bad\n  IDs resolve to controlled statuses instead of hanging forever.\n- **Stateless API:** FastAPI stores state in Supabase, so the app process can be\n  restarted without losing jobs.\n- **Idempotency:** payment records are keyed by Squad reference to avoid double\n  processing.\n- **Backpressure:** AI pipeline has a 90-second timeout to protect demo/runtime\n  stability.\n- **Security:** API keys and Squad keys are environment secrets, not frontend\n  code.\n- **Maintainability:** endpoint contracts are tested and documented.\n- **Observability:** backend logs show payment initiation, callback, file upload,\n  pipeline start, and pipeline completion/failure.\n\n## Tech Stack\n\n### Frontend\n\n- Next.js\n- TypeScript\n- Tailwind CSS\n- Axios\n- React Dropzone\n- React PDF\n- PWA manifest/icons\n- Vercel\n\n### Backend\n\n- FastAPI\n- Uvicorn\n- Supabase database\n- Supabase Storage\n- Hugging Face Spaces\n- Squad API\n- Tesseract OCR\n- OpenCV\n- Pillow\n- NumPy\n\n## Repository Structure\n\n```text\nverifyng/\n|-- backend/\n|   |-- app/\n|   |   |-- main.py\n|   |   |-- verifications.py\n|   |   |-- payments.py\n|   |   |-- result.py\n|   |   |-- webhook.py\n|   |   |-- pipeline.py\n|   |   |-- ocr.py\n|   |   |-- ela.py\n|   |   |-- content_validator.py\n|   |   |-- ai_depth.py\n|   |   |-- ml_model.py\n|   |   |-- database.py\n|   |-- requirements.txt\n|   |-- Dockerfile\n|-- web/\n|   |-- app/\n|   |-- components/\n|   |-- lib/\n|   |-- types/\n|   |-- public/\n|   |-- package.json\n|-- tests/\n|-- AI_TECHNICAL_DEPTH.md\n|-- README.md\n```\n\n## Backend Setup\n\n```powershell\npython -m venv venv\nvenv\\Scripts\\activate\npip install -r backend\\requirements.txt\nuvicorn backend.app.main:app --reload\n```\n\nRequired backend environment variables:\n\n```text\nSUPABASE_URL=\nSUPABASE_KEY=\nSUPABASE_SERVICE_ROLE_KEY=\nSUPABASE_STORAGE_BUCKET=certificates\nSQUAD_API_URL=https://sandbox-api-d.squadco.com\nSQUAD_API_KEY=\nWEBHOOK_URL=https://olatunjitobi-verifyng-api.hf.space/api/payment/callback\nFRONTEND_URL=https://verifyng-three.vercel.app\nAPI_KEY=\n```\n\n## Frontend Setup\n\n```bash\ncd web\nnpm install\nnpm run dev\n```\n\nRequired frontend environment variable:\n\n```text\nNEXT_PUBLIC_BACKEND_URL=https://olatunjitobi-verifyng-api.hf.space/api\n```\n\n## Testing\n\nRun backend tests:\n\n```powershell\nvenv\\Scripts\\python.exe -m unittest discover -s tests -v\n```\n\nCurrent backend coverage includes:\n\n- `/api/verify` response contract\n- Squad amount in kobo\n- Squad checkout response parsing\n- payment callback queueing\n- result endpoint states\n- manual trigger authorization\n- Supabase missing-row handling\n- storage signed URL handling\n- duplicate upload prevention\n- AI pipeline download failures\n- AI pipeline timeout handling\n- OCR and template matching\n- custom ML classifier behavior\n\nRun frontend checks:\n\n```bash\ncd web\nnpm install\nnpm run lint\nnpm run build\n```\n\n## Demo Script\n\nUse this flow for judges:\n\n1. Open the PWA.\n2. Upload a certificate/result image.\n3. Click verify.\n4. Show Squad checkout.\n5. Complete payment in Squad sandbox.\n6. Return to the results page.\n7. Explain the AI layers while the result is processing.\n8. Show the final trust score, verdict, confidence, flags, and layers run.\n9. Run a second upload with a suspicious/fake document to show score contrast.\n\nThe strongest demo moment is the contrast:\n\n```text\nClean certificate      -\u003e higher score -\u003e LIKELY AUTHENTIC / manual review\nTampered certificate   -\u003e lower score  -\u003e SUSPICIOUS / LIKELY FORGED\n```\n\n## Business Model\n\nVerifyNG can start as a pay-per-check verification service and grow into a B2B\nverification infrastructure product.\n\n| Segment | Offer | Revenue Path |\n| --- | --- | --- |\n| Individuals and small employers | Single verification | N500 per check |\n| SMEs and recruiters | Monthly verification bundle | Subscription |\n| Universities and exam bodies | Bulk verification dashboard/API | Institutional contract |\n| HR platforms | Verification API | Usage-based API pricing |\n\nEvery paid verification can flow through Squad.\n\n## Responsible AI and Privacy\n\n- VerifyNG gives a risk score, not an absolute legal declaration.\n- Low confidence or suspicious outputs should be manually reviewed.\n- Uploaded documents are used for the requested verification workflow.\n- Secrets stay in backend/Hugging Face/Supabase environment variables.\n- The system is designed to fail closed: if analysis cannot complete, the job is\n  marked `FAILED` and the frontend can show a refund/support path.\n\n## Team\n\n- **Olatunji Tobiloba** - AI pipeline, backend, Supabase, Hugging Face deployment\n- **Fisayo Obadina** - PWA frontend, upload flow, result experience\n- **Divine Aghulor** - Squad API integration, payment callback/webhook flow\n\n## Pitch Summary\n\nVerifyNG turns certificate verification into a fast, payment-gated AI workflow.\nSquad powers the transaction layer, FastAPI coordinates the verification job,\nSupabase stores the state and uploaded file, and the AI pipeline produces an\nexplainable trust score. The result is a live product that fits the Proof of\nLife challenge: it verifies documents where fraud is common, uses AI as the\ncore trust engine, integrates Squad as a necessary part of the workflow, and can\nscale into a real verification business.\n\nNo payment. No verification. Squad is the gatekeeper.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffisayo-dev%2Fverifyng","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffisayo-dev%2Fverifyng","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffisayo-dev%2Fverifyng/lists"}