noble-1 System Requirements Document

1. Introduction

The noble-1 project aims to provide a comprehensive platform that aggregates global trade data, customs records, and B2B enrichment APIs to display buyers' import details. The application will feature a robust dashboard for search and analytics, a continuous lead pipeline, and automated outreach with CRM integration. This document outlines the system requirements for noble-1, including functional and non-functional requirements, user personas, core user flows, and design specifications.

2. System Overview

noble-1 is designed to serve exporters by providing detailed insights into buyers' import activities. The system will ingest data from various sources, clean and enrich it, and present it through a SaaS dashboard. Key functionalities include buyer discovery, analytics, continuous lead monitoring, and outreach automation.

2a. Source Content Inventory

• Customs Data Providers: ImportYeti API, Trademo, Datamyne, Panjiva, Apify Trade Actors
• Contact Data Enrichment: Apollo.io API, Hunter.io, Dropcontact, Proxycurl
• Email/Messaging: SendGrid, Resend, WhatsApp Business API (via Twilio/Wati)

3. Functional Requirements as Story Points

• As an Exporter, I should be able to search for buyers by HS Code, Product Name, or Target Country.
• As an Exporter, I should be able to view Buyer Profile Cards with Company Name, Headquarter Address, Primary Phone, and Verified Email IDs.
• As an Exporter, I should be able to access Import Statistics such as Total Volume/Value, Average Unit Price Paid, and Shipment Frequency.
• As an Exporter, I should be able to receive real-time alerts when a target buyer receives a new shipment or places a new order.
• As an Exporter, I should be able to score buyers based on their activity in the last 30-60 days.
• As an Exporter, I should be able to automate cold email and WhatsApp campaigns with product catalogs and quotes.
• As an Exporter, I should be able to integrate leads into CRM systems like HubSpot and Salesforce or export them to CSV.

4. User Personas

• Exporter: A business entity looking to expand its market by identifying and reaching out to potential buyers globally.

5. Core User Flows

• Exporter searches for buyers using HS Code/Product Name -> Views Buyer Profile Cards -> Analyzes Import Statistics -> Sets up alerts for new shipments/orders -> Automates outreach campaigns -> Integrates leads into CRM.

6. Visuals Colors and Theme

• primary: #1E3A8A (Deep Blue)
• primary_light: #3B82F6 (Light Blue)
• secondary: #10B981 (Green)
• accent: #F59E0B (Amber)
• highlight: #EF4444 (Red)
• bg: #F9FAFB (Light Gray)
• surface: #FFFFFF (White)
• text: #111827 (Dark Gray)
• text_muted: #6B7280 (Muted Gray)
• border: #D1D5DB (Gray)

7. Signature Design Concept

The noble-1 landing page will feature an interactive "Trade Network Map" where users can explore global trade routes. As users hover over different regions, trade data will dynamically update, showing import/export statistics and buyer information. The map will be built using d3 for data visualization and motion/react for smooth transitions. Users can click on specific countries to drill down into detailed buyer profiles and trade analytics.

Landing Hero Motion Brief

The hero section will depict a dynamic world map with animated trade routes connecting various countries. As users interact with the map, trade data will animate into view, highlighting key statistics and buyer profiles. The animation will loop every 10 seconds, showcasing different trade routes and data points. The map will adjust responsively, ensuring a seamless experience across devices.

8. Interaction Model & Motion Direction

• Interaction Model: Parallax
• The landing page will feature layered depth via scroll, with decorative elements moving at different speeds to create a sense of depth. Real content will scroll naturally, enhancing the storytelling aspect of the platform.

9. Non-Functional Requirements

• The system must handle large volumes of trade data efficiently.
• The application must comply with GDPR and CAN-SPAM regulations.
• The platform should ensure high availability and reliability.

10. Tech Stack

• Frontend: Next.js (React), Tailwind CSS, Shadcn UI
• Backend: Node.js (TypeScript) or Python (FastAPI)
• Database: PostgreSQL (Primary Data), ClickHouse or Elasticsearch (Fast Querying)
• Customs Data Providers: ImportYeti API, Trademo, Datamyne, Panjiva, Apify Trade Actors
• Contact Data Enrichment: Apollo.io API, Hunter.io, Dropcontact, Proxycurl
• Email/Messaging: SendGrid, Resend, WhatsApp Business API (via Twilio/Wati)

11. Assumptions and Constraints

• The application assumes access to public customs data and compliance with international trade regulations.
• The system is constrained by the legal requirements for handling and processing trade data.

12. Glossary

• HS Code: Harmonized System Code used for classifying traded products.
• FOB: Free on Board, a term used in international trade to indicate who is responsible for goods during transit.
• CIF: Cost, Insurance, and Freight, a term indicating that the seller covers these costs to a specified destination.