# pranavkrishnasuresh/getasap-logistics architecture

> Architecture diagram of the GitHub repository pranavkrishnasuresh/getasap-logistics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pranavkrishnasuresh/getasap-logistics
- Repository: https://github.com/pranavkrishnasuresh/getasap-logistics

## Overview

1. **Overall shape**
   - This is a **Next.js 15 App Router** prototype for a reefer freight brokerage workflow.
   - It has two user-facing surfaces: a **customer quote/tracking experience** and an **internal operations dashboard**.
   - The app is designed to run **entirely on mock data by default**, with **Supabase** as an optional persistence layer.

2. **Primary route boundaries**
   - `/` is the **shipment request intake** entry point.
   - `/quote` presents the **generated rate/quote result** and confirmation step.
   - `/tracking` provides **live shipment tracking** and event history.
   - `/dashboard` is the **operator console** for managing shipments and events.
   - These pages are implemented in `src/app/`, with page-specific client components where interactivity is needed.

3. **Backend/API layer**
   - The app uses App Router API routes under `src/app/api/` as the main backend boundary.
   - Key endpoints exist for:
     - `quote` for quote generation
     - `shipment` and `shipments` for shipment lookup/listing
     - `shipment/[id]/confirm` for confirming a shipment
     - `events/[id]` for shipment/event retrieval
   - This suggests the UI talks to the backend through REST-style routes rather than direct database access from components.

4. **Business logic core**
   - The `src/lib/` folder holds the domain logic that likely powers the API routes and UI:
     - `quote-engine.ts` for rate calculation / quote assembly
     - `ai.ts` for AI-generated quote summaries or narrative output
     - `mock-data.ts` for the default in-memory/demo data source
     - `utils.ts` for shared helpers
   - This is the main place where freight-specific logic is separated from presentation.

5. **Data source strategy**
   - The system defaults to **mock data** so the whole app works without external services.
   - `src/supabase/` contains the optional database integration:
     - `schema.sql` for the PostgreSQL schema
     - `seed.sql` for demo records
     - `client.ts` for the browser/client connection
   - In practice, the architecture is “mock-first, Supabase-enabled,” with the API and UI able to operate without the database.

6. **Customer flow data path**
   - The customer starts with the **shipment request form** in `src/components/shipment/request-form.tsx`.
   - The request is processed through the quote endpoint and business logic in `src/lib/quote-engine.ts`.
   - The result is shown on `/quote` via `src/app/quote/quote-client.tsx`.
   - If the customer confirms, the shipment confirmation API updates the shipment lifecycle and feeds the tracking experience.

7. **Tracking and event streaming**
   - `/tracking` is built for **live operational visibility**.
   - `src/hooks/use-shipment-polling.ts` indicates the UI periodically refreshes shipment state instead of relying solely on push updates.
   - Shipment events are represented through the API and visualized with timeline-style primitives, so the tracking page is likely driven by a shipment detail record plus an ordered event feed.

8. **Dashboard subsystem**
   - `/dashboard` is an internal ops console composed from `src/components/dashboard/*` and `src/app/dashboard/dashboard-shell.tsx`.
   - It includes:
     - shipment list
     - shipment detail view
     - event feed
     - status filtering
   - This area is optimized for operational review and triage rather than customer interaction.

9. **Reusable UI architecture**
   - `src/components/primitives/` contains domain-flavored building blocks like:
     - status chips
     - confidence indicators
     - metric cards
     - timelines
     - empty states
   - `src/components/ui/` contains the lower-level shadcn/ui component set used across the app.
   - This split separates **generic UI primitives** from **business-semantic presentation**.

10. **Client/server composition**
   - Next.js server-rendered pages provide the route shell, while interactive sections are isolated into `*-client.tsx` components.
   - That pattern appears in quote and tracking screens, implying a mix of server routing with client-side interactivity for polling, form handling, and dynamic UI state.

11. **AI integration boundary**
   - `src/lib/ai.ts` abstracts model access behind provider selection.
   - The README shows support for **OpenAI**, **Google Generative AI**, or **mock AI**, controlled by environment variables.
   - This keeps AI-enhanced quote summaries optional and prevents the rest of the app from depending on a specific vendor.

12. **Types and contract consistency**
   - `src/types/index.ts` centralizes shared TypeScript types for shipments, events, quotes, and related domain models.
   - This is the contract layer used across API routes, library code, hooks, and UI components, helping keep customer and ops views aligned.

13. **Infrastructure and runtime implications**
   - The stack is **Next.js + TypeScript + Tailwind CSS v4 + shadcn/ui**, with Motion for animation.
   - Vercel is the intended deployment target, but the architecture remains mostly self-contained because mock data is the default and Supabase is optional.

14. **How to diagram it**
   - Draw three main zones: **Customer experience**, **Operator dashboard**, and **Shared backend/domain layer**.
   - Connect both UI zones to the **Next.js API routes**.
   - Show the API layer talking to either **mock data / business logic** or **Supabase**.
   - Place **AI provider abstraction** as an optional dependency off the quote logic, not as a core system dependency.

Main entry points: [`src/app/api`](https://github.com/pranavkrishnasuresh/getasap-logistics/tree/main/src/app/api) (API routes), [`src/app/dashboard/dashboard-shell.tsx`](https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/app/dashboard/dashboard-shell.tsx) (Dashboard shell), [`src/lib/quote-engine.ts`](https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/lib/quote-engine.ts) (Quote engine), [`src/components/shipment/request-form.tsx`](https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/components/shipment/request-form.tsx) (Request form)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_customer["Customer experience"]
  node_home["Intake<br/>route page<br/>[page.tsx]"]
  node_request_form["Request form<br/>client form<br/>[request-form.tsx]"]
  node_quote_page["Quote view<br/>route page<br/>[page.tsx]"]
  node_quote_client["Quote client<br/>client screen<br/>[quote-client.tsx]"]
  node_tracking_page["Tracking view<br/>route page<br/>[page.tsx]"]
  node_tracking_client["Tracking client<br/>client screen"]
end

subgraph group_ops["Operator dashboard"]
  node_dashboard_page["Dashboard page<br/>route page<br/>[page.tsx]"]
  node_dashboard_shell["Dashboard shell<br/>layout shell"]
  node_shipment_list["Shipment list<br/>ops component<br/>[shipment-list.tsx]"]
  node_shipment_detail["Shipment detail<br/>ops component"]
  node_event_feed["Event feed<br/>ops component<br/>[event-feed.tsx]"]
  node_status_filter["Status filter<br/>ops component<br/>[status-filter.tsx]"]
end

subgraph group_shared["Shared backend"]
  node_api_routes["API routes<br/>route handlers"]
  node_quote_engine["Quote engine<br/>business logic<br/>[quote-engine.ts]"]
  node_mock_data[("Mock data<br/>data source<br/>[mock-data.ts]")]
  node_ai_layer["AI adapter<br/>provider abstraction<br/>[ai.ts]"]
  node_domain_types["Domain types<br/>contracts<br/>[index.ts]"]
  node_supabase[("Supabase<br/>optional persistence")]
  node_polling_hook["Polling hook<br/>client hook"]
end

node_home -->|"renders"| node_request_form
node_request_form -->|"submit quote"| node_api_routes
node_api_routes -->|"compute"| node_quote_engine
node_quote_engine -->|"reads"| node_mock_data
node_quote_engine -.->|"optional"| node_ai_layer
node_api_routes -.->|"persist/lookup"| node_supabase
node_api_routes -->|"share models"| node_domain_types
node_quote_page -->|"renders"| node_quote_client
node_quote_client -->|"confirm"| node_api_routes
node_tracking_page -->|"renders"| node_tracking_client
node_tracking_client -->|"uses"| node_polling_hook
node_polling_hook -->|"fetches"| node_api_routes
node_dashboard_page -->|"renders"| node_dashboard_shell
node_dashboard_shell -->|"contains"| node_shipment_list
node_dashboard_shell -->|"contains"| node_shipment_detail
node_dashboard_shell -->|"contains"| node_event_feed
node_dashboard_shell -->|"contains"| node_status_filter
node_shipment_list -->|"loads"| node_api_routes
node_shipment_detail -->|"loads"| node_api_routes
node_event_feed -->|"loads"| node_api_routes
node_api_routes -->|"default source"| node_mock_data

click node_home "https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/app/page.tsx"
click node_request_form "https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/components/shipment/request-form.tsx"
click node_quote_page "https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/app/quote/page.tsx"
click node_quote_client "https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/app/quote/quote-client.tsx"
click node_tracking_page "https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/app/tracking/page.tsx"
click node_tracking_client "https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/app/tracking/tracking-client.tsx"
click node_dashboard_page "https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/app/dashboard/page.tsx"
click node_dashboard_shell "https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/app/dashboard/dashboard-shell.tsx"
click node_shipment_list "https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/components/dashboard/shipment-list.tsx"
click node_shipment_detail "https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/components/dashboard/shipment-detail.tsx"
click node_event_feed "https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/components/dashboard/event-feed.tsx"
click node_status_filter "https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/components/dashboard/status-filter.tsx"
click node_api_routes "https://github.com/pranavkrishnasuresh/getasap-logistics/tree/main/src/app/api"
click node_quote_engine "https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/lib/quote-engine.ts"
click node_mock_data "https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/lib/mock-data.ts"
click node_ai_layer "https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/lib/ai.ts"
click node_domain_types "https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/types/index.ts"
click node_supabase "https://github.com/pranavkrishnasuresh/getasap-logistics/tree/main/src/supabase"
click node_polling_hook "https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/hooks/use-shipment-polling.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_home,node_request_form,node_quote_page,node_quote_client,node_tracking_page,node_tracking_client toneBlue
class node_dashboard_page,node_dashboard_shell,node_shipment_list,node_shipment_detail,node_event_feed,node_status_filter toneAmber
class node_api_routes,node_quote_engine,node_mock_data,node_ai_layer,node_domain_types,node_supabase,node_polling_hook toneMint
```

## Components

### Customer experience

Shipment request, quote, and tracking flow for external users.

- [Intake](https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/app/page.tsx): route page · Shipment request entry point. · `src/app/page.tsx`
- [Request form](https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/components/shipment/request-form.tsx): client form · Customer shipment intake form. · `src/components/shipment/request-form.tsx`
- [Quote view](https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/app/quote/page.tsx): route page · Generated quote and confirmation screen. · `src/app/quote/page.tsx`
- [Quote client](https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/app/quote/quote-client.tsx): client screen · Interactive quote result UI. · `src/app/quote/quote-client.tsx`
- [Tracking view](https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/app/tracking/page.tsx): route page · Live shipment tracking entry point. · `src/app/tracking/page.tsx`
- [Tracking client](https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/app/tracking/tracking-client.tsx): client screen · Polling-driven tracking UI. · `src/app/tracking/tracking-client.tsx`

### Operator dashboard

Internal shipment management and event review console.

- [Dashboard page](https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/app/dashboard/page.tsx): route page · Internal operations entry point. · `src/app/dashboard/page.tsx`
- [Dashboard shell](https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/app/dashboard/dashboard-shell.tsx): layout shell · Top-level dashboard composition. · `src/app/dashboard/dashboard-shell.tsx`
- [Shipment list](https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/components/dashboard/shipment-list.tsx): ops component · Lists shipments for operators. · `src/components/dashboard/shipment-list.tsx`
- [Shipment detail](https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/components/dashboard/shipment-detail.tsx): ops component · Shows shipment state and details. · `src/components/dashboard/shipment-detail.tsx`
- [Event feed](https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/components/dashboard/event-feed.tsx): ops component · Displays shipment event history. · `src/components/dashboard/event-feed.tsx`
- [Status filter](https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/components/dashboard/status-filter.tsx): ops component · Filters dashboard shipments by status. · `src/components/dashboard/status-filter.tsx`

### Shared backend

Route handlers, domain logic, data sources, and common types.

- [API routes](https://github.com/pranavkrishnasuresh/getasap-logistics/tree/main/src/app/api): route handlers · REST boundary for quotes, shipments, and events. · `src/app/api`
- [Quote engine](https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/lib/quote-engine.ts): business logic · Rate calculation and quote assembly. · `src/lib/quote-engine.ts`
- [Mock data](https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/lib/mock-data.ts): data source · Default in-memory/demo dataset. · `src/lib/mock-data.ts`
- [AI adapter](https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/lib/ai.ts): provider abstraction · Optional AI-backed quote narration and summaries. · `src/lib/ai.ts`
- [Domain types](https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/types/index.ts): contracts · Shared shipment, quote, and event models. · `src/types/index.ts`
- [Supabase](https://github.com/pranavkrishnasuresh/getasap-logistics/tree/main/src/supabase): optional persistence · Optional PostgreSQL-backed persistence layer. · `src/supabase`
- [Polling hook](https://github.com/pranavkrishnasuresh/getasap-logistics/blob/main/src/hooks/use-shipment-polling.ts): client hook · Refreshes shipment state on an interval. · `src/hooks/use-shipment-polling.ts`

## Connections

- Intake → Request form: renders · The landing route mounts the shipment intake form.
- Request form → API routes: submit quote · Customer form submits shipment details for pricing.
- API routes → Quote engine: compute · Quote endpoint delegates pricing and assembly.
- Quote engine → Mock data: reads · Default quote flow uses demo shipment data.
- Quote engine → AI adapter: optional · AI can generate explanatory quote summaries.
- API routes → Supabase: persist/lookup · API can read or write shipment records via the database layer.
- API routes → Domain types: share models · Handlers rely on common request and response contracts.
- Quote view → Quote client: renders · Server route shells the interactive quote screen.
- Quote client → API routes: confirm · Quote UI posts confirmation through the API boundary.
- Tracking view → Tracking client: renders · Server route shells the tracking experience.
- Tracking client → Polling hook: uses · Tracking UI refreshes shipment status periodically.
- Polling hook → API routes: fetches · Polling reads shipment and event data from API routes.
- Dashboard page → Dashboard shell: renders · Dashboard route composes the operator shell.
- Dashboard shell → Shipment list: contains · Shell coordinates the shipment list view.
- Dashboard shell → Shipment detail: contains · Shell coordinates the detail pane.
- Dashboard shell → Event feed: contains · Shell includes shipment event history.
- Dashboard shell → Status filter: contains · Shell includes operational filtering controls.
- Shipment list → API routes: loads · Operator list is backed by shipment APIs.
- Shipment detail → API routes: loads · Detail pane fetches shipment state and events.
- Event feed → API routes: loads · Event timeline is sourced from API routes.
- API routes → Mock data: default source · Mock data powers the app when persistence is absent.
