# nischalacharya060/nepal-license-checker architecture

> Architecture diagram of the GitHub repository nischalacharya060/nepal-license-checker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nischalacharya060/nepal-license-checker
- Repository: https://github.com/nischalacharya060/nepal-license-checker

## Overview

Nepal License Checker is a bilingual web app for checking whether a Nepal driving license has been printed, with indexed and live DOTM lookup paths. Its broader product includes saved-user alerts, OCR, developer APIs, administration, and offline PWA support. The main lookup flow and several internal dependencies are evidenced by excerpts or README statements; unsampled capability links are omitted where their runtime wiring cannot be verified.

Main entry points: [`src/app/api/license/route.ts`](https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/app/api/license/route.ts) (Lookup endpoint), [`src/lib/turso.ts`](https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/lib/turso.ts) (Turso index), [`src/app/api/user/licenses/route.ts`](https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/app/api/user/licenses/route.ts) (Saved licenses), [`src/lib/developerAuth.ts`](https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/lib/developerAuth.ts) (Developer access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_lookup["License lookup"]
  node_home["Lookup experience<br/>[page.tsx]"]
  node_form["License form<br/>[LicenseForm.tsx]"]
  node_lookup_api["Lookup endpoint<br/>[route.ts]"]
  node_input_utils["Input sanitization<br/>[sanitize.ts]"]
  node_rate_limit["Rate limiting<br/>[rateLimit.ts]"]
  node_search_log["Search logging<br/>[searchLogger.ts]"]
  node_result["Lookup result<br/>[LicenseResult.tsx]"]
end

subgraph group_data["Data and alerts"]
  node_database[("Turso index<br/>[turso.ts]")]
  node_scraper["PDF scraper<br/>[scraper.js]"]
  node_sync_runner["Data sync runner<br/>[update-data.js]"]
  node_saved_licenses["Saved licenses<br/>[route.ts]"]
  node_notification_service["Email alert service<br/>[notifications.js]"]
  node_notification_lib["Notification access<br/>[notifications.ts]"]
  node_email["Email delivery<br/>[email.ts]"]
end

subgraph group_accounts["Accounts and APIs"]
  node_user_auth["User authentication<br/>[userAuth.ts]"]
  node_developer_api["Developer API<br/>[route.ts]"]
  node_developer_auth["Developer access<br/>[developerAuth.ts]"]
  node_developer_analytics["Developer analytics<br/>[route.ts]"]
end

subgraph group_operations["Operations and extensions"]
  node_admin["Admin console<br/>[page.tsx]"]
  node_ocr["License OCR<br/>[route.ts]"]
  node_ocr_scanner["OCR scanner"]
  node_testimonials["Testimonials<br/>[route.ts]"]
  node_pwa["Offline PWA<br/>[sw.js]"]
  node_meta_api["Site metadata<br/>[route.ts]"]
  node_meta_cache["Metadata cache<br/>[metaCache.ts]"]
  node_system_mode["System mode<br/>[systemMode.ts]"]
end

node_visitor(("License holder"))
node_dotm["DOTM records"]

node_visitor -->|"opens"| node_home
node_home -->|"presents"| node_form
node_form -->|"requests status"| node_lookup_api
node_lookup_api -->|"sanitizes input"| node_input_utils
node_lookup_api -->|"checks limits"| node_rate_limit
node_lookup_api -->|"queries index"| node_database
node_lookup_api -->|"scrapes on miss"| node_dotm
node_lookup_api -->|"logs searches"| node_search_log
node_lookup_api -->|"validates keys"| node_developer_auth
node_lookup_api -->|"checks user"| node_user_auth
node_lookup_api -->|"returns status"| node_result
node_visitor -->|"manages alerts"| node_saved_licenses
node_saved_licenses -->|"authenticates user"| node_user_auth
node_saved_licenses -->|"reads and writes"| node_database
node_saved_licenses -.->|"manages subscriptions"| node_notification_lib
node_notification_lib -->|"delegates operations"| node_notification_service
node_notification_lib -->|"provides database"| node_database
node_notification_service -.->|"sends alerts"| node_email
node_scraper -->|"fetches PDFs"| node_dotm
node_sync_runner -.->|"runs sync"| node_scraper
node_scraper -->|"upserts records"| node_database
node_visitor -.->|"requests API access"| node_developer_api
node_developer_api -.->|"manages keys"| node_developer_auth
node_developer_auth -->|"persists access data"| node_database
node_developer_analytics -->|"verifies session"| node_developer_auth
node_developer_analytics -->|"queries metrics"| node_database
node_visitor -.->|"scans license"| node_ocr_scanner
node_ocr_scanner -.->|"submits image"| node_ocr
node_admin -.->|"manages content"| node_testimonials
node_admin -.->|"manages records"| node_database
node_home -.->|"loads metadata"| node_meta_api
node_meta_api -->|"reads and caches"| node_meta_cache
node_meta_api -->|"loads mode"| node_system_mode
node_system_mode -->|"reads and writes"| node_database
node_visitor -->|"uses offline app"| node_pwa

click node_home "https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/app/page.tsx"
click node_form "https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/components/LicenseForm.tsx"
click node_lookup_api "https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/app/api/license/route.ts"
click node_input_utils "https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/utils/sanitize.ts"
click node_rate_limit "https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/lib/rateLimit.ts"
click node_search_log "https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/lib/searchLogger.ts"
click node_result "https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/components/LicenseResult.tsx"
click node_database "https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/lib/turso.ts"
click node_scraper "https://github.com/nischalacharya060/nepal-license-checker/blob/master/scripts/scraper.js"
click node_sync_runner "https://github.com/nischalacharya060/nepal-license-checker/blob/master/scripts/update-data.js"
click node_saved_licenses "https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/app/api/user/licenses/route.ts"
click node_notification_service "https://github.com/nischalacharya060/nepal-license-checker/blob/master/scripts/notifications.js"
click node_notification_lib "https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/lib/notifications.ts"
click node_email "https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/lib/email.ts"
click node_user_auth "https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/lib/userAuth.ts"
click node_developer_api "https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/app/api/developer/keys/route.ts"
click node_developer_auth "https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/lib/developerAuth.ts"
click node_developer_analytics "https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/app/api/developer/analytics/route.ts"
click node_admin "https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/app/admin/page.tsx"
click node_ocr "https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/app/api/ocr/route.ts"
click node_ocr_scanner "https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/components/OcrScannerModal.tsx"
click node_testimonials "https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/app/api/testimonials/route.ts"
click node_pwa "https://github.com/nischalacharya060/nepal-license-checker/blob/master/public/sw.js"
click node_meta_api "https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/app/api/meta/route.ts"
click node_meta_cache "https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/lib/metaCache.ts"
click node_system_mode "https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/lib/systemMode.ts"

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_home,node_form,node_lookup_api,node_input_utils,node_rate_limit,node_search_log,node_result toneBlue
class node_database,node_scraper,node_sync_runner,node_saved_licenses,node_notification_service,node_notification_lib,node_email toneAmber
class node_user_auth,node_developer_api,node_developer_auth,node_developer_analytics toneMint
class node_admin,node_ocr,node_ocr_scanner,node_testimonials,node_pwa,node_meta_api,node_meta_cache,node_system_mode toneRose
class node_visitor,node_dotm toneIndigo
```

## Components

### License lookup

- [Lookup experience](https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/app/page.tsx): `src/app/page.tsx`
- [License form](https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/components/LicenseForm.tsx): `src/components/LicenseForm.tsx`
- [Lookup endpoint](https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/app/api/license/route.ts): `src/app/api/license/route.ts`
- [Input sanitization](https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/utils/sanitize.ts): `src/utils/sanitize.ts`
- [Rate limiting](https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/lib/rateLimit.ts): `src/lib/rateLimit.ts`
- [Search logging](https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/lib/searchLogger.ts): `src/lib/searchLogger.ts`
- [Lookup result](https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/components/LicenseResult.tsx): `src/components/LicenseResult.tsx`

### Data and alerts

- [Turso index](https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/lib/turso.ts): `src/lib/turso.ts`
- [PDF scraper](https://github.com/nischalacharya060/nepal-license-checker/blob/master/scripts/scraper.js): `scripts/scraper.js`
- [Data sync runner](https://github.com/nischalacharya060/nepal-license-checker/blob/master/scripts/update-data.js): `scripts/update-data.js`
- [Saved licenses](https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/app/api/user/licenses/route.ts): `src/app/api/user/licenses/route.ts`
- [Email alert service](https://github.com/nischalacharya060/nepal-license-checker/blob/master/scripts/notifications.js): `scripts/notifications.js`
- [Notification access](https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/lib/notifications.ts): `src/lib/notifications.ts`
- [Email delivery](https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/lib/email.ts): `src/lib/email.ts`

### Accounts and APIs

- [User authentication](https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/lib/userAuth.ts): `src/lib/userAuth.ts`
- [Developer API](https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/app/api/developer/keys/route.ts): `src/app/api/developer/keys/route.ts`
- [Developer access](https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/lib/developerAuth.ts): `src/lib/developerAuth.ts`
- [Developer analytics](https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/app/api/developer/analytics/route.ts): `src/app/api/developer/analytics/route.ts`

### Operations and extensions

- [Admin console](https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/app/admin/page.tsx): `src/app/admin/page.tsx`
- [License OCR](https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/app/api/ocr/route.ts): `src/app/api/ocr/route.ts`
- [OCR scanner](https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/components/OcrScannerModal.tsx): `src/components/OcrScannerModal.tsx`
- [Testimonials](https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/app/api/testimonials/route.ts): `src/app/api/testimonials/route.ts`
- [Offline PWA](https://github.com/nischalacharya060/nepal-license-checker/blob/master/public/sw.js): `public/sw.js`
- [Site metadata](https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/app/api/meta/route.ts): `src/app/api/meta/route.ts`
- [Metadata cache](https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/lib/metaCache.ts): `src/lib/metaCache.ts`
- [System mode](https://github.com/nischalacharya060/nepal-license-checker/blob/master/src/lib/systemMode.ts): `src/lib/systemMode.ts`

### Other components

- **License holder**
- **DOTM records**

## Connections

- License holder → Lookup experience: opens (evidence: `README.md`)
- Lookup experience → License form: presents (evidence: `README.md`)
- License form → Lookup endpoint: requests status (evidence: `README.md`)
- Lookup endpoint → Input sanitization: sanitizes input (evidence: `src/app/api/license/route.ts`)
- Lookup endpoint → Rate limiting: checks limits (evidence: `src/app/api/license/route.ts`)
- Lookup endpoint → Turso index: queries index (evidence: `README.md`)
- Lookup endpoint → DOTM records: scrapes on miss (evidence: `README.md`)
- Lookup endpoint → Search logging: logs searches (evidence: `src/app/api/license/route.ts`)
- Lookup endpoint → Developer access: validates keys (evidence: `src/app/api/license/route.ts`)
- Lookup endpoint → User authentication: checks user (evidence: `src/app/api/license/route.ts`)
- Lookup endpoint → Lookup result: returns status (evidence: `README.md`)
- License holder → Saved licenses: manages alerts (evidence: `README.md`)
- Saved licenses → User authentication: authenticates user (evidence: `src/app/api/user/licenses/route.ts`)
- Saved licenses → Turso index: reads and writes (evidence: `src/app/api/user/licenses/route.ts`)
- Saved licenses → Notification access: manages subscriptions (evidence: `src/app/api/user/licenses/route.ts`)
- Notification access → Email alert service: delegates operations (evidence: `src/lib/notifications.ts`)
- Notification access → Turso index: provides database (evidence: `src/lib/notifications.ts`)
- Email alert service → Email delivery: sends alerts
- PDF scraper → DOTM records: fetches PDFs (evidence: `README.md`)
- Data sync runner → PDF scraper: runs sync
- PDF scraper → Turso index: upserts records (evidence: `README.md`)
- License holder → Developer API: requests API access
- Developer API → Developer access: manages keys
- Developer access → Turso index: persists access data (evidence: `src/lib/developerAuth.ts`)
- Developer analytics → Developer access: verifies session (evidence: `src/app/api/developer/analytics/route.ts`)
- Developer analytics → Turso index: queries metrics (evidence: `src/app/api/developer/analytics/route.ts`)
- License holder → OCR scanner: scans license
- OCR scanner → License OCR: submits image
- Admin console → Testimonials: manages content
- Admin console → Turso index: manages records
- Lookup experience → Site metadata: loads metadata
- Site metadata → Metadata cache: reads and caches (evidence: `src/app/api/meta/route.ts`)
- Site metadata → System mode: loads mode (evidence: `src/app/api/meta/route.ts`)
- System mode → Turso index: reads and writes (evidence: `src/lib/systemMode.ts`)
- License holder → Offline PWA: uses offline app (evidence: `README.md`)
