A full-stack web application designed to manage, process, and track import and export customs procedures, package declarations, Single Central American Declaration (DUCA) workflows, tax/pricing calculations, and multi-stage audit logging.
This was part of a university project between the whole class where each classmate was an entity in the customs declaration simulation. The current state of the project is for demonstration and historic purpose only as it needs the other projects to communicate.
- Overview
- Key Features
- System Architecture
- Technologies Used
- Database Schema
- Prerequisites
- Setup & Installation
- Running the Application
- API Overview
- License
The Customs Agency System provides an end-to-end digital solution for handling international trade and customs declarations. It enables clients to submit export/import shipment registrations, declare cargo packages, monitor declaration status across lifecycle stages, compute estimated taxes and tariffs, and maintain comprehensive audit trails for customs authorities.
- 👤 User & Role Management: Sign up, log in, manage user profile accounts, and enforce role-based access control (
ADMINvsCLIENT). - 📦 Import & Export Operations: Register international shipments with tracking numbers, Bill of Lading (Blanding), country of origin and destination ISO codes, transport modes, and assigned customs offices.
- 📋 Package & Inventory Tracking: Declare detailed package contents per shipment (unit count, weight in kg, volume in m³, item values), handle cargo package updates, and preserve deleted package records with audit notes.
- 🔄 Customs Workflow Pipeline: Real-time status progression through 5 sequential stages:
Registration Received(-1)Pending Verification(0)Pending DUCA Submission(1)Pending Payment(2)Completed!(3)
- 💰 Tax & Pricing Calculation Engine: Dynamic calculation of tariff procedure fees, dimensional tariffs (weight/volume), per-package rates, and category-specific import taxes.
- 📜 Audit & System Logs: Dedicated logging modules for tracking transactional events across each process phase (
Registration,Verification,DUCA Submission,Payment) along with authorized IP role records. - 🌍 Master Data Management: Catalog for ISO country codes, regional customs offices, transport types, and tax categories.
The application is built using a modern decoupled client-server architecture:
graph TD
Client["Angular 20 Frontend<br/>(Port 4200)"]
API["Node.js + Express REST API Backend<br/>(Port 3333)"]
DB[("MariaDB Database<br/>(eu_customs_agency)")]
Client -->|HTTP / JSON REST API| API
API -->|SQL Queries via mariadb client| DB
- Frontend Tier: Single Page Application built with Angular 20 and Angular Material, featuring dynamic routing, reactive forms, state management services, and real-time status UI modules.
- Backend Tier: Express 5 REST API handling request routing, payload validation, CORS header policies, and database connection pooling.
- Database Tier: MariaDB relational database enforcing foreign key integrity across users, roles, shipments, packages, pricing models, and transactional audit logs.
- Framework: Angular 20.2
- UI Components: Angular Material 20.2 / Angular CDK
- Language: TypeScript 5.9
- Styling: SCSS
- Runtime: Node.js (v22.x recommended)
- Web Framework: Express.js (v5.1.0)
- Database Driver:
mariadb(v3.4.5) - Cross-Origin Handling:
cors(v2.8.5) - Development Tooling:
nodemon
- DBMS: MariaDB / MySQL
- Database Name:
eu_customs_agency
Key database tables configured in script.sql:
| Table Name | Description |
|---|---|
codigo_pais |
ISO country codes and country names |
pais_aduanas |
Customs offices associated with countries |
rol |
User roles (ADMIN, CLIENT) |
usuarios |
Registered system users (DUI, phone, email, credentials) |
empleados |
Employee records linked to user accounts |
exportaciones_importaciones |
Master shipment declarations (tracking number, DUCA ID, Blanding, origin/destination) |
status_imp_exp |
Workflow status codes (-1 to 3) |
paquetes |
Packages registered under specific shipment tracking numbers |
paquetes_eliminados |
Log of removed packages with explanatory comments |
precio_servicio |
Service fee parameters (per kg, per m³, per package, per procedure) |
impuestos |
Category-specific tax percentages |
transportes |
Transport modes (land, sea, air) |
logs_* |
Audit logs for registration, verification, DUCA submission, and payment phases |
roles_ip |
IP address registry for authorized customs entities |
Ensure you have the following installed on your development machine:
- Node.js:
v22.19.0or later - npm:
v10.9.3or later - MariaDB or MySQL: Running locally on port
3306
- Start your local MariaDB / MySQL server.
- Create the database
eu_customs_agency:CREATE DATABASE eu_customs_agency;
- Import the initial schema and seed data located at
./backend/src/script/script.sql:mysql -u root -p eu_customs_agency < backend/src/script/script.sql - Verify connection credentials in
./backend/src/config/database.js:- Host:
localhost - User:
root - Password:
""(or update with your local password) - Database:
eu_customs_agency
- Host:
- Navigate to the
backenddirectory:cd backend - Install dependencies:
npm install
- Navigate to the
frontenddirectory:cd frontend - Install dependencies:
npm install
From the backend folder:
npm startThe server will start on http://localhost:3333.
From the frontend folder:
npm startThe application will be accessible at http://localhost:4200.
The backend exposes RESTful endpoints organized by resource:
- User Accounts:
/users,/users/login,/users/signup - Shipment Services:
/services,/services/packages,/services/packages-deleted - Service Status:
/service_status - Master Data:
/countries,/aduanas,/roles,/fallback/taxes,/fallback/transports - Pricing & Rates:
/pricing - Audit Logs:
/logs/registration,/logs/verification,/logs/duca,/logs/payment,/logs/roles_ip
This project is open source and available under the MIT License.