Skip to main content

Overview

This API is a Cloudflare Workers service built with Hono, Drizzle ORM (Turso), and Directus SDK. It exposes routes grouped under /v3 and uses Zod for request validation. A separate Elasticsearch index supports fuzzy company lookup by name. Images are stored in R2.

Applies to: v3

Quick facts

  • Runtime: Cloudflare Workers
  • Router: Hono
  • Database: Turso (libSQL)
  • Images: R2 buckets
  • Search: Elasticsearch (companies-index)

Key Libraries

  • Hono for HTTP routing and middleware
  • Drizzle ORM for Turso (libSQL) schema and queries
  • Directus SDK for data synchronization from Directus
  • Zod for schema validation and @hono/zod-validator for request validation
  • Elasticsearch for name-based search

Core Components

  • Routing: src/routes/index.ts mounts resource routers.
  • Services: src/services/* implements business logic (users, reports, barcodes, companies).
  • DTOs & mappers: src/dto/* declares response models and src/mappers/* converts database rows into camelCase DTOs.
  • Schemas: src/lib/dbs/schema/schema.ts contains Turso tables; Directus interfaces in src/lib/dbs/directus/schema.ts.
  • Middleware: authentication (src/middleware/auth.ts), cache (src/middleware/cache.ts), validation helpers (src/middleware/validation.ts).
  • Utilities: barcode validation/parsing (src/utils/barcode.ts), country code helpers (src/utils/countries.ts).

Request Lifecycle (typical)

  1. Request hits a versioned route (e.g., /v3/users/...).
  2. Middleware runs:
    • auth enforces JWT or public route + API key.
    • conditionalCache applies caching policy on selected GET routes.
  3. The route validates params/body via Zod.
  4. The route delegates to a service function for database and business logic.
  5. Services fetch data from Turso/Directus, then map results through the DTO layer (camelCase).
  6. Response is shaped and returned (JSON or streaming for assets).

Data Sources

  • Turso (primary runtime store): boycott/alternative companies, barcode tables, users, reports, lookup tables.
  • Directus (data source): data synchronized to Turso and R2 as needed.
  • Elasticsearch: denormalized company search index (companies-index).

See ../v3/barcode-matching.mdx for a deep dive into the matching flow.

Last updated on