How amit4517187/med-verify-authenticator works
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: App.tsx App shell · pages Pages · offlineSearch.ts Offline search · ScanScreen.tsx Scan screen
Components 27
Root PWA
Primary React/Vite medicine verification app at the repository root.
- Bootstraps · Root React entrypoint that mounts the application.
src/main.tsx - App shell · Top-level application composition and routing shell.
src/App.tsx - Pages · Primary route boundaries for scan, results, history, and legal/info screens.
src/pages - Scan flow · Barcode capture and scan interaction surface.
src/components/BarcodeScanner.tsx - Results flow · Verification result presentation and follow-up state.
src/pages/ResultsPage.tsx - Verification types · Typed verification result contract shared across the flow.
src/types/verification.ts - Offline search · Local fallback lookup against the bundled medicine registry.
src/utils/offlineSearch.ts - Storage · Browser persistence for session state, cache, or history.
- UI system · Reusable shell components and shadcn-style primitives used across the app.
src/components/ui - Language · App-wide language and localization context.
src/contexts/LanguageContext.tsx - PWA runtime · Install prompt, error boundary, maintenance messaging, and motion helpers.
src/components - Styling · Global CSS and Tailwind theme configuration.
src/index.css - Medicine DB · 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 · Secondary packaged client bootstrap and app shell.
MedVerifyApp/App.tsx - Home screen · Primary landing screen in the secondary client.
MedVerifyApp/src/screens/HomeScreen.tsx - Scan screen · Capture screen in the secondary client.
MedVerifyApp/src/screens/ScanScreen.tsx - Results screen · Outcome screen in the secondary client.
MedVerifyApp/src/screens/ResultsScreen.tsx - Mobile services · Secondary client API and storage boundaries.
MedVerifyApp/src/services - Mobile types · Shared type definitions for the secondary client.
MedVerifyApp/src/types/index.ts
Data pipeline
Dataset preparation, registry refresh, and monitoring scripts.
- Convert DB · Transforms source medicine data into the packaged registry format.
scratch/convert_db.py - CDSCO monitor · Automated script for regulatory source monitoring and updates.
scripts/cdsco_monitor.py - DB upkeep · Maintenance script for keeping the medicine registry current or resilient.
scripts/db_immortality.py - Processed PDFs · Processed document index used by the maintenance pipeline.
scripts/processed_pdfs.json
Docs and ops
Architecture docs, deployment settings, and scheduled automation.
- API contract · Documented frontend/backend contract for online verification.
docs/api-contract.md - Security arch · Security model and boundary documentation.
docs/SECURITY_ARCHITECTURE.md - Daily check · 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 verification, OCR, and AI services referenced by the frontend contract.
Connections 26
- 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.