JAHEZ TRADE CO | Bilingual Trade Operations Platform

Project Overview

JAHEZ TRADE CO is a bilingual digital platform for managing trade services, client requests, consulting, bookings, shipments, invoices, subscriptions, and business content. It gives clients a clear place to request services and follow progress while giving administrators one operational workspace for managing the complete service journey.

The platform is available in English and Arabic. Its interface, navigation, content, metadata, and public pages adapt to the selected language. This was an important product requirement because the platform serves an audience that expects both languages to feel complete rather than translated as an afterthought.

I designed and developed the application as a full stack project. My work covered product architecture, database design, authentication, public experiences, client dashboards, administrative tools, AI integration, external services, transactional workflows, notifications, document generation, localization, and search visibility.

The Problem

Trade and logistics services often depend on disconnected communication. A client may submit a request through one channel, receive pricing through another, discuss delivery over the phone, and request documents through email. This creates unnecessary work for the business and makes it difficult for the client to understand what is happening.

JAHEZ was created to organize these interactions around a consistent digital process.

The platform needed to solve several connected problems:

1. Clients needed a simple way to discover services and submit detailed requests.

2. Administrators needed one place to manage products, requests, bookings, consulting, shipments, invoices, and communication.

3. Shipment progress needed to combine carrier information with updates entered by the business.

4. Important documents and notifications needed to reach clients through practical channels such as email and WhatsApp.

5. Public content needed to support English and Arabic while remaining accessible to search engines.

6. AI needed to assist administrative work without becoming a dependency for essential operations.

My Responsibilities

As the developer of the platform, I was responsible for the complete implementation.

1. I translated the business requirements into public, client, and administrative workflows.

2. I designed the PostgreSQL data model and managed it through Prisma migrations.

3. I built the application with Next.js 16, React 19, TypeScript, and Tailwind CSS.

4. I implemented authentication and authorization with Clerk.

5. I created the English and Arabic experience with localized routing and right to left presentation.

6. I integrated Groq AI, 17TRACK, email, WhatsApp, PDF generation, QR codes, and barcodes.

7. I built operational dashboards for requests, bookings, shipments, invoices, content, users, employees, integrations, notifications, and audit records.

Technology Stack

Application

Next.js 16 provides the application framework and App Router. React 19 powers the user interface, while TypeScript provides consistent types across pages, actions, and data models. Tailwind CSS supports a responsive interface across the public site and both dashboards.

Data

PostgreSQL stores operational and content data. Prisma provides the schema, migrations, relationships, transactions, indexes, and typed database access used by the application.

Identity and Access

Clerk manages authentication and account sessions. Application records connect authenticated identities with local client and administrator data. Protected actions verify the active user and check the required role before accessing sensitive operations.

Artificial Intelligence

Groq provides fast access to the Llama 3.3 70B model. The platform uses it for administrative pricing suggestions and client support responses. Both features are designed so that the normal workflow remains available when the AI service cannot respond.

External Communication and Logistics

The application integrates email and WhatsApp for client communication. 17TRACK provides carrier tracking data. PDFKit generates invoice documents, while QR and barcode libraries create machine readable references for operational documents and shipments.

Platform Architecture

JAHEZ uses a single Next.js application with clear feature boundaries. This architecture keeps deployment and maintenance practical while allowing public pages, client tools, administrative tools, server actions, route handlers, integrations, and database access to share one typed codebase.

The application is organized around three primary experiences.

Public Experience

Visitors can explore products, consulting services, company information, articles, and service pages. They can also submit product requests, consulting requests, and booking requests. Public shipment pages allow a client to follow delivery progress using a tracking code.

Client Experience

Authenticated clients can manage their account, review available services, access support, follow notifications, and interact with the workflows available through their subscription plan.

Administrative Experience

Administrators manage the operational side of the business. The dashboard provides dedicated areas for requests, bookings, consulting, products, shipments, invoices, users, employees, content, notifications, integrations, support, subscriptions, analytics, and audit activity.

Product Request Management

The product request workflow turns an informal inquiry into structured operational data. Clients and guests can provide the information required by the business, including contact details, product requirements, quantity, destination, and supporting context.

Administrators can review each request, update its status, record pricing information, communicate with the client, and preserve the request history. This creates a consistent process without forcing every visitor to create an account before making contact.

The same guest friendly approach appears in other parts of the platform. Booking requests, consulting requests, and shipment records can be associated with guest client information when an authenticated account is not available.

AI Assisted Pricing

The administrative request workflow includes an AI pricing assistant powered by Groq. It uses the details of a product request to prepare a suggested estimate with a confidence value, reasoning, and useful notes.

The suggestion is presented to an administrator for review. It is never treated as an automatic commercial decision. The administrator remains responsible for verifying the information and deciding how it should be used.

When an accepted suggestion is stored, the platform records both the AI suggestion and the related request update inside a database transaction. This keeps the generated recommendation connected to the operational record it was created for.

If the AI service is unavailable, administrators can continue the pricing process manually. This approach makes AI a productivity tool rather than a critical dependency.

Client Support Assistant

The client dashboard includes a support conversation experience. Recent messages provide context for a Groq generated response, allowing the assistant to answer general questions about platform services and guide the client through common tasks.

The support system also preserves a human path. If the AI request fails, the client message remains available so an administrator can respond. This design keeps the conversation reliable and avoids losing a support request because an external service is temporarily unavailable.

Booking and Consultation Workflows

The booking system allows guests and authenticated clients to request appointments through the public platform. Administrators define availability slots, review requests, propose schedules, add meeting information, and manage status changes.

The scheduling logic uses transactional database access and row locking when a slot is reserved. This protects the workflow from two people claiming the same availability at nearly the same moment.

When an administrator schedules, changes, or cancels a booking, the platform can notify the client through email and WhatsApp. Meeting providers include Zoom, Google Meet, Microsoft Teams, WhatsApp, and custom meeting links supplied by the administrator.

Consulting is modeled as its own business area. Administrators can publish consulting services with localized information and media. Clients can then submit requests connected to a specific service, giving the business a structured way to manage advisory work alongside its other operations.

Shipment Management and Public Tracking

Shipment management is one of the most complete operational areas in JAHEZ. Administrators can create shipment records, associate them with registered users or guest clients, attach images, generate public tracking references, and maintain a chronological event history.

17TRACK integration supports several parts of the tracking lifecycle:

1. Registering a carrier tracking number.

2. Requesting the latest carrier information.

3. Mapping external carrier states into application shipment states.

4. Receiving signed webhook updates from 17TRACK.

5. Reconciling active shipments through a protected scheduled synchronization route.

The tracking design is easier to understand as two carrier update paths and one human update path converging on a stored timeline.

Webhook events are checked for authenticity and compared with existing event data before new information is stored. Scheduled synchronization provides a second path for keeping active shipments current. Administrators can also add manual events when a delivery requires business specific context that is not available from the carrier.

Clients open a public tracking page with their tracking code and see the latest shipment state and timeline without needing access to the administrative dashboard.

Shipping Cost Estimation

JAHEZ includes a configurable shipping estimator for early cost guidance. The calculation can consider information such as weight, volume, quantity, unit rates, and the selected shipping method.

Administrators manage the rates and review submitted estimates. Keeping these rules in operational data allows the business to adjust pricing inputs without rebuilding the application whenever shipping conditions change.

Invoice Generation and Delivery

The invoice system converts operational records into professional client documents. Administrators can create invoices with line items, quantities, prices, totals, payment information, status, and references to the relevant client or shipment.

PDFKit generates downloadable invoice documents with support for English and Arabic content. QR codes and barcodes make important references easier to scan and verify. Completed invoices can be delivered by email or WhatsApp, allowing the business to use the communication channel that best fits the client.

This feature is more than a document template. It connects stored invoice data, generated files, delivery actions, and administrative status management in one workflow.

Notifications and Communication

The notification system gives clients and administrators a persistent record of important activity. Header indicators periodically check for unread items, while dedicated views support filtering, pagination, and status management.

Administrators can send a notification to one client or broadcast a message to a wider audience. Email and WhatsApp services extend selected events beyond the application interface. These channels are also used by booking, shipment, request, and invoice workflows.

Delivery failures are handled without removing the related database record. This separation allows administrators to review what happened and continue the business process even if an external communication provider is temporarily unavailable.

Subscriptions and Access Control

The application includes subscription plans and feature access rules. Plan records define which capabilities and limits are available to a client. Subscription and payment attempt records keep the local application state connected to billing activity received through Clerk webhooks.

This design allows the platform to present different service levels while enforcing important restrictions on the server. Access checks are not limited to hiding interface elements. Protected operations verify authentication, role, and plan eligibility before completing an action.

Content and Search Visibility

JAHEZ contains a bilingual publishing system for products, consulting services, blog posts, categories, and related public content. Administrators manage English and Arabic titles, descriptions, media, publication state, and search metadata.

The blog supports comments, replies, reactions, view counts, related articles, social sharing, image media, video media, moderation, and advertising placements. These features turn the content area into an active communication channel rather than a static news page.

Search visibility is supported through localized metadata, canonical information, structured data components, a generated sitemap, and robots configuration. Public routes expose the appropriate language version of products, services, articles, and organizational information.

Administration and Analytics

The administrative dashboard brings operational tools into one consistent interface. Administrators can review workload, request states, booking activity, shipment progress, client records, subscription information, and financial indicators.

Charts and summary cards help convert database activity into an understandable business view. Detailed screens remain available for the underlying records, so high level indicators connect directly to the workflows that produced them.

Employee profiles can also be managed through the dashboard and presented on public team pages. This keeps organizational information synchronized with the same content system used by the rest of the site.

Audit Activity

Important administrative operations create audit records containing the administrator, action, entity, entity reference, change information, and creation time. A dedicated dashboard allows authorized administrators to search and review this history.

The system also includes retention controls that allow selected entries to be removed or records older than a chosen date to be purged. The audit feature therefore serves as an operational activity record with administrative lifecycle management.

Data Integrity and Reliability

Several implementation choices protect important workflows.

1. Prisma transactions keep related database changes together when an operation updates multiple records.

2. Booking reservations use row locking to reduce the risk of conflicting slot assignments.

3. Shipment webhook signatures are verified before external tracking updates are accepted.

4. Tracking events are checked for duplication before they are added to the shipment timeline.

5. Protected actions verify identity and role on the server.

6. Input schemas validate data used by many administrative and public forms.

7. External AI and communication failures do not remove the underlying client or operational record.

Engineering Challenges

Combining Automated and Manual Tracking

Carrier data does not always describe every business event that matters to a client. JAHEZ solves this by maintaining one shipment timeline that can receive verified 17TRACK updates and manual administrative updates. Source information and timestamps preserve the context of each event.

Protecting Booking Availability

A visual availability calendar is not enough to prevent conflicting reservations. The final slot check occurs within a database transaction, where the selected record is locked before the booking is confirmed. This moves the important protection to the server and database rather than relying on the browser state.

Supporting Registered and Guest Clients

Requiring an account too early can prevent a potential client from making a request. JAHEZ supports guest submissions while still allowing authenticated clients to receive a richer dashboard experience. The data model and administrative screens handle both identities consistently.

Introducing AI Responsibly

Pricing and customer communication affect real business relationships. AI output is therefore treated as assistance, not authority. Administrators review pricing suggestions, support messages remain available for human response, and manual workflows continue to work when Groq is unavailable.

Delivering a Complete Arabic Experience

Localization affects much more than translated labels. Routes, layout direction, content fields, validation messages, metadata, structured data, generated invoices, and public navigation all need to agree on the active language. Designing localization as an application concern made the English and Arabic experiences consistent across public and protected areas.

Outcome

JAHEZ brings a broad set of trade operations into one coherent application. A visitor can discover a service and submit a request. An administrator can review that request, prepare pricing, schedule a consultation, manage shipment progress, issue an invoice, and communicate with the client without moving between unrelated systems.

The result demonstrates practical full stack engineering across application architecture, relational data modeling, authentication, internationalization, artificial intelligence, logistics integration, document generation, external communication, operational dashboards, and search visibility.

Lessons Learned

Operational software should reflect the complete journey

A polished request form provides limited value if pricing, scheduling, shipping, documentation, and communication remain disconnected. Modeling the complete client journey created stronger workflows and a more useful administrative system.

External integrations need a reliable local record

Carrier, AI, email, and WhatsApp services can fail independently. The application remains understandable because requests, messages, events, invoices, and delivery attempts are stored locally and can be reviewed by an administrator.

AI is most useful when humans retain control

The pricing assistant saves preparation work while leaving the final decision with an administrator. The support assistant provides immediate guidance while keeping human follow up available. These boundaries make the AI features useful without giving them inappropriate authority.

Localization belongs in the architecture

English and Arabic support influenced the data model, page structure, navigation, documents, and search metadata. Addressing these concerns from the beginning was more effective than adding translation after the operational workflows were complete.

Future Opportunities

The existing architecture provides a foundation for additional improvements.

1. Direct integrations with more shipping carriers could provide deeper delivery information.

2. Accounting integrations could connect invoices and payment records with external finance systems.

3. More advanced reporting could compare request categories, shipment performance, revenue, and client activity over time.

4. A dedicated mobile experience could make operational updates faster for staff working away from a desktop.

5. Additional AI tools could assist with document extraction, request classification, and knowledge retrieval while preserving administrative review.

Conclusion

JAHEZ TRADE CO is a substantial bilingual software platform built around real operational needs. Its value comes from connecting public discovery, client requests, administrative decisions, consulting, scheduling, logistics, documents, communication, subscriptions, and content within one maintainable system.

For me, the project represents the ability to move from a broad business problem to a working technical product. It demonstrates how thoughtful data modeling, careful workflow design, reliable integrations, and human centered automation can turn fragmented service operations into a clear digital experience.