Platform Overview
Architecture, technology stack, and design principles behind the customs compliance platform.
Design Principles
The platform is designed around three principles:
- Accuracy first -- duty calculations must match what a customs broker would file. Every rate type, every exemption, every CARICOM preference must be handled correctly.
- Broker-grade workflow -- the interface follows the actual customs declaration lifecycle: classify goods, estimate duties, prepare declaration, export for filing.
- Data integrity -- tariff data is versioned, timestamped, and traceable. The platform tracks when data was last refreshed and warns users if rates may be outdated.
Technology Stack
| Layer | Technology | Purpose |
|---|---|---|
| Frontend | Next.js 16 (React) with Turbopack | Server-rendered application with App Router |
| Styling | Tailwind CSS 4 | Utility-first CSS framework |
| Database | PostgreSQL 16 + pgvector | Relational data + vector similarity search |
| AI -- Classification | Azure OpenAI (GPT-4.1-mini) | Natural language to HS code classification |
| AI -- Search | Azure OpenAI (text-embedding-3-small) | Semantic embedding for tariff code search |
| AI -- Documents | Azure Document Intelligence | OCR and structured data extraction from invoices |
| Auth | NextAuth v5 (Auth.js) | Authentication with role-based access control |
| Hosting | Azure Container Apps | Serverless container hosting with auto-scale |
| CDN/Security | Cloudflare Pro | Edge caching, WAF, DDoS protection, SSL |
| Infrastructure | Terraform | Infrastructure as code for all Azure resources |
Application Architecture
The platform follows a standard Next.js App Router architecture:
src/
app/
login/ -- Sign-in page (credentials + OAuth)
signup/ -- Registration page (currently disabled)
signout/ -- Sign-out handler
portal/ -- User dashboard and activity overview
classify/ -- AI-assisted HS code classification
tariffs/ -- Tariff schedule browsing and search
declarations/ -- C82 declaration management
extract/ -- Document upload and data extraction
reports/ -- Analytics and reporting
billing/ -- Usage and billing management
clients/ -- Customs broker client management
settings/ -- User preferences and account settings
audit/ -- Audit log viewer
jobs/ -- Background job monitoring
pipeline/ -- Data pipeline management
proposal/ -- Classification proposal workflow
docs/ -- In-app documentation (Fumadocs)
api/ -- API route handlers
db/ -- Database schema, migrations, queries
lib/ -- Shared utilities, AI service clientsDatabase Schema
The database contains 25 tables organized around the core domain:
| Table Group | Key Tables | Purpose |
|---|---|---|
| Tariff data | tariff_commodities, tariff_embeddings | ~7,300 HS codes with 11 duty rate types + vector embeddings |
| Users | users, accounts, sessions, audit_log | Authentication, authorization, activity tracking |
| Declarations | declarations, declaration_items | C82 declaration preparation and line items |
| Documents | user_documents | Uploaded commercial documents (invoices, bills of lading) |
| Exchange rates | exchange_rates | Daily FX rates for duty calculation in TTD |
| Clients | clients | Customs broker client management |
| Reports | Generated at query time | Classification and duty estimation analytics |
Authentication and Roles
The platform implements 6 hierarchical roles:
| Role | Level | Capabilities |
|---|---|---|
| Guest | 0 | Public tariff lookup only |
| Client | 1 | Search, classify, view own declarations |
| Broker | 2 | Full declaration management, client management |
| Viewer | 3 | Read-only access to all data |
| Reviewer | 4 | Audit classifications, approve declarations |
| Admin | 5 | Full system access, user management |
Authentication uses scrypt password hashing, JWT tokens (8-hour expiry), and optional Cloudflare Turnstile CAPTCHA for bot protection.
AI Services
The platform integrates three Azure AI services across four deployed models:
Classification (GPT-4.1-mini)
Primary classification model. Takes a natural language goods description and returns the most likely HS code(s) with confidence scores. The model is prompted with T&T tariff context and returns structured JSON. GPT-4o-mini and GPT-4.1 are also deployed as fallback/evaluation models.
Semantic Search (text-embedding-3-small)
Pre-computed 1536-dimension embeddings for all ~7,300 tariff commodity descriptions. User queries are embedded at search time and matched via cosine similarity using pgvector. This powers the "search by description" feature.
Document Intelligence (prebuilt-layout)
Extracts structured data from uploaded commercial invoices and bills of lading using Azure's prebuilt document models. Extracted fields are mapped to declaration line items.
Deployed Models
| Model | Version | Capacity (TPM) | Purpose |
|---|---|---|---|
| gpt-4.1-mini | 2025-04-14 | 200 | Primary classification |
| gpt-4o-mini | 2024-07-18 | 100 | Fallback classification |
| gpt-4.1 | 2025-04-14 | 50 | Complex classification |
| text-embedding-3-small | v1 | 120 | Semantic search embeddings |
All AI service usage is governed by a spend guard: $5/day and $25/month hard limits, enforced at the application level.