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.
| 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 |
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β 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)β β
β ββββββββββββββββββββ ββββββββββββββββββββ ββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
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).
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
| 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) |
| 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 |
- 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)
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 existsEdit 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:8081Open Supabase Dashboard β SQL Editor β New Query and run each file in backend/migrations/ in order:
20250725_fix_vector_indexes.sql(createsdocument_chunks,hs_codes, RPC functions)20260725_create_all_rag_tables.sql(creates AfCFTA tables + RLS)
# 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 |
# 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, ...}# 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# 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# 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 buildAll must pass before PR.
| 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.
| 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 |
EXPO_PUBLIC_API_URL=http://localhost:8000
EXPO_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
EXPO_PUBLIC_SUPABASE_ANON_KEY=xxxNEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=xxx-- 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 similaritymatch_hs_codes(query_embedding, match_count)β cosine similarity
mainβ production-ready, protecteddevelopβ integration branchfeature/*β new featuresfix/*β bug fixesdocs/*β documentation only
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
- All tests pass (
./run.sh test) - TypeScript clean (
npx tsc --noEmitin frontend) - Lint clean (
npm run lintif configured) - No hardcoded secrets
- Migration SQL included if schema changes
- Updated relevant docs (README, CHANGELOG)
- Python: Ruff (line-length 100, target py311)
- TypeScript: ESLint + Prettier (via Expo defaults)
- SQL: 2-space indent, UPPER CASE keywords
| 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 |
MIT License β see LICENSE for details.
- 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. π³π¬