# fractal-solutions/boost-carrier architecture

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

- Interactive diagram: https://gitdiagram.com/fractal-solutions/boost-carrier
- Repository: https://github.com/fractal-solutions/boost-carrier

## Overview

This repository is a Bun HTTP adapter between an ecommerce application and Uber Direct. Its main workflow accepts a quote request, verifies the drop-off address, requests an Uber quote, books a delivery, and fetches its current status and courier details. The server also exposes health and webhook endpoints; webhook events are logged, not persisted. OAuth tokens are cached, while delivery state is not stored. The README documents the workflow and integrations; connections below are limited to relationships visible in the excerpts or README.

Main entry points: [`server.ts`](https://github.com/fractal-solutions/boost-carrier/blob/main/server.ts) (Bun API server), [`delivery.ts`](https://github.com/fractal-solutions/boost-carrier/blob/main/delivery.ts) (Uber delivery client), [`auth.ts`](https://github.com/fractal-solutions/boost-carrier/blob/main/auth.ts) (OAuth token cache), [`address_validation.ts`](https://github.com/fractal-solutions/boost-carrier/blob/main/address_validation.ts) (Drop-off validator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_server["Bun API server<br/>[server.ts]"]
  node_webhook_log["Webhook logging<br/>[server.ts]"]
end

subgraph group_delivery["Delivery integration"]
  node_delivery_client["Uber delivery client<br/>[delivery.ts]"]
  node_oauth["OAuth token cache<br/>[auth.ts]"]
end

subgraph group_validation["Address verification"]
  node_address_validation["Drop-off validator"]
end

node_ecommerce(("Ecommerce app"))
node_uber_api["Uber Direct API"]
node_uber_oauth["Uber OAuth"]
node_photon["Photon geocoder"]
node_console["Server console"]

node_ecommerce -->|"calls API"| node_server
node_server -->|"validates address"| node_address_validation
node_server -->|"requests quote"| node_delivery_client
node_server -->|"books delivery"| node_delivery_client
node_server -->|"fetches status"| node_delivery_client
node_server -->|"logs webhook"| node_webhook_log
node_webhook_log -->|"writes events"| node_console
node_address_validation -->|"geocodes address"| node_photon
node_delivery_client -->|"gets token"| node_oauth
node_delivery_client -->|"sends requests"| node_uber_api
node_oauth -->|"requests token"| node_uber_oauth

click node_server "https://github.com/fractal-solutions/boost-carrier/blob/main/server.ts"
click node_webhook_log "https://github.com/fractal-solutions/boost-carrier/blob/main/server.ts"
click node_delivery_client "https://github.com/fractal-solutions/boost-carrier/blob/main/delivery.ts"
click node_oauth "https://github.com/fractal-solutions/boost-carrier/blob/main/auth.ts"
click node_address_validation "https://github.com/fractal-solutions/boost-carrier/blob/main/address_validation.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_server,node_webhook_log toneBlue
class node_delivery_client,node_oauth toneAmber
class node_address_validation,node_uber_api,node_console toneMint
class node_ecommerce,node_uber_oauth,node_photon toneIndigo
```

## Components

### HTTP API

- [Bun API server](https://github.com/fractal-solutions/boost-carrier/blob/main/server.ts): `server.ts`
- [Webhook logging](https://github.com/fractal-solutions/boost-carrier/blob/main/server.ts): `server.ts`

### Delivery integration

- [Uber delivery client](https://github.com/fractal-solutions/boost-carrier/blob/main/delivery.ts): `delivery.ts`
- [OAuth token cache](https://github.com/fractal-solutions/boost-carrier/blob/main/auth.ts): `auth.ts`

### Address verification

- [Drop-off validator](https://github.com/fractal-solutions/boost-carrier/blob/main/address_validation.ts): `address_validation.ts`

### Other components

- **Ecommerce app**
- **Uber Direct API**
- **Uber OAuth**
- **Photon geocoder**
- **Server console**

## Connections

- Ecommerce app → Bun API server: calls API (evidence: `README.md`)
- Bun API server → Drop-off validator: validates address (evidence: `server.ts`)
- Bun API server → Uber delivery client: requests quote (evidence: `server.ts`)
- Bun API server → Uber delivery client: books delivery (evidence: `server.ts`)
- Bun API server → Uber delivery client: fetches status (evidence: `server.ts`)
- Bun API server → Webhook logging: logs webhook (evidence: `server.ts`)
- Webhook logging → Server console: writes events (evidence: `server.ts`)
- Drop-off validator → Photon geocoder: geocodes address (evidence: `address_validation.ts`)
- Uber delivery client → OAuth token cache: gets token (evidence: `delivery.ts`)
- Uber delivery client → Uber Direct API: sends requests (evidence: `delivery.ts`)
- OAuth token cache → Uber OAuth: requests token (evidence: `auth.ts`)