# hugeletters/recallio architecture

> Architecture diagram of the GitHub repository hugeletters/recallio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hugeletters/recallio
- Repository: https://github.com/hugeletters/recallio

## Overview

##### Project type and purpose
- This is a full‑stack PWA built with Next.js (T3 Stack template):
- Frontend: React pages/components under `src/pages`, `src/interface`, `src/layout`, etc.
- Backend: Next.js API Routes and tRPC endpoints under `src/pages/api` and `src/server/api`.
- Database: SQLite hosted on Turso, accessed via Drizzle (migrations in `database/`).
- Cache/Queue: Redis via Upstash.
- File uploads: Uploadthing.
- Cron jobs: scheduled scripts in `scripts/cron` and `src/server/cron`.
- Service Worker for offline features in `src/sw`.

##### File structure
- Top‑level separation:
- `public/` – static assets and manifest.
- `src/pages/` – Next.js page components (including `/api` routes).
- `src/server/` – server‑side logic: API, auth, database layers, cron, Redis, uploadthing, validation.
- `scripts/` – dev/build/run scripts, DB migration generators, cron triggers.
- `database/migrations/` – SQL migrations and snapshot history.
- `src/sw/` – service worker code.
- Notice use of:
- NextAuth for user sessions (`src/auth`, `src/pages/api/auth/[...nextauth].ts`).
- tRPC for type‑safe RPC (`trpc/`, `src/pages/api/trpc/[trpc].ts`).
- Drizzle ORM config (`drizzle.config.ts`).
- Redis caching modules (`src/server/redis/`).
- Uploadthing integration (`src/server/uploadthing/` and `src/uploadthing/`).

##### README for additional insights
- Purpose: scan grocery‑store barcodes, view or leave reviews, mark private, tag, search.
- Services: Turso (DB), Upstash (Redis & MQ), Uploadthing (file storage), Vercel (hosting).
- PWA considerations: camera capture in secure context; uses service worker.

##### Main components and their interactions
a. Frontend (Browser/PWA)
– Next.js pages (React UI): scan page, product/review pages, search, auth pages.
– React Contexts/providers: Auth provider, Toast provider, state store.
– tRPC client: issues queries/mutations to backend.
– Service Worker: caches assets, intercepts fetch, handles offline TRPC queries.
– Barcode‑scanner module (`src/scan/`).
b. Backend (Serverless functions on Vercel)
– Next.js API Routes:
- Auth (`/api/auth/[...nextauth]` using NextAuth, DB adapter).
- Cron endpoints (`/api/file‑cleanup`, `/api/logs‑cleanup`).
- Uploadthing (`/api/uploadthing`).
– tRPC router (`/api/trpc/[trpc]`): routes to `src/server/api/*`.
– Server modules: DB client (Drizzle), cache utils, product scrapers, validation, logging.
– Cron workers: triggered by Upstash MQ or schedule, run cleanup & seed scripts.
c. Data stores & external services
– Turso (SQLite): persistent data (users, reviews, products, logs).
– Upstash Redis: caching layer, message queue for cron.
– Uploadthing: file storage for review images.
– External barcode scanning via `navigator.mediaDevices`.

##### Architectural patterns & design principles
- Monorepo‑style layering: clear separation between frontend (`src/pages`, UI modules) and backend (`src/server`).
- Serverless microservices: each API route acts as an isolated function.
- tRPC for type‑safe RPC replaces REST.
- Drizzle ORM centralizes schema/migrations.
- React Context & Zustand‑style store (`src/state`, `src/layout/store`).
- PWA best practices: service worker caching, offline support.
- Cron jobs decoupled via message queue.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Zone
    subgraph "Client (Browser/PWA)"
        direction TB
        UI["Next.js Pages (React UI)"]:::client
        Interface["Interface Components"]:::client
        LayoutState["Layout & Global State"]:::client
        TRPCClient["tRPC Client"]:::client
        Scanner["Barcode Scanner Module"]:::client
        SW["Service Worker"]:::client
    end

    %% Server Zone
    subgraph "Server (Vercel Serverless)"
        direction TB
        APIRoutes["Next.js API Routes"]:::server
        TRPCRouter["tRPC Router & Handlers"]:::server
        AuthSub["Auth Subsystem (NextAuth)"]:::server
        DBLayer["Database Layer (Drizzle + Turso)"]:::server
        CacheLayer["Cache Layer (Upstash Redis)"]:::server
        UploadS["Uploadthing Integration"]:::server
        CronSub["Cron Subsystem"]:::server
        ProdLogic["Product Logic"]:::server
        Utils["Validation & API Utils"]:::server
    end

    %% Data Stores & External
    Turso["Turso (SQLite)"]:::datastore
    RedisMQ["Upstash Redis & MQ"]:::datastore
    UploadExt["Uploadthing Service"]:::external
    CameraAPI["Camera API (navigator.mediaDevices)"]:::external

    %% Connections
    UI -->|uses| TRPCClient
    Interface -->|used by| UI
    LayoutState -->|provides state to| UI
    Scanner -->|captures barcode| UI
    SW -->|intercepts fetch| UI
    TRPCClient -->|RPC calls| TRPCRouter
    TRPCRouter -->|queries/mutations| DBLayer
    TRPCRouter -->|cache ops| CacheLayer
    TRPCRouter -->|file ops| UploadS
    AuthSub -->|auth data| DBLayer
    APIRoutes -->|delegates to| AuthSub
    APIRoutes -->|delegates to| CronSub
    APIRoutes -->|delegates to| UploadS
    DBLayer -->|stores data in| Turso
    CacheLayer -->|uses| RedisMQ
    CronSub -->|publishes jobs to| RedisMQ
    CronSub -->|triggers| APIRoutes
    UploadS -->|stores files in| UploadExt
    ProdLogic -->|scrapes & validates| TRPCRouter
    Utils -->|helpers for| TRPCRouter

    CameraAPI -->|provides stream to| Scanner

    %% Click Events - Client
    click UI "https://github.com/hugeletters/recallio/tree/main/src/pages/*"
    click Interface "https://github.com/hugeletters/recallio/tree/main/src/interface/"
    click LayoutState "https://github.com/hugeletters/recallio/blob/main/src/layout/index.tsx"
    click TRPCClient "https://github.com/hugeletters/recallio/blob/main/src/trpc/index.ts"
    click Scanner "https://github.com/hugeletters/recallio/blob/main/src/scan/hook.ts"
    click SW "https://github.com/hugeletters/recallio/blob/main/src/sw/index.ts"

    %% Click Events - Server
    click APIRoutes "https://github.com/hugeletters/recallio/tree/main/src/pages/api/"
    click TRPCRouter "https://github.com/hugeletters/recallio/blob/main/src/server/api/router.ts"
    click AuthSub "https://github.com/hugeletters/recallio/blob/main/src/server/auth/index.ts"
    click DBLayer "https://github.com/hugeletters/recallio/blob/main/src/server/database/client/serverless.ts"
    click CacheLayer "https://github.com/hugeletters/recallio/blob/main/src/server/redis/index.ts"
    click UploadS "https://github.com/hugeletters/recallio/blob/main/src/server/uploadthing/index.ts"
    click CronSub "https://github.com/hugeletters/recallio/blob/main/src/server/cron/index.ts"
    click ProdLogic "https://github.com/hugeletters/recallio/blob/main/src/server/product/cache.ts"
    click Utils "https://github.com/hugeletters/recallio/blob/main/src/server/validation/string.ts"

    %% Click Events - External/Data
    click Turso "https://github.com/hugeletters/recallio/tree/main/database/migrations/"
    click RedisMQ "https://github.com/hugeletters/recallio/blob/main/src/server/redis/index.ts"
    click UploadExt "https://github.com/hugeletters/recallio/blob/main/src/server/uploadthing/index.ts"

    %% Styles
    classDef client fill:#cce5ff,stroke:#000,stroke-width:1px
    classDef server fill:#ccffcc,stroke:#000,stroke-width:1px
    classDef datastore fill:#ffe0b3,stroke:#000,stroke-width:1px
    classDef external fill:#e5ccff,stroke:#000,stroke-width:1px
```
