CargoCore Logistics Platform

1. Product Goal

Create an original logistics brand and a working website that helps customers learn about freight services, track verified shipments, request quotes, and contact support. Authorized staff must manage shipments, shipment events, quotes, inquiries, and editable website content.

2. Recommended Architecture

Suggested C++ structure

src/
  main.cpp
  config/
  http/
    routes.cpp
    middleware/
  controllers/
  services/
  repositories/
  models/
  validators/
  auth/
  utils/
tests/
migrations/
public/
  index.html
  assets/
CMakeLists.txt
.env.example
README.md

3. Brand and Interface

Use an original premium corporate identity called CargoCore or another editable name. Use navy blue, white, light gray, and orange accents. Use bold headings, readable body text, spacious layouts, professional logistics imagery, subtle transitions, clear CTAs, and mobile-first responsive behavior.

Shared UI elements

Implement a sticky header, mobile menu, logo, buttons, tracking form, service cards, shipment timeline, quote form, contact form, FAQ accordion, support widget, loading states, error states, empty states, success messages, admin layout, protected route, and a consistent footer.

Required pages

• Home
• About Us
• Services overview
• Air Freight, Ocean Freight, Road Freight, Express Courier detail pages
• Shipment Tracking
• Request a Quote
• Contact Us
• FAQ
• Privacy Policy
• Terms and Conditions
• Protected Admin Dashboard

4. REST API Contract

Return JSON responses with consistent fields such as success, data, error, and requestId. Validate all request bodies server-side.

Example public tracking response

{
  "success": true,
  "data": {
    "trackingNumber": "CC-2026-0001",
    "status": "in_transit",
    "origin": "Chicago, USA",
    "destination": "Toronto, Canada",
    "estimatedDelivery": "2026-10-20",
    "currentLocation": "Detroit Facility",
    "shippingMethod": "Road Freight",
    "events": []
  },
  "requestId": "req_abc123"
}

5. Database Model

Use UUID primary keys, timestamps, foreign keys, indexes, check constraints, and migration files. Never use tracking numbers as the primary key.

6. Shipment Tracking Rules

1. Accept a tracking number and normalize safe whitespace/case.
2. Query only verified shipment records.
3. Return a safe not-found response without revealing whether private records exist.
4. Expose only public fields; mask or omit private addresses, phone numbers, email addresses, and internal notes.
5. Display the seven stages: Registered, Picked Up, Processing, In Transit, Arrived, Out for Delivery, Delivered.
6. Show completed, current, and upcoming stages separately.
7. Do not claim live GPS or real-time updates without a connected carrier/GPS provider.

7. Customer Forms

Quote request

Collect full name, email, phone, optional company, pickup, destination, shipment type, weight, dimensions, package count, shipping method, pickup date, instructions, special handling, and fragile cargo. Validate in the frontend and again in the C++ API. Save the request and tell the customer the team will review the details. Do not show an invented price.

Contact inquiry

Collect full name, email, optional phone, subject, and message. Save securely, return a confirmation, and show editable company contact information. If live chat is not integrated, provide a contact form instead of claiming an agent is available.

8. Administration

Protect the admin dashboard with authentication and role-based permissions. Implement separate permissions for staff and administrators.

9. Security and Privacy

• Use HTTPS in production.
• Store secrets only in environment variables or a secrets manager.
• Hash passwords with Argon2id or bcrypt; never store plaintext passwords.
• Use short-lived access tokens and refresh-token rotation, or secure HttpOnly cookies.
• Validate and length-limit every request field.
• Use parameterized SQL queries.
• Apply CORS allowlists, rate limits, request-size limits, and security headers.
• Log security-relevant events without logging passwords, tokens, or private customer data.
• Return generic errors to clients and detailed errors only to protected logs.
• Apply least privilege to database roles and admin actions.

10. Testing and Operations

Build requirements

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel
ctest --test-dir build --output-on-failure

11. Acceptance Criteria

The project is complete when:

• All required customer and admin routes work.
• The UI is responsive on mobile, tablet, and desktop.
• Tracking queries real database records and never fabricates updates.
• Public tracking responses protect private customer data.
• Quote and contact forms validate and persist submissions.
• Authorized staff can create and update shipments.
• Status changes create timestamped shipment events.
• Authentication and role-based access are enforced server-side.
• RLS or equivalent database permissions are configured.
• Services, FAQs, testimonials, and contact settings are editable.
• Loading, empty, success, error, and not-found states are implemented.
• SEO metadata, sitemap, robots.txt, semantic HTML, and accessibility basics are present.
• The app has no hardcoded credentials or sensitive data in frontend code.
• README documentation explains setup, environment variables, migrations, seed data, testing, and deployment.