How pranavkrishnasuresh/getasap-logistics works
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: api API routes · dashboard-shell.tsx Dashboard shell · quote-engine.ts Quote engine · request-form.tsx Request form
Components 19
Customer experience
Shipment request, quote, and tracking flow for external users.
- Intake · Shipment request entry point.
src/app/page.tsx - Request form · Customer shipment intake form.
src/components/shipment/request-form.tsx - Quote view · Generated quote and confirmation screen.
src/app/quote/page.tsx - Quote client · Interactive quote result UI.
src/app/quote/quote-client.tsx - Tracking view · Live shipment tracking entry point.
src/app/tracking/page.tsx - Tracking client · Polling-driven tracking UI.
src/app/tracking/tracking-client.tsx
Operator dashboard
Internal shipment management and event review console.
- Dashboard page · Internal operations entry point.
src/app/dashboard/page.tsx - Dashboard shell · Top-level dashboard composition.
src/app/dashboard/dashboard-shell.tsx - Shipment list · Lists shipments for operators.
src/components/dashboard/shipment-list.tsx - Shipment detail · Shows shipment state and details.
src/components/dashboard/shipment-detail.tsx - Event feed · Displays shipment event history.
src/components/dashboard/event-feed.tsx - Status filter · Filters dashboard shipments by status.
src/components/dashboard/status-filter.tsx
Shared backend
Route handlers, domain logic, data sources, and common types.
- API routes · REST boundary for quotes, shipments, and events.
src/app/api - Quote engine · Rate calculation and quote assembly.
src/lib/quote-engine.ts - Mock data · Default in-memory/demo dataset.
src/lib/mock-data.ts - AI adapter · Optional AI-backed quote narration and summaries.
src/lib/ai.ts - Domain types · Shared shipment, quote, and event models.
src/types/index.ts - Supabase · Optional PostgreSQL-backed persistence layer.
src/supabase - Polling hook · Refreshes shipment state on an interval.
src/hooks/use-shipment-polling.ts
Connections 21
- 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.