Skip to content
HardeezahPublic

About

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

20 Commits

Folders and files

Repository files navigation

KodaTrade β€” Nigerian Trade Compliance Platform

AI-powered trade compliance for Nigerian importers & exporters. Scan a product, get instant regulatory verdicts with citations, generate documents, and stay compliant with NCS, NAFDAC, SON, CBN, AfCFTA rules.


🎯 What It Does

Feature Description
Import Compliance Check Scan product β†’ get HS code, NCS/NAFDAC/SON/CBN requirements, prohibition status, required permits
Export / AfCFTA Check Verify Rules of Origin, tariff savings, ROO eligibility for 54 African markets
Document Generation Auto-generate Form M, PAAR, NAFDAC applications, SON certificates, NEPC certificates
Trade Ledger Persistent history of all checks, audit trail, compliance scoring
Broker Communication AI-drafted emails to customs brokers with pre-filled Form M / PAAR details
Digital Trade Passport Profile completeness + compliance score + CAC verification β†’ shareable passport

πŸ— Architecture Overview

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                        USER INTERFACES                          β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚  Mobile (React Nativeβ”‚   Web Dashboard      β”‚   Admin / API     β”‚
β”‚  + Expo)             β”‚   (Next.js 14)       β”‚   (FastAPI)       β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
           β”‚                      β”‚                    β”‚
           β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                  β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                      FASTAPI BACKEND                            β”‚
β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
β”‚  β”‚ Auth    β”‚ β”‚ Complianceβ”‚ β”‚ AfCFTA   β”‚ β”‚ Docs     β”‚ β”‚ Comm   β”‚ β”‚
β”‚  β”‚ (Supabaseβ”‚ β”‚ (RAG)    β”‚ β”‚ (Tariff) β”‚ β”‚ (Gen)    β”‚ β”‚ (Email)β”‚ β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”˜
           β”‚
           β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                      DATA LAYER                                 β”‚
β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”‚
β”‚  β”‚ Supabase         β”‚ β”‚ Upstash Redis    β”‚ β”‚ pgvector       β”‚  β”‚
β”‚  β”‚ (PostgreSQL +    β”‚ β”‚ (AfCFTA cache)   β”‚ β”‚ (1536-dim β†’     β”‚  β”‚
β”‚  β”‚  pgvector)       β”‚ β”‚                  β”‚ β”‚  384-dim local)β”‚  β”‚
β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

🧠 RAG Pipeline (Core Intelligence)

User Query ("frozen chicken import")
         β”‚
         β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚  LOCAL EMBEDDINGS (fastembed: BAAI/bge-small-en-v1.5, 384d)  β”‚
β”‚  Query β†’ vector β†’ pgvector cosine search (IVFFlat, lists=10) β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                           β”‚
                           β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚  RETRIEVER                                                   β”‚
β”‚  match_document_chunks(query_embedding, match_count=8,       β”‚
β”‚                        min_similarity=0.30, filter_agency)   β”‚
β”‚  β†’ top 8 regulatory chunks from NCS, NAFDAC, SON, CBN, etc.  β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                           β”‚
                           β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚  RERANKER (keyword boost)                                    β”‚
β”‚  +0.05 similarity per query-term match in chunk content      β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                           β”‚
                           β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚  CONTEXT FORMATTER                                           β”‚
β”‚  - Max 6000 chars total                                      β”‚
β”‚  - Citations extracted (source, agency, excerpt, score)      β”‚
β”‚  - Truncation warning if context exceeds limit               β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                           β”‚
                           β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚  GROQ LLM (Llama 3.3 70B Versatile, temp=0.2, JSON mode)     β”‚
β”‚  System prompt: Nigerian trade compliance expert              β”‚
β”‚  User prompt: product + context + strict JSON schema          β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                           β”‚
                           β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚  CitedComplianceVerdict (Pydantic)                           β”‚
β”‚  status, HS code, summary, risks, citations, AfCFTA data     β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Fallback: If RAG fails β†’ LLM-only mode with "retrieval_used": false, lower confidence (0.40 vs 0.75).


πŸ“¦ Project Structure

koda-trade/
β”œβ”€β”€ .github/
β”‚   └── workflows/ci.yml          # CI: backend tests, frontend type-check, web build
β”œβ”€β”€ backend/                      # FastAPI Backend (Python 3.11)
β”‚   β”œβ”€β”€ app/
β”‚   β”‚   β”œβ”€β”€ api/v1/endpoints/     # REST endpoints
β”‚   β”‚   β”‚   β”œβ”€β”€ auth.py           # Register + Login (Supabase)
β”‚   β”‚   β”‚   β”œβ”€β”€ compliance.py     # POST /check, /analyze_image, /generate_document
β”‚   β”‚   β”‚   β”œβ”€β”€ afcfta.py         # POST /afcfta/check (tariff + ROO + cache)
β”‚   β”‚   β”‚   β”œβ”€β”€ documents.py      # Document CRUD
β”‚   β”‚   β”‚   β”œβ”€β”€ communication.py  # POST /draft (broker email)
β”‚   β”‚   β”‚   β”œβ”€β”€ orchestration.py  # Scan β†’ HS β†’ Compliance β†’ Ledger
β”‚   β”‚   β”‚   β”œβ”€β”€ profile.py        # User profile + CAC
β”‚   β”‚   β”‚   └── ledger.py         # Trade history
β”‚   β”‚   β”œβ”€β”€ core/
β”‚   β”‚   β”‚   └── config.py         # Pydantic Settings (env)
β”‚   β”‚   β”œβ”€β”€ domain/models/        # Pydantic models
β”‚   β”‚   β”‚   β”œβ”€β”€ compliance.py     # TextComplianceRequest, CitedComplianceVerdict
β”‚   β”‚   β”‚   β”œβ”€β”€ rag.py            # RetrievedChunk, Citation
β”‚   β”‚   β”‚   β”œβ”€β”€ vision.py         # ProductAttributes, HSCodeResult
β”‚   β”‚   β”‚   └── afcfta.py         # AfCFTACheckRequest/Response
β”‚   β”‚   β”œβ”€β”€ infrastructure/
β”‚   β”‚   β”‚   β”œβ”€β”€ rag/              # RAG Pipeline
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ retriever.py          # pgvector search + retries
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ reranker.py           # keyword boost + citations
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ compliance_chain.py   # Groq LLM + prompt + parse
β”‚   β”‚   β”‚   β”‚   └── document_ingestion.py # chunk β†’ embed β†’ upsert
β”‚   β”‚   β”‚   β”œβ”€β”€ ai/               # AI Services
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ intelligence.py       # analyze_compliance (RAG + fallback)
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ compliance_utils.py   # confidence scoring
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ hs_classifier.py      # image β†’ attributes β†’ HS code
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ vision_pipeline.py    # image β†’ attributes (Llama 4 Scout)
β”‚   β”‚   β”‚   β”‚   └── communication.py      # broker email drafts
β”‚   β”‚   β”‚   β”œβ”€β”€ db/               # Supabase repositories
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ supabase.py   # client singleton
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ afcfta_queries.py     # tariff + ROO SQL
β”‚   β”‚   β”‚   β”‚   └── hs_code_repository.py # HS code vector search
β”‚   β”‚   β”‚   └── redis_client.py   # Upstash REST client
β”‚   β”‚   β”œβ”€β”€ middleware/           # rate_limit, security_headers, request_logging
β”‚   β”‚   └── main.py               # FastAPI app + CORS + middleware
β”‚   β”œβ”€β”€ assets/regulations/       # Source .txt files for ingestion
β”‚   β”‚   β”œβ”€β”€ ncs_2026_prohibition_list.txt
β”‚   β”‚   β”œβ”€β”€ afcfta_rules_of_origin.txt
β”‚   β”‚   β”œβ”€β”€ afcfta_nigeria_tariff_offer.txt
β”‚   β”‚   β”œβ”€β”€ cbn_trade_finance_circular.txt
β”‚   β”‚   β”œβ”€β”€ nafdac_import_guidelines.txt
β”‚   β”‚   └── son_mancap_schedule.txt
β”‚   β”œβ”€β”€ migrations/               # Supabase SQL (run in SQL Editor)
β”‚   β”œβ”€β”€ tests/                    # 55 pytest tests (RAG, endpoints, auth)
β”‚   β”œβ”€β”€ requirements.txt
β”‚   └── pyproject.toml
β”œβ”€β”€ frontend/                     # React Native + Expo (Mobile)
β”‚   β”œβ”€β”€ src/
β”‚   β”‚   β”œβ”€β”€ presentation/
β”‚   β”‚   β”‚   β”œβ”€β”€ screens/          # All UI screens
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ compliance/   # HSResult, ComplianceResult, ComplianceSearch
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ afcfta/       # AfCFTAReport
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ passport/     # ExportScore
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ scanner/      # CameraScan
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ dashboard/    # Dashboard, ExportScore
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ ledger/       # Ledger
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ profile/      # Profile, EditProfile
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ auth/         # Login, Signup
β”‚   β”‚   β”‚   β”‚   └── shared/       # Communication
β”‚   β”‚   β”‚   β”œβ”€β”€ components/       # Reusable UI (Button, ScreenLayout, Typography)
β”‚   β”‚   β”‚   └── hooks/            # Custom hooks
β”‚   β”‚   β”œβ”€β”€ context/              # TradeModeContext (import/export toggle)
β”‚   β”‚   β”œβ”€β”€ infrastructure/       # Supabase client, API client
β”‚   β”‚   └── utils/                # score.ts (centralized compliance score)
β”‚   β”œβ”€β”€ app.json                  # Expo config
β”‚   β”œβ”€β”€ tsconfig.json
β”‚   └── package.json
β”œβ”€β”€ web/                          # Next.js 14 (Web Dashboard)
β”‚   β”œβ”€β”€ src/
β”‚   β”‚   β”œβ”€β”€ app/                  # App Router pages
β”‚   β”‚   β”‚   β”œβ”€β”€ dashboard/        # Compliance, AfCFTA, Documents, Ledger, Profile
β”‚   β”‚   β”‚   β”œβ”€β”€ login/, signup/   # Auth pages
β”‚   β”‚   β”œβ”€β”€ context/              # AuthContext, TradeModeContext
β”‚   β”‚   └── lib/                  # API client, Supabase client
β”‚   β”œβ”€β”€ package.json
β”‚   └── tsconfig.json
β”œβ”€β”€ docker-compose.yml            # Local stack: db, redis, backend, frontend, web
β”œβ”€β”€ run.sh                        # Unified dev runner (see below)
β”œβ”€β”€ .gitignore
└── README.md

πŸ”§ Technology Stack

Layer Technology Version Purpose
Backend API FastAPI 0.110+ Async REST, OpenAPI docs
Auth Supabase Auth - JWT, email/password, OAuth ready
Database Supabase (PostgreSQL 15 + pgvector) - Relational + vector search
Vector Search pgvector (IVFFlat, cosine) - Semantic retrieval
Embeddings fastembed (BAAI/bge-small-en-v1.5) 0.8+ Local, 384-dim, no API key
LLM Groq (Llama 3.3 70B Versatile) - Fast inference, JSON mode
Vision Groq (Llama 4 Scout 17B) - Image β†’ product attributes
Cache Upstash Redis (REST) - AfCFTA tariff/ROO cache (24h TTL)
PDF PyMuPDF (fitz) - Regulation PDF text extraction
Mobile React Native + Expo 50 / 49 iOS/Android/Web
Web Next.js 14 (App Router) 14.2+ Dashboard, SSR
Styling NativeWind (Tailwind for RN) 4+ Utility-first styling
CI/CD GitHub Actions - Tests, type-check, build
Container Docker / docker-compose - Local + prod parity

πŸš€ Quick Start

Prerequisites

  • Docker & Docker Compose (for full stack)
  • OR Python 3.11+, Node 20+, pnpm/npm
  • Supabase project (free tier works)
  • Groq API key (free tier works)
  • Upstash Redis (free tier works)

1. Clone & Configure

git clone <repo-url>
cd koda-trade

# Copy env templates
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env   # if exists
cp web/.env.example web/.env             # if exists

Edit backend/.env with your keys:

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
GROQ_API_KEY=gsk_xxxxxxxxxxxxx
UPSTASH_REDIS_REST_URL=https://xxx.upstash.io
UPSTASH_REDIS_REST_TOKEN=xxx
OPENAI_API_KEY=sk-xxx  # optional, not used if fastembed works
CORS_ORIGINS=http://localhost:3000,http://localhost:8081,exp://localhost:8081

2. Run Database Migrations

Open Supabase Dashboard β†’ SQL Editor β†’ New Query and run each file in backend/migrations/ in order:

  1. 20250725_fix_vector_indexes.sql (creates document_chunks, hs_codes, RPC functions)
  2. 20260725_create_all_rag_tables.sql (creates AfCFTA tables + RLS)

3. Start Everything (Docker)

# From root
docker compose up --build
Service URL
Backend API http://localhost:8000/docs
Frontend (Expo) http://localhost:8081
Web Dashboard http://localhost:3000
Supabase (local) http://localhost:5432

4. Ingest Regulatory Documents

# One-time setup: embeds all 6 regulation files into pgvector
docker compose exec backend python -c "
from app.infrastructure.rag.document_ingestion import ingest_all_from_assets
import asyncio
print(asyncio.run(ingest_all_from_assets()))
"
# Expected: {'afcfta_rules_of_origin': 22, 'afcfta_nigeria_tariff_offer': 15, ...}

5. Run Without Docker (Alternative)

# Terminal 1: Backend
cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

# Terminal 2: Frontend (Mobile)
cd frontend
npm install --legacy-peer-deps
npx expo start --lan

# Terminal 3: Web Dashboard
cd web
npm install --legacy-peer-deps
npm run dev

πŸƒ Unified Runner (run.sh)

# From project root
chmod +x run.sh

./run.sh backend      # Start FastAPI (uvicorn)
./run.sh frontend     # Start Expo (npx expo start --lan)
./run.sh web          # Start Next.js (npm run dev)
./run.sh mobile       # Expo LAN mode for phone testing
./run.sh dev          # Backend + Frontend together
./run.sh all          # Full docker compose stack
./run.sh test         # Run all tests (backend + frontend TS + web build)
./run.sh ingest       # Ingest regulation docs into Supabase
./run.sh db           # Print all migration SQL (copy-paste to Supabase)
./run.sh help         # Show usage

πŸ§ͺ Testing

# Backend (55 tests)
cd backend
source venv/bin/activate
python -m pytest tests/ -v --tb=short

# Frontend type-check
cd frontend
npx tsc --noEmit

# Web build check
cd web
npm run build

All must pass before PR.


πŸ“¦ Regulatory Data Sources (Ingested)

File Source Updated Chunks
ncs_2026_prohibition_list.txt Nigeria Customs Service (customs.gov.ng) Apr 2026 18
afcfta_rules_of_origin.txt AfCFTA Annex 2 + Appendix IV Jan 2024 22
afcfta_nigeria_tariff_offer.txt FMITI PSTCs + ECOWAS CET Apr 2025 15
cbn_trade_finance_circular.txt CBN FX Manual 4th Ed + Circulars Jun 2026 17
nafdac_import_guidelines.txt NAFDAC Registration Guidelines Jan 2025 24
son_mancap_schedule.txt SON Act 14/2015 + SONCAP/MANCAP 2025 17

Total: 113 chunks, ~90KB text β€” all embedded locally via fastembed.


πŸ” Environment Variables

Backend (backend/.env)

Variable Required Description
SUPABASE_URL βœ… https://xxx.supabase.co
SUPABASE_KEY βœ… Anon key (client)
SUPABASE_SERVICE_ROLE_KEY βœ… Service role (admin)
GROQ_API_KEY βœ… gsk_... from console.groq.com
UPSTASH_REDIS_REST_URL βœ… https://xxx.upstash.io
UPSTASH_REDIS_REST_TOKEN βœ… Upstash REST token
CORS_ORIGINS βœ… Comma-separated origins
OPENAI_API_KEY ❌ Not used (fastembed local)
GROQ_MODEL ❌ Default: llama-3.3-70b-versatile
COMPLIANCE_TEMPERATURE ❌ Default: 0.2

Frontend (frontend/.env)

EXPO_PUBLIC_API_URL=http://localhost:8000
EXPO_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
EXPO_PUBLIC_SUPABASE_ANON_KEY=xxx

Web (web/.env.local)

NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=xxx

πŸ—ƒ Database Schema (Key Tables)

-- RAG Knowledge Base
document_chunks (id, source, agency, doc_date, url, chunk_index, content, embedding vector(384))

-- HS Code Search
hs_codes (id, chapter, heading, code, description, notes, embedding vector(384))

-- AfCFTA
afcfta_tariff_schedule (hs_code, destination_country, base_rate, category_a_rate, phase_out_year)
afcfta_roo_requirements (hs_code_prefix, roo_type, roo_description, value_added_threshold)
afcfta_checks (user_id, product_name, hs_code, destination_country, eligible, tariff_saving, roo_eligible, explanation)

-- User Data
profiles (id, user_id, business_name, cac_number, trade_type, ...)
ledger (id, profile_id, product_name, hs_code, status, quantity, value_usd, direction, created_at)

RPC Functions:

  • match_document_chunks(query_embedding, match_count, filter_agency) β†’ cosine similarity
  • match_hs_codes(query_embedding, match_count) β†’ cosine similarity

🀝 Contributing

Branching Strategy

  • main β€” production-ready, protected
  • develop β€” integration branch
  • feature/* β€” new features
  • fix/* β€” bug fixes
  • docs/* β€” documentation only

Commit Convention (Conventional Commits)

feat: add AfCFTA tariff schedule ingestion
fix: handle empty retrieval in compliance_chain
docs: update README with Docker instructions
refactor: extract score calculation to utils/score.ts
test: add reranker truncation warning test
chore: bump fastembed to 0.8.0

Pull Request Checklist

  • All tests pass (./run.sh test)
  • TypeScript clean (npx tsc --noEmit in frontend)
  • Lint clean (npm run lint if configured)
  • No hardcoded secrets
  • Migration SQL included if schema changes
  • Updated relevant docs (README, CHANGELOG)

Code Style

  • Python: Ruff (line-length 100, target py311)
  • TypeScript: ESLint + Prettier (via Expo defaults)
  • SQL: 2-space indent, UPPER CASE keywords

πŸ› Troubleshooting

Issue Fix
document_chunks table missing Run migrations in Supabase SQL Editor
json.loads(cached) NameError in afcfta.py Add import json at top of file
Groq 429 rate limit Wait / check quota / add fallback
pgvector dimension mismatch Ensure migration ran (384-dim for fastembed)
Expo "Metro bundler ECONNREFUSED" npx expo start --clear --lan
Supabase RLS blocking inserts Check service_role key used for admin ops
fastembed model download fails pip install --upgrade fastembed + internet

πŸ“„ License

MIT License β€” see LICENSE for details.


πŸ™ Acknowledgments

  • Nigeria Customs Service β€” prohibition lists, CET tariffs
  • AfCFTA Secretariat β€” Rules of Origin, tariff schedules
  • CBN β€” Form M/NXP, FX Manual 4th Edition
  • NAFDAC β€” Registration guidelines, tariffs
  • SON β€” MANCAP/SONCAP certification
  • Groq β€” Ultra-fast LLM inference
  • fastembed β€” Local embeddings without API keys
  • Supabase β€” Postgres + pgvector + Auth + Realtime
  • Upstash β€” Serverless Redis

Built for Nigerian traders, by people who understand the pain of Form M. πŸ‡³πŸ‡¬

About

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages