# amit4517187/med-verify-authenticator architecture

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

- Interactive diagram: https://gitdiagram.com/amit4517187/med-verify-authenticator
- Repository: https://github.com/amit4517187/med-verify-authenticator

## Overview

1. **Repository shape**
   - This repo is primarily a **frontend-first medicine verification PWA** with supporting data/automation scripts.
   - The main application lives at the repo root under `src/`.
   - A second client app exists in `MedVerifyApp/`, with its own screens, services, and `app.json`, suggesting a separate mobile-style or packaged client alongside the main web PWA.

2. **Primary user-facing app**
   - The root app is a **React 18 + Vite + TypeScript** SPA/PWA.
   - Navigation is page-based, with routes like `Index`, `ScanPage`, `ResultsPage`, `HistoryPage`-style flows, plus informational/legal pages: `AboutPage`, `PrivacyPage`, `TermsPage`, and `CrisisInsights`.
   - `src/main.tsx` bootstraps the app, `src/App.tsx` defines the shell, and `src/pages/*` are the route boundaries.

3. **Core verification flow**
   - The central flow is: **scan or enter medicine data → verify → show results**.
   - `src/components/BarcodeScanner.tsx` handles barcode capture.
   - `src/pages/ScanPage.tsx` and `src/pages/ResultsPage.tsx` are the main interaction and output surfaces.
   - `src/types/verification.ts` defines the data model for the verification result, keeping the flow strongly typed.

4. **Online vs offline architecture**
   - The app is explicitly **offline-capable**.
   - Online verification likely goes through `src/services/api.ts` to an external backend/API contract described in `docs/api-contract.md`.
   - Offline fallback uses `src/utils/offlineSearch.ts`, `src/services/storage.ts`, and the shipped dataset in `public/medicine_db.json`.
   - This creates a clear boundary: **cloud-assisted verification when available, local registry lookup when not**.

5. **Local data and persistence**
   - The app stores or caches user/session data through `src/services/storage.ts`, which is the browser-side persistence boundary.
   - The local medicine registry is prepackaged in `public/medicine_db.json`, allowing verification without network access.
   - The README’s “offline-first” design implies browser storage and cache are used to preserve recent state/history across sessions.

6. **Shared UI and shell components**
   - The app shell is built from reusable components in `src/components/`.
   - `Navbar`, `Footer`, `NavLink`, `InstallPWA`, `MaintenanceBanner`, and `GlobalErrorBoundary` define the main UI framing and runtime safety boundaries.
   - The `src/components/ui/` directory is a large shadcn/ui-style design system used across pages for consistent primitives.

7. **State, localization, and device adaptation**
   - `src/contexts/LanguageContext.tsx` provides app-wide language switching, supporting bilingual behavior.
   - `src/hooks/use-mobile.tsx` indicates responsive/device-aware UI behavior.
   - `src/index.css` and `tailwind.config.ts` establish the visual system, while `ScrollReveal` adds lightweight motion effects.

8. **PWA/runtime concerns**
   - The application is designed to be installable and resilient as a PWA.
   - `InstallPWA` is the user-facing install prompt, and the README calls out service-worker/offline behavior.
   - `vercel.json`, `vite.config.ts`, and `public/robots.txt` show this is meant to be deployed as a static frontend with edge-friendly hosting.

9. **Secondary `MedVerifyApp/` client**
   - `MedVerifyApp/` is a separate app structure with `App.tsx`, `index.ts`, `app.json`, screens, contexts, services, and types.
   - Its `screen`-oriented structure (`HomeScreen`, `ScanScreen`, `ResultsScreen`, etc.) and `app.json` suggest a distinct client packaging target, likely mobile-oriented.
   - It mirrors the same domain flow as the root app: language context, storage/API services, and verification-result types.

10. **Data preparation and maintenance pipeline**
   - The repo includes the raw/derived medicine dataset artifacts: `master_medicines_enriched.csv`, `public/medicine_db.json`, and `scratch/convert_db.py`.
   - `scripts/cdsco_monitor.py`, `scripts/db_immortality.py`, and `scripts/processed_pdfs.json` suggest an external update pipeline that refreshes or validates the medicine registry from regulatory sources.
   - These scripts form a **build/maintenance subsystem** separate from the runtime app.

11. **Security and operational boundaries**
   - `docs/SECURITY_ARCHITECTURE.md` and `docs/api-contract.md` document the security model and backend interaction boundary.
   - `.github/workflows/daily_ban_check.yml` indicates scheduled automation for regulatory/status monitoring.
   - `src/components/GlobalErrorBoundary.tsx` and `src/components/MaintenanceBanner.tsx` provide runtime safeguards and degraded-mode messaging in the UI.

12. **Testing and quality**
   - `src/test/ResultFlow.test.tsx` and `src/test/setup.ts` show the primary tested path is the verification result flow.
   - `vitest.config.ts` and the Vite/TypeScript config files define the frontend test/build toolchain.

13. **External services and missing backend**
   - The README describes external backend services such as **Groq API, OCR, BigQuery, and HuggingFace Spaces**, but that backend is not present in this repo.
   - For an architecture diagram, treat the backend as an **external verification/AI service layer** connected only through the frontend API boundary in `src/services/api.ts` and the documented contract.

Main entry points: [`src/App.tsx`](https://github.com/amit4517187/med-verify-authenticator/blob/main/src/App.tsx) (App shell), [`src/pages`](https://github.com/amit4517187/med-verify-authenticator/tree/main/src/pages) (Pages), [`src/utils/offlineSearch.ts`](https://github.com/amit4517187/med-verify-authenticator/blob/main/src/utils/offlineSearch.ts) (Offline search), [`MedVerifyApp/src/screens/ScanScreen.tsx`](https://github.com/amit4517187/med-verify-authenticator/blob/main/MedVerifyApp/src/screens/ScanScreen.tsx) (Scan screen)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root_app["Root PWA"]
  node_main_bootstrap["Bootstraps<br/>entry<br/>[main.tsx]"]
  node_app_shell["App shell<br/>[App.tsx]"]
  node_route_pages["Pages<br/>routes"]
  node_scan_ui["Scan flow<br/>capture-ui<br/>[BarcodeScanner.tsx]"]
  node_results_ui["Results flow<br/>outcome-ui<br/>[ResultsPage.tsx]"]
  node_verification_model["Verification types<br/>domain-model<br/>[verification.ts]"]
  node_offline_lookup["Offline search<br/>local-retrieval<br/>[offlineSearch.ts]"]
  node_storage_layer[("Storage<br/>persistence")]
  node_shared_ui["UI system<br/>design-system"]
  node_language_ctx(("Language<br/>global-state"))
  node_pwa_runtime["PWA runtime<br/>runtime-support"]
  node_root_styles["Styling<br/>theme<br/>[index.css]"]
  node_verify_dataset[("Medicine DB<br/>local-dataset<br/>[medicine_db.json]")]
end

subgraph group_mobile_client["MedVerifyApp"]
  node_mobile_app["Mobile shell<br/>entry<br/>[App.tsx]"]
  node_mobile_home["Home screen<br/>[HomeScreen.tsx]"]
  node_mobile_scan["Scan screen<br/>[ScanScreen.tsx]"]
  node_mobile_results["Results screen<br/>[ResultsScreen.tsx]"]
  node_mobile_services["Mobile services<br/>client-services"]
  node_mobile_types["Mobile types<br/>client-model<br/>[index.ts]"]
end

subgraph group_pipeline["Data pipeline"]
  node_convert_script["Convert DB<br/>data-prep<br/>[convert_db.py]"]
  node_monitor_script["CDSCO monitor<br/>registry-monitor<br/>[cdsco_monitor.py]"]
  node_immortality_script["DB upkeep<br/>registry-maintenance<br/>[db_immortality.py]"]
  node_archive_json["Processed PDFs<br/>artifact"]
end

subgraph group_docs_ops["Docs and ops"]
  node_api_contract["API contract<br/>architecture-doc<br/>[api-contract.md]"]
  node_security_doc["Security arch<br/>architecture-doc"]
  node_daily_check["Daily check<br/>workflow"]
end

subgraph group_external["External services"]
  node_external_backend[("Backend APIs<br/>external-services")]
end

node_main_bootstrap -->|"mounts"| node_app_shell
node_app_shell -->|"routes to"| node_route_pages
node_route_pages -->|"uses"| node_scan_ui
node_route_pages -->|"shows"| node_results_ui
node_scan_ui -->|"produces"| node_verification_model
node_results_ui -->|"consumes"| node_verification_model
node_verification_model -->|"supports"| node_offline_lookup
node_offline_lookup -->|"reads"| node_verify_dataset
node_offline_lookup -->|"caches in"| node_storage_layer
node_app_shell -->|"provides"| node_language_ctx
node_app_shell -->|"composes"| node_shared_ui
node_app_shell -->|"hardens"| node_pwa_runtime
node_app_shell -->|"styles with"| node_root_styles
node_mobile_app -->|"starts at"| node_mobile_home
node_mobile_home -->|"navigates to"| node_mobile_scan
node_mobile_scan -->|"yields"| node_mobile_results
node_mobile_scan -->|"calls"| node_mobile_services
node_mobile_results -->|"formats"| node_mobile_types
node_convert_script -->|"builds"| node_verify_dataset
node_monitor_script -->|"tracks"| node_archive_json
node_immortality_script -->|"maintains"| node_verify_dataset
node_daily_check -->|"runs"| node_monitor_script
node_api_contract -->|"defines boundary"| node_external_backend
node_security_doc -->|"constrains"| node_api_contract
node_security_doc -->|"covers"| node_external_backend
node_pwa_runtime -->|"supports"| node_storage_layer

click node_main_bootstrap "https://github.com/amit4517187/med-verify-authenticator/blob/main/src/main.tsx"
click node_app_shell "https://github.com/amit4517187/med-verify-authenticator/blob/main/src/App.tsx"
click node_route_pages "https://github.com/amit4517187/med-verify-authenticator/tree/main/src/pages"
click node_scan_ui "https://github.com/amit4517187/med-verify-authenticator/blob/main/src/components/BarcodeScanner.tsx"
click node_results_ui "https://github.com/amit4517187/med-verify-authenticator/blob/main/src/pages/ResultsPage.tsx"
click node_verification_model "https://github.com/amit4517187/med-verify-authenticator/blob/main/src/types/verification.ts"
click node_offline_lookup "https://github.com/amit4517187/med-verify-authenticator/blob/main/src/utils/offlineSearch.ts"
click node_shared_ui "https://github.com/amit4517187/med-verify-authenticator/tree/main/src/components/ui"
click node_language_ctx "https://github.com/amit4517187/med-verify-authenticator/blob/main/src/contexts/LanguageContext.tsx"
click node_pwa_runtime "https://github.com/amit4517187/med-verify-authenticator/tree/main/src/components"
click node_root_styles "https://github.com/amit4517187/med-verify-authenticator/blob/main/src/index.css"
click node_verify_dataset "https://github.com/amit4517187/med-verify-authenticator/blob/main/public/medicine_db.json"
click node_mobile_app "https://github.com/amit4517187/med-verify-authenticator/blob/main/MedVerifyApp/App.tsx"
click node_mobile_home "https://github.com/amit4517187/med-verify-authenticator/blob/main/MedVerifyApp/src/screens/HomeScreen.tsx"
click node_mobile_scan "https://github.com/amit4517187/med-verify-authenticator/blob/main/MedVerifyApp/src/screens/ScanScreen.tsx"
click node_mobile_results "https://github.com/amit4517187/med-verify-authenticator/blob/main/MedVerifyApp/src/screens/ResultsScreen.tsx"
click node_mobile_services "https://github.com/amit4517187/med-verify-authenticator/tree/main/MedVerifyApp/src/services"
click node_mobile_types "https://github.com/amit4517187/med-verify-authenticator/blob/main/MedVerifyApp/src/types/index.ts"
click node_convert_script "https://github.com/amit4517187/med-verify-authenticator/blob/main/scratch/convert_db.py"
click node_monitor_script "https://github.com/amit4517187/med-verify-authenticator/blob/main/scripts/cdsco_monitor.py"
click node_immortality_script "https://github.com/amit4517187/med-verify-authenticator/blob/main/scripts/db_immortality.py"
click node_archive_json "https://github.com/amit4517187/med-verify-authenticator/blob/main/scripts/processed_pdfs.json"
click node_api_contract "https://github.com/amit4517187/med-verify-authenticator/blob/main/docs/api-contract.md"
click node_security_doc "https://github.com/amit4517187/med-verify-authenticator/blob/main/docs/SECURITY_ARCHITECTURE.md"
click node_daily_check "https://github.com/amit4517187/med-verify-authenticator/blob/main/.github/workflows/daily_ban_check.yml"

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_main_bootstrap,node_app_shell,node_route_pages,node_scan_ui,node_results_ui,node_verification_model,node_offline_lookup,node_storage_layer,node_shared_ui,node_language_ctx,node_pwa_runtime,node_root_styles,node_verify_dataset toneBlue
class node_mobile_app,node_mobile_home,node_mobile_scan,node_mobile_results,node_mobile_services,node_mobile_types toneAmber
class node_convert_script,node_monitor_script,node_immortality_script,node_archive_json toneMint
class node_api_contract,node_security_doc,node_daily_check toneRose
class node_external_backend toneIndigo
```

## Components

### Root PWA

Primary React/Vite medicine verification app at the repository root.

- [Bootstraps](https://github.com/amit4517187/med-verify-authenticator/blob/main/src/main.tsx): entry · Root React entrypoint that mounts the application. · `src/main.tsx`
- [App shell](https://github.com/amit4517187/med-verify-authenticator/blob/main/src/App.tsx): shell · Top-level application composition and routing shell. · `src/App.tsx`
- [Pages](https://github.com/amit4517187/med-verify-authenticator/tree/main/src/pages): routes · Primary route boundaries for scan, results, history, and legal/info screens. · `src/pages`
- [Scan flow](https://github.com/amit4517187/med-verify-authenticator/blob/main/src/components/BarcodeScanner.tsx): capture-ui · Barcode capture and scan interaction surface. · `src/components/BarcodeScanner.tsx`
- [Results flow](https://github.com/amit4517187/med-verify-authenticator/blob/main/src/pages/ResultsPage.tsx): outcome-ui · Verification result presentation and follow-up state. · `src/pages/ResultsPage.tsx`
- [Verification types](https://github.com/amit4517187/med-verify-authenticator/blob/main/src/types/verification.ts): domain-model · Typed verification result contract shared across the flow. · `src/types/verification.ts`
- [Offline search](https://github.com/amit4517187/med-verify-authenticator/blob/main/src/utils/offlineSearch.ts): local-retrieval · Local fallback lookup against the bundled medicine registry. · `src/utils/offlineSearch.ts`
- **Storage**: persistence · Browser persistence for session state, cache, or history.
- [UI system](https://github.com/amit4517187/med-verify-authenticator/tree/main/src/components/ui): design-system · Reusable shell components and shadcn-style primitives used across the app. · `src/components/ui`
- [Language](https://github.com/amit4517187/med-verify-authenticator/blob/main/src/contexts/LanguageContext.tsx): global-state · App-wide language and localization context. · `src/contexts/LanguageContext.tsx`
- [PWA runtime](https://github.com/amit4517187/med-verify-authenticator/tree/main/src/components): runtime-support · Install prompt, error boundary, maintenance messaging, and motion helpers. · `src/components`
- [Styling](https://github.com/amit4517187/med-verify-authenticator/blob/main/src/index.css): theme · Global CSS and Tailwind theme configuration. · `src/index.css`
- [Medicine DB](https://github.com/amit4517187/med-verify-authenticator/blob/main/public/medicine_db.json): local-dataset · Bundled offline medicine registry shipped with the web app. · `public/medicine_db.json`

### MedVerifyApp

Secondary packaged or mobile-style client with mirrored verification flow.

- [Mobile shell](https://github.com/amit4517187/med-verify-authenticator/blob/main/MedVerifyApp/App.tsx): entry · Secondary packaged client bootstrap and app shell. · `MedVerifyApp/App.tsx`
- [Home screen](https://github.com/amit4517187/med-verify-authenticator/blob/main/MedVerifyApp/src/screens/HomeScreen.tsx): screen · Primary landing screen in the secondary client. · `MedVerifyApp/src/screens/HomeScreen.tsx`
- [Scan screen](https://github.com/amit4517187/med-verify-authenticator/blob/main/MedVerifyApp/src/screens/ScanScreen.tsx): screen · Capture screen in the secondary client. · `MedVerifyApp/src/screens/ScanScreen.tsx`
- [Results screen](https://github.com/amit4517187/med-verify-authenticator/blob/main/MedVerifyApp/src/screens/ResultsScreen.tsx): screen · Outcome screen in the secondary client. · `MedVerifyApp/src/screens/ResultsScreen.tsx`
- [Mobile services](https://github.com/amit4517187/med-verify-authenticator/tree/main/MedVerifyApp/src/services): client-services · Secondary client API and storage boundaries. · `MedVerifyApp/src/services`
- [Mobile types](https://github.com/amit4517187/med-verify-authenticator/blob/main/MedVerifyApp/src/types/index.ts): client-model · Shared type definitions for the secondary client. · `MedVerifyApp/src/types/index.ts`

### Data pipeline

Dataset preparation, registry refresh, and monitoring scripts.

- [Convert DB](https://github.com/amit4517187/med-verify-authenticator/blob/main/scratch/convert_db.py): data-prep · Transforms source medicine data into the packaged registry format. · `scratch/convert_db.py`
- [CDSCO monitor](https://github.com/amit4517187/med-verify-authenticator/blob/main/scripts/cdsco_monitor.py): registry-monitor · Automated script for regulatory source monitoring and updates. · `scripts/cdsco_monitor.py`
- [DB upkeep](https://github.com/amit4517187/med-verify-authenticator/blob/main/scripts/db_immortality.py): registry-maintenance · Maintenance script for keeping the medicine registry current or resilient. · `scripts/db_immortality.py`
- [Processed PDFs](https://github.com/amit4517187/med-verify-authenticator/blob/main/scripts/processed_pdfs.json): artifact · Processed document index used by the maintenance pipeline. · `scripts/processed_pdfs.json`

### Docs and ops

Architecture docs, deployment settings, and scheduled automation.

- [API contract](https://github.com/amit4517187/med-verify-authenticator/blob/main/docs/api-contract.md): architecture-doc · Documented frontend/backend contract for online verification. · `docs/api-contract.md`
- [Security arch](https://github.com/amit4517187/med-verify-authenticator/blob/main/docs/SECURITY_ARCHITECTURE.md): architecture-doc · Security model and boundary documentation. · `docs/SECURITY_ARCHITECTURE.md`
- [Daily check](https://github.com/amit4517187/med-verify-authenticator/blob/main/.github/workflows/daily_ban_check.yml): workflow · Scheduled automation for ban or status monitoring. · `.github/workflows/daily_ban_check.yml`

### External services

Backend APIs and third-party services used through the frontend contract.

- **Backend APIs**: external-services · External verification, OCR, and AI services referenced by the frontend contract.

## Connections

- Bootstraps → App shell: mounts · Application entrypoint renders the shell.
- App shell → Pages: routes to · Shell delegates user navigation to page boundaries.
- Pages → Scan flow: uses · Scan page uses barcode capture for input.
- Pages → Results flow: shows · Results page presents verification output.
- Scan flow → Verification types: produces · Captured medicine data is shaped into the verification model.
- Results flow → Verification types: consumes · Result screens render the typed verification payload.
- Verification types → Offline search: supports · Typed verification data can be checked against local registry data.
- Offline search → Medicine DB: reads · Offline search queries the bundled registry.
- Offline search → Storage: caches in · Local results and session state are persisted browser-side.
- App shell → Language: provides · Language context is available throughout the app shell.
- App shell → UI system: composes · Shell and pages are built from shared UI primitives.
- App shell → PWA runtime: hardens · Runtime components provide install, error, and degraded-mode support.
- App shell → Styling: styles with · Global styling and theme configuration shape the UI.
- Mobile shell → Home screen: starts at · Secondary client boots into its home screen.
- Home screen → Scan screen: navigates to · Home screen leads into scanning.
- Scan screen → Results screen: yields · Scanning leads into result presentation.
- Scan screen → Mobile services: calls · Secondary client uses its own service layer.
- Results screen → Mobile types: formats · Results screen renders shared client types.
- Convert DB → Medicine DB: builds · Data conversion produces the packaged registry artifact.
- CDSCO monitor → Processed PDFs: tracks · Monitoring persists processed source document state.
- DB upkeep → Medicine DB: maintains · Maintenance scripts support registry freshness and durability.
- Daily check → CDSCO monitor: runs · Scheduled workflow triggers the monitoring job.
- API contract → Backend APIs: defines boundary · The documented contract governs external service interaction.
- Security arch → API contract: constrains · Security architecture informs the external contract.
- Security arch → Backend APIs: covers · Security boundaries include third-party service interactions.
- PWA runtime → Storage: supports · Runtime components depend on browser persistence for resilience.
