# mfahim14/auctionsales-frontend architecture

> Architecture diagram of the GitHub repository mfahim14/auctionsales-frontend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mfahim14/auctionsales-frontend
- Repository: https://github.com/mfahim14/auctionsales-frontend

## Overview

FairPy Sales is an automotive-auction discovery and wholesale lead-intelligence frontend. Buyers filter inventory, inspect lots, save favorites, and use presets or the FairScout.AI Copilot; account and activity views support ongoing use. Admins manage users, crawler recipes and schedules, scrape runs, and failures. The shown API routes proxy requests to the configured backend, while client API calls attach Cognito tokens. Some pages and feature implementations were not sampled, so their links are included only where the README or source index supports them.

Main entry points: [`src/views/app/InventoryListPage.tsx`](https://github.com/mfahim14/auctionsales-frontend/blob/main/src/views/app/InventoryListPage.tsx) (Inventory Search), [`src/api/client.ts`](https://github.com/mfahim14/auctionsales-frontend/blob/main/src/api/client.ts) (API Client), [`src/auth/session.ts`](https://github.com/mfahim14/auctionsales-frontend/blob/main/src/auth/session.ts) (Auth Session), [`src/api/copilot.ts`](https://github.com/mfahim14/auctionsales-frontend/blob/main/src/api/copilot.ts) (Copilot API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and Shell"]
  node_signin["Sign In<br/>[SignInPage.tsx]"]
  node_auth["Auth Session<br/>[session.ts]"]
  node_cognito["Cognito"]
  node_app_shell["App Shell<br/>[AppShell.tsx]"]
end

subgraph group_discovery["Inventory Discovery"]
  node_inventory_page["Inventory Search"]
  node_inventory_query["Filter Query<br/>[query.ts]"]
  node_lot_details["Lot Details"]
end

subgraph group_buyer["Buyer Workflows"]
  node_favorites["Favorites<br/>[useFavorites.ts]"]
  node_copilot["FairScout Copilot<br/>[CopilotDrawer.tsx]"]
  node_copilot_chat["Chat State<br/>[useCopilotChat.ts]"]
  node_presets["Presets and Watchlists"]
  node_activity["Activity History<br/>[ActivityPage.tsx]"]
  node_account["Account<br/>[AccountPage.tsx]"]
end

subgraph group_admin["Administration"]
  node_admin_users["User Management<br/>[UserListPage.tsx]"]
  node_admin_recipe["Recipe Management<br/>[RecipePage.tsx]"]
  node_admin_runs["Scrape Runs"]
  node_admin_failures["Failure Review<br/>[FailuresPage.tsx]"]
end

subgraph group_platform["API Platform"]
  node_inventory_api["Inventory API<br/>[inventory.ts]"]
  node_copilot_api["Copilot API<br/>[copilot.ts]"]
  node_api_client["API Client<br/>[client.ts]"]
  node_route_proxy["Route Proxy<br/>[_proxy.ts]"]
end

node_buyer(("Buyer"))
node_admin_actor(("Admin"))
node_backend["FairPy Backend"]
node_dynamodb[("DynamoDB Sessions")]

node_buyer -->|"signs in"| node_signin
node_signin -->|"authenticates"| node_auth
node_auth -->|"uses"| node_cognito
node_buyer -->|"searches lots"| node_inventory_page
node_inventory_page -->|"filters query"| node_inventory_query
node_inventory_page -->|"loads inventory"| node_inventory_api
node_inventory_api -->|"requests data"| node_api_client
node_inventory_page -.->|"opens lot"| node_lot_details
node_inventory_page -->|"saves interest"| node_favorites
node_buyer -->|"discovers vehicles"| node_copilot
node_copilot -.->|"manages chat"| node_copilot_chat
node_copilot_chat -->|"sends messages"| node_copilot_api
node_copilot_api -->|"requests sessions"| node_api_client
node_copilot_api -->|"syncs threads"| node_dynamodb
node_buyer -->|"manages searches"| node_presets
node_buyer -.->|"reviews history"| node_activity
node_buyer -.->|"manages account"| node_account
node_admin_actor -->|"manages users"| node_admin_users
node_admin_actor -.->|"manages recipes"| node_admin_recipe
node_admin_actor -.->|"reviews runs"| node_admin_runs
node_admin_actor -.->|"reviews failures"| node_admin_failures
node_api_client -->|"gets token"| node_auth
node_api_client -.->|"calls API"| node_route_proxy
node_route_proxy -->|"forwards requests"| node_backend
node_app_shell -.->|"gates access"| node_auth

click node_signin "https://github.com/mfahim14/auctionsales-frontend/blob/main/src/views/public/SignInPage.tsx"
click node_auth "https://github.com/mfahim14/auctionsales-frontend/blob/main/src/auth/session.ts"
click node_app_shell "https://github.com/mfahim14/auctionsales-frontend/blob/main/src/layouts/AppShell.tsx"
click node_inventory_page "https://github.com/mfahim14/auctionsales-frontend/blob/main/src/views/app/InventoryListPage.tsx"
click node_inventory_query "https://github.com/mfahim14/auctionsales-frontend/blob/main/src/features/inventory/query.ts"
click node_lot_details "https://github.com/mfahim14/auctionsales-frontend/blob/main/src/views/app/InventoryDetailPage.tsx"
click node_inventory_api "https://github.com/mfahim14/auctionsales-frontend/blob/main/src/api/inventory.ts"
click node_favorites "https://github.com/mfahim14/auctionsales-frontend/blob/main/src/features/inventory/useFavorites.ts"
click node_copilot "https://github.com/mfahim14/auctionsales-frontend/blob/main/src/components/copilot/CopilotDrawer.tsx"
click node_copilot_chat "https://github.com/mfahim14/auctionsales-frontend/blob/main/src/components/copilot/useCopilotChat.ts"
click node_copilot_api "https://github.com/mfahim14/auctionsales-frontend/blob/main/src/api/copilot.ts"
click node_presets "https://github.com/mfahim14/auctionsales-frontend/blob/main/src/views/app/WatchlistListPage.tsx"
click node_activity "https://github.com/mfahim14/auctionsales-frontend/blob/main/src/views/app/ActivityPage.tsx"
click node_account "https://github.com/mfahim14/auctionsales-frontend/blob/main/src/views/app/AccountPage.tsx"
click node_admin_users "https://github.com/mfahim14/auctionsales-frontend/blob/main/src/views/admin/UserListPage.tsx"
click node_admin_recipe "https://github.com/mfahim14/auctionsales-frontend/blob/main/src/views/admin/RecipePage.tsx"
click node_admin_runs "https://github.com/mfahim14/auctionsales-frontend/blob/main/src/views/admin/ScrapeRunListPage.tsx"
click node_admin_failures "https://github.com/mfahim14/auctionsales-frontend/blob/main/src/views/admin/FailuresPage.tsx"
click node_api_client "https://github.com/mfahim14/auctionsales-frontend/blob/main/src/api/client.ts"
click node_route_proxy "https://github.com/mfahim14/auctionsales-frontend/blob/main/app/api/_proxy.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_signin,node_auth,node_cognito,node_app_shell toneBlue
class node_inventory_page,node_inventory_query,node_lot_details,node_dynamodb toneAmber
class node_favorites,node_copilot,node_copilot_chat,node_presets,node_activity,node_account toneMint
class node_admin_users,node_admin_recipe,node_admin_runs,node_admin_failures toneRose
class node_inventory_api,node_copilot_api,node_api_client,node_route_proxy,node_buyer,node_admin_actor,node_backend toneIndigo
```

## Components

### Identity and Shell

- [Sign In](https://github.com/mfahim14/auctionsales-frontend/blob/main/src/views/public/SignInPage.tsx): `src/views/public/SignInPage.tsx`
- [Auth Session](https://github.com/mfahim14/auctionsales-frontend/blob/main/src/auth/session.ts): `src/auth/session.ts`
- **Cognito**
- [App Shell](https://github.com/mfahim14/auctionsales-frontend/blob/main/src/layouts/AppShell.tsx): `src/layouts/AppShell.tsx`

### Inventory Discovery

- [Inventory Search](https://github.com/mfahim14/auctionsales-frontend/blob/main/src/views/app/InventoryListPage.tsx): `src/views/app/InventoryListPage.tsx`
- [Filter Query](https://github.com/mfahim14/auctionsales-frontend/blob/main/src/features/inventory/query.ts): `src/features/inventory/query.ts`
- [Lot Details](https://github.com/mfahim14/auctionsales-frontend/blob/main/src/views/app/InventoryDetailPage.tsx): `src/views/app/InventoryDetailPage.tsx`

### Buyer Workflows

- [Favorites](https://github.com/mfahim14/auctionsales-frontend/blob/main/src/features/inventory/useFavorites.ts): `src/features/inventory/useFavorites.ts`
- [FairScout Copilot](https://github.com/mfahim14/auctionsales-frontend/blob/main/src/components/copilot/CopilotDrawer.tsx): `src/components/copilot/CopilotDrawer.tsx`
- [Chat State](https://github.com/mfahim14/auctionsales-frontend/blob/main/src/components/copilot/useCopilotChat.ts): `src/components/copilot/useCopilotChat.ts`
- [Presets and Watchlists](https://github.com/mfahim14/auctionsales-frontend/blob/main/src/views/app/WatchlistListPage.tsx): `src/views/app/WatchlistListPage.tsx`
- [Activity History](https://github.com/mfahim14/auctionsales-frontend/blob/main/src/views/app/ActivityPage.tsx): `src/views/app/ActivityPage.tsx`
- [Account](https://github.com/mfahim14/auctionsales-frontend/blob/main/src/views/app/AccountPage.tsx): `src/views/app/AccountPage.tsx`

### Administration

- [User Management](https://github.com/mfahim14/auctionsales-frontend/blob/main/src/views/admin/UserListPage.tsx): `src/views/admin/UserListPage.tsx`
- [Recipe Management](https://github.com/mfahim14/auctionsales-frontend/blob/main/src/views/admin/RecipePage.tsx): `src/views/admin/RecipePage.tsx`
- [Scrape Runs](https://github.com/mfahim14/auctionsales-frontend/blob/main/src/views/admin/ScrapeRunListPage.tsx): `src/views/admin/ScrapeRunListPage.tsx`
- [Failure Review](https://github.com/mfahim14/auctionsales-frontend/blob/main/src/views/admin/FailuresPage.tsx): `src/views/admin/FailuresPage.tsx`

### API Platform

- [Inventory API](https://github.com/mfahim14/auctionsales-frontend/blob/main/src/api/inventory.ts): `src/api/inventory.ts`
- [Copilot API](https://github.com/mfahim14/auctionsales-frontend/blob/main/src/api/copilot.ts): `src/api/copilot.ts`
- [API Client](https://github.com/mfahim14/auctionsales-frontend/blob/main/src/api/client.ts): `src/api/client.ts`
- [Route Proxy](https://github.com/mfahim14/auctionsales-frontend/blob/main/app/api/_proxy.ts): `app/api/_proxy.ts`

### Other components

- **Buyer**
- **Admin**
- **FairPy Backend**
- **DynamoDB Sessions**

## Connections

- Buyer → Sign In: signs in (evidence: `README.md`)
- Sign In → Auth Session: authenticates (evidence: `src/views/public/SignInPage.tsx`)
- Auth Session → Cognito: uses (evidence: `src/auth/session.ts`)
- Buyer → Inventory Search: searches lots (evidence: `README.md`)
- Inventory Search → Filter Query: filters query (evidence: `src/views/app/InventoryListPage.tsx`)
- Inventory Search → Inventory API: loads inventory (evidence: `src/views/app/InventoryListPage.tsx`)
- Inventory API → API Client: requests data (evidence: `src/api/inventory.ts`)
- Inventory Search → Lot Details: opens lot
- Inventory Search → Favorites: saves interest (evidence: `src/views/app/InventoryListPage.tsx`)
- Buyer → FairScout Copilot: discovers vehicles (evidence: `README.md`)
- FairScout Copilot → Chat State: manages chat
- Chat State → Copilot API: sends messages (evidence: `src/components/copilot/useCopilotChat.ts`)
- Copilot API → API Client: requests sessions (evidence: `src/api/copilot.ts`)
- Copilot API → DynamoDB Sessions: syncs threads (evidence: `README.md`)
- Buyer → Presets and Watchlists: manages searches (evidence: `README.md`)
- Buyer → Activity History: reviews history
- Buyer → Account: manages account
- Admin → User Management: manages users (evidence: `src/views/admin/UserListPage.tsx`)
- Admin → Recipe Management: manages recipes
- Admin → Scrape Runs: reviews runs
- Admin → Failure Review: reviews failures
- API Client → Auth Session: gets token (evidence: `src/api/client.ts`)
- API Client → Route Proxy: calls API
- Route Proxy → FairPy Backend: forwards requests (evidence: `app/api/_proxy.ts`)
- App Shell → Auth Session: gates access
