# yucodings/vericargo_extension architecture

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

- Interactive diagram: https://gitdiagram.com/yucodings/vericargo_extension
- Repository: https://github.com/yucodings/vericargo_extension

## Overview

VeriCargo’s active product is the Chrome side-panel assistant backed by the Cloud Run API; the root Next.js app is an earlier fixture-backed prototype. The principal workflow connects Gmail, synchronizes and classifies Inbox mail, processes SI/Draft BL documents, compares seven fields, then presents uncertain cases for human review and draft preparation. The graph follows documented capabilities and the server’s service wiring; unsampled service internals are represented at their exact paths, with uncertain internal links omitted.

Main entry points: [`cloud-run-api/src/app.js`](https://github.com/yucodings/vericargo_extension/blob/main/cloud-run-api/src/app.js) (HTTP API), [`cloud-run-api/src/document-service.js`](https://github.com/yucodings/vericargo_extension/blob/main/cloud-run-api/src/document-service.js) (Document processing), [`cloud-run-api/src/gmail-service.js`](https://github.com/yucodings/vericargo_extension/blob/main/cloud-run-api/src/gmail-service.js) (Gmail service), [`cloud-run-api/src/oauth-service.js`](https://github.com/yucodings/vericargo_extension/blob/main/cloud-run-api/src/oauth-service.js) (OAuth service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extension["Chrome extension"]
  node_sidepanel["Side panel<br/>[sidepanel.js]"]
  node_cloudclient["Cloud client<br/>[cloud-client.js]"]
  node_worker["Background worker<br/>[service-worker.js]"]
end

subgraph group_backend["Cloud Run API"]
  node_api["HTTP API<br/>[app.js]"]
  node_oauth["OAuth service<br/>[oauth-service.js]"]
  node_gmailservice["Gmail service<br/>[gmail-service.js]"]
  node_crypto["Crypto utilities<br/>[crypto-utils.js]"]
end

subgraph group_processing["Classification and documents"]
  node_classification["Email classification"]
  node_documents["Document processing"]
  node_parser["Lightweight parser"]
  node_comparison["SI/BL comparison"]
  node_drafts["BL draft service"]
end

subgraph group_integrations["External services"]
  node_firestore[("Firestore")]
  node_gmail["Gmail"]
  node_googleoauth["Google OAuth"]
  node_gemini["Gemini"]
end

node_user(("Reviewer"))

node_user -->|"reviews in"| node_sidepanel
node_sidepanel -->|"requests"| node_cloudclient
node_worker -->|"syncs via"| node_cloudclient
node_cloudclient -->|"calls API"| node_api
node_api -->|"dispatches auth"| node_oauth
node_api -->|"dispatches mail"| node_gmailservice
node_api -->|"dispatches classification"| node_classification
node_api -->|"dispatches processing"| node_documents
node_oauth -->|"authorizes with"| node_googleoauth
node_oauth -->|"encrypts tokens"| node_crypto
node_oauth -->|"stores credentials"| node_firestore
node_gmailservice -->|"syncs and labels"| node_gmail
node_gmailservice -->|"stores cases"| node_firestore
node_classification -->|"classifies with"| node_gemini
node_classification -->|"stores results"| node_firestore
node_classification -->|"loads attachments"| node_gmailservice
node_documents -->|"loads attachments"| node_gmailservice
node_documents -->|"parses documents"| node_parser
node_documents -->|"compares fields"| node_comparison
node_documents -->|"stores outcomes"| node_firestore
node_api -->|"dispatches drafts"| node_drafts
node_drafts -->|"reads case data"| node_firestore

click node_sidepanel "https://github.com/yucodings/vericargo_extension/blob/main/chrome-extension/sidepanel.js"
click node_cloudclient "https://github.com/yucodings/vericargo_extension/blob/main/chrome-extension/cloud-client.js"
click node_worker "https://github.com/yucodings/vericargo_extension/blob/main/chrome-extension/service-worker.js"
click node_api "https://github.com/yucodings/vericargo_extension/blob/main/cloud-run-api/src/app.js"
click node_oauth "https://github.com/yucodings/vericargo_extension/blob/main/cloud-run-api/src/oauth-service.js"
click node_gmailservice "https://github.com/yucodings/vericargo_extension/blob/main/cloud-run-api/src/gmail-service.js"
click node_classification "https://github.com/yucodings/vericargo_extension/blob/main/cloud-run-api/src/classification-service.js"
click node_documents "https://github.com/yucodings/vericargo_extension/blob/main/cloud-run-api/src/document-service.js"
click node_parser "https://github.com/yucodings/vericargo_extension/blob/main/cloud-run-api/src/lightweight-parser.js"
click node_comparison "https://github.com/yucodings/vericargo_extension/blob/main/cloud-run-api/src/document-comparison.js"
click node_drafts "https://github.com/yucodings/vericargo_extension/blob/main/cloud-run-api/src/bl-draft-service.js"
click node_crypto "https://github.com/yucodings/vericargo_extension/blob/main/cloud-run-api/src/crypto-utils.js"

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_sidepanel,node_cloudclient,node_worker,node_user toneBlue
class node_api,node_oauth,node_gmailservice,node_crypto toneAmber
class node_classification,node_documents,node_parser,node_comparison,node_drafts toneMint
class node_firestore,node_gmail,node_googleoauth,node_gemini toneRose
```

## Components

### Chrome extension

- [Side panel](https://github.com/yucodings/vericargo_extension/blob/main/chrome-extension/sidepanel.js): `chrome-extension/sidepanel.js`
- [Cloud client](https://github.com/yucodings/vericargo_extension/blob/main/chrome-extension/cloud-client.js): `chrome-extension/cloud-client.js`
- [Background worker](https://github.com/yucodings/vericargo_extension/blob/main/chrome-extension/service-worker.js): `chrome-extension/service-worker.js`

### Cloud Run API

- [HTTP API](https://github.com/yucodings/vericargo_extension/blob/main/cloud-run-api/src/app.js): `cloud-run-api/src/app.js`
- [OAuth service](https://github.com/yucodings/vericargo_extension/blob/main/cloud-run-api/src/oauth-service.js): `cloud-run-api/src/oauth-service.js`
- [Gmail service](https://github.com/yucodings/vericargo_extension/blob/main/cloud-run-api/src/gmail-service.js): `cloud-run-api/src/gmail-service.js`
- [Crypto utilities](https://github.com/yucodings/vericargo_extension/blob/main/cloud-run-api/src/crypto-utils.js): `cloud-run-api/src/crypto-utils.js`

### Classification and documents

- [Email classification](https://github.com/yucodings/vericargo_extension/blob/main/cloud-run-api/src/classification-service.js): `cloud-run-api/src/classification-service.js`
- [Document processing](https://github.com/yucodings/vericargo_extension/blob/main/cloud-run-api/src/document-service.js): `cloud-run-api/src/document-service.js`
- [Lightweight parser](https://github.com/yucodings/vericargo_extension/blob/main/cloud-run-api/src/lightweight-parser.js): `cloud-run-api/src/lightweight-parser.js`
- [SI/BL comparison](https://github.com/yucodings/vericargo_extension/blob/main/cloud-run-api/src/document-comparison.js): `cloud-run-api/src/document-comparison.js`
- [BL draft service](https://github.com/yucodings/vericargo_extension/blob/main/cloud-run-api/src/bl-draft-service.js): `cloud-run-api/src/bl-draft-service.js`

### External services

- **Firestore**
- **Gmail**
- **Google OAuth**
- **Gemini**

### Other components

- **Reviewer**

## Connections

- Reviewer → Side panel: reviews in
- Side panel → Cloud client: requests
- Background worker → Cloud client: syncs via
- Cloud client → HTTP API: calls API
- HTTP API → OAuth service: dispatches auth
- HTTP API → Gmail service: dispatches mail
- HTTP API → Email classification: dispatches classification
- HTTP API → Document processing: dispatches processing
- OAuth service → Google OAuth: authorizes with
- OAuth service → Crypto utilities: encrypts tokens
- OAuth service → Firestore: stores credentials
- Gmail service → Gmail: syncs and labels
- Gmail service → Firestore: stores cases
- Email classification → Gemini: classifies with
- Email classification → Firestore: stores results
- Email classification → Gmail service: loads attachments
- Document processing → Gmail service: loads attachments
- Document processing → Lightweight parser: parses documents
- Document processing → SI/BL comparison: compares fields
- Document processing → Firestore: stores outcomes
- HTTP API → BL draft service: dispatches drafts
- BL draft service → Firestore: reads case data