# Progressive Web App (PWA) Guide (Hausa)

🌐 **Languages:** 🇺🇸 [English](../../../../guides/PWA_GUIDE.md) · 🇪🇹 [am](../../../am/docs/guides/PWA_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/guides/PWA_GUIDE.md) · 🇦🇿 [az](../../../az/docs/guides/PWA_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/guides/PWA_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/guides/PWA_GUIDE.md) · 🇧🇦 [bs](../../../bs/docs/guides/PWA_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/guides/PWA_GUIDE.md) · 🇩🇰 [da](../../../da/docs/guides/PWA_GUIDE.md) · 🇩🇪 [de](../../../de/docs/guides/PWA_GUIDE.md) · 🇬🇷 [el](../../../el/docs/guides/PWA_GUIDE.md) · 🇪🇸 [es](../../../es/docs/guides/PWA_GUIDE.md) · 🇪🇪 [et](../../../et/docs/guides/PWA_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/guides/PWA_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/guides/PWA_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/guides/PWA_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/guides/PWA_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/guides/PWA_GUIDE.md) · 🇮🇱 [he](../../../he/docs/guides/PWA_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/guides/PWA_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/guides/PWA_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/guides/PWA_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/guides/PWA_GUIDE.md) · 🇮🇩 [id](../../../id/docs/guides/PWA_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/guides/PWA_GUIDE.md) · 🇮🇹 [it](../../../it/docs/guides/PWA_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/guides/PWA_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/guides/PWA_GUIDE.md) · 🇰🇭 [km](../../../km/docs/guides/PWA_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/guides/PWA_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/guides/PWA_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/guides/PWA_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/guides/PWA_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/guides/PWA_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/guides/PWA_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/guides/PWA_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/guides/PWA_GUIDE.md) · 🇲🇲 [my](../../../my/docs/guides/PWA_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/guides/PWA_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/guides/PWA_GUIDE.md) · 🇳🇴 [no](../../../no/docs/guides/PWA_GUIDE.md) · 🇮🇳 [or](../../../or/docs/guides/PWA_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/guides/PWA_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/guides/PWA_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/guides/PWA_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/guides/PWA_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/PWA_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/guides/PWA_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/guides/PWA_GUIDE.md) · 🇱🇰 [si](../../../si/docs/guides/PWA_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/guides/PWA_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/guides/PWA_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/guides/PWA_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/guides/PWA_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/guides/PWA_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/guides/PWA_GUIDE.md) · 🇮🇳 [te](../../../te/docs/guides/PWA_GUIDE.md) · 🇹🇭 [th](../../../th/docs/guides/PWA_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/guides/PWA_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/PWA_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/guides/PWA_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/guides/PWA_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/guides/PWA_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/guides/PWA_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/PWA_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/PWA_GUIDE.md)

---

OmniRoute na zuwa a matsayin cikakkiyar Progressive Web App da za a iya girkawa. Lokacin da ka shiga dashboard daga kowace manhajar binciken yanar gizo ta wayar hannu — Android (Chrome) ko iOS (Safari) — za ka iya yin "Ƙara zuwa Fuskar Farko" domin samun ƙwarewa irin ta manhajar asali ba tare da buƙatar kantin manhajoji ba.

## Mene Ne PWA?

Progressive Web App tana mayar da dashboard na yanar gizon OmniRoute zuwa wani abu mai kama da aiki irin na manhajar wayar hannu ta asali. Bayan an girka ta, tana:

- Buɗewa daga fuskar farko da tambarinta na musamman
- Buɗewa a cikakken allo — babu mashigin adireshin burauza ko mahaɗin shafuka
- Aiki ba tare da intanet ba tare da keɓantaccen shafin haɗin yanar gizo
- Adana kadarorin tsaye a cache domin saurin lodawa
- Goyon bayan yanayin tsaye da na kwance

## Girkawa

### Android (Chrome)

1. Buɗe dashboard na OmniRoute a Chrome: `http://YOUR_IP:20128`
2. Chrome zai nuna tutar **"Ƙara OmniRoute zuwa Fuskar farko"** ta atomatik, ko kuma:
   - Taɓa menu na **⋮** (dige uku) → **"Ƙara zuwa Fuskar farko"** ko **"Girka manhaja"**
3. Tabbatar da saƙon neman izini
4. OmniRoute zai bayyana a fuskar farko a matsayin manhaja mai zaman kanta

### iOS (Safari)

1. Buɗe dashboard na OmniRoute a Safari: `http://YOUR_IP:20128`
2. Taɓa maɓallin **Rabawa** (akwati mai kibiya)
3. Gungura ƙasa sannan ka taɓa **"Ƙara zuwa Fuskar Farko"**
4. Sanya mata suna (tsohon zaɓi shi ne "OmniRoute") sannan ka taɓa **Ƙara**
5. OmniRoute zai bayyana a fuskar farko tare da tambarin manhajar

### Kwamfutar Tebur (Chrome / Edge)

1. Buɗe dashboard na OmniRoute
2. Danna **tambarin girkawa** a mashigin adireshi (ko ⋮ → "Girka OmniRoute...")
3. Tabbatar da saƙon neman izini
4. OmniRoute zai buɗe a matsayin taga mai zaman kanta — babu shafuka, babu mashigin adireshi

## Fasali

### Ƙwarewar Cikakken Allo

An saita manifest da `display: "fullscreen"`, wanda ke nufin manhajar da aka girka tana amfani da dukkan allo — babu kayan aikin burauza, kuma babu karo da mashigin matsayi. Wannan yana sa dashboard ya ji kamar manhajar asali ta gaske.

### Goyon Bayan Aiki Ba Tare da Intanet Ba

OmniRoute ya ƙunshi service worker (`sw.js`) wanda ke samar da adanawa a cache cikin basira:

| Nau'in Kadara                                                | Dabara                                        | Halayya                                                                                                      |
| ------------------------------------------------------------ | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Tsarin Asalin Manhaja**                                    | Cache da farko                                | Ana riga-kafin adana `/`, `/offline`, manifest, da tambura a cache yayin girkawa                             |
| **Kadarorin tsaye** (CSS, JS, hotuna, fonts)                 | Hanyar sadarwa da farko tare da komawa cache  | Yana ɗauko sabbi daga hanyar sadarwa; yana komawa cache idan babu intanet                                    |
| **Kunshin Next.js** (`/_next/`)                              | Hanyar sadarwa da farko tare da sabunta cache | Yana ɗauko daga hanyar sadarwa kuma yana sabunta cache; yana bayar da sigar da ke cache idan babu intanet    |
| **Buƙatun kewayawa**                                         | Ketarewa (ba a taɓa tsoma baki ba)            | Burauza ce ke kula da komawar HTTP/3→HTTP/2; matacciyar soket ɗin QUIC ba dole ta zama `Response.error()` ba |
| **Hanyoyin API / dashboard** (`/api/`, `/a2a`, `/dashboard`) | Ketarewa (ba a taɓa adanawa a cache ba)       | Koyaushe yana zuwa kai tsaye zuwa uwar garken — service worker ba ya taɓa tsoma baki                         |

### Shafin Rashin Intanet

Lokacin da hanyar sadarwa ba ta samuwa kuma mai amfani ya kewaya zuwa sabon shafi, service worker zai bayar da keɓantaccen shafin `/offline` wanda:

- Ke nuna bayyanannen saƙon **"Matsalar Haɗin Yanar Gizo"**
- Ke nuna **alama ta halin haɗuwa/rashin haɗuwa** kai tsaye wadda ke sabuntawa a ainihin lokaci
- Ke samar da maɓallin **"Sake Gwada Haɗawa"** domin sake loda shafin idan haɗin yanar gizo ya dawo
- Ke haɗawa zuwa **Shafin Matsayi** domin binciken matsala

### Tambarin Manhaja

OmniRoute yana samar da tamburan da aka inganta domin kowane dandali:

| Fayil                  | Girma            | Inda Ake Amfani Da Shi                 |
| ---------------------- | ---------------- | -------------------------------------- |
| `icon-512.png`         | 512×512          | Saƙon girkawa na Android, allon farawa |
| `apple-touch-icon.png` | 180×180          | Tambarin fuskar farko na iOS           |
| `icon-192.svg`         | 192×192 (vector) | Tambarin daidaitawa na Android         |
| `apple-touch-icon.svg` | 180×180 (vector) | Madadin Apple                          |
| `favicon.svg`          | Vector           | Shafukan burauza                       |
| `favicon.ico`          | Girma iri-iri    | Tsofaffin burauzozi                    |

### Rijista Ta Atomatik

Ana rijistar service worker ta atomatik ta hanyar ɓangaren `<PwaRegister />` da ke cikin tushen layout. Ba a buƙatar wani mataki daga mai amfani — manhajar za ta zama abin girkawa da zarar burauza ta gano ingantaccen manifest da service worker.

## Tsarin Fasaha

### Bayanin Manhajar Yanar Gizo (`manifest.webmanifest`)

Next.js ne ke samar da shi ta hanyar `src/app/manifest.ts`:

```json
{
  "name": "OmniRoute",
  "short_name": "OmniRoute",
  "description": "OmniRoute is an AI gateway for multi-provider LLMs. One endpoint for all your AI providers.",
  "start_url": "/",
  "scope": "/",
  "display": "fullscreen",
  "orientation": "any",
  "background_color": "#0b0f1a",
  "theme_color": "#0b0f1a",
  "icons": [
    {
      "src": "/icon-512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any maskable"
    },
    { "src": "/apple-touch-icon.png", "sizes": "180x180", "type": "image/png" }
  ]
}
```

### Service Worker (`public/sw.js`)

Service worker na asali (ba tare da dogaro da wani framework ba) wanda yake da:

- **Matakin girkawa**: Yana riga-kafin adana ginshiƙin manhajar a cache (tushen shafi, shafin rashin haɗi, manifest, da gumaka)
- **Matakin kunnawa**: Yana share tsofaffin nau'ikan cache kuma ya mallaki dukkan clients
- **Matakin fetch**: Hanyar turawa mai kaifin basira bisa nau'in buƙata (navigation, static asset, API)
- **Sarrafa nau'in cache**: `omniroute-pwa-v3` — ƙara wannan don tilasta sabon cache bayan sabuntawa

### Metadata na Layout (`src/app/layout.tsx`)

Layout na tushe yana samar da duk meta tags da ake buƙata don bin ƙa'idodin PWA:

- Mahaɗin `manifest` zuwa `/manifest.webmanifest`
- `apple-web-app-capable: true` don yanayin standalone na iOS
- `apple-web-app-status-bar-style: black-translucent`
- `mobile-web-app-capable: yes` don Android Chrome
- `theme-color: #0b0f1a`
- `viewport-fit: cover` don nunawa daga gefe zuwa gefe

### Bangare: `PwaRegister`

Yana a `src/shared/components/PwaRegister.tsx`, wannan bangaren client:

1. Yana aiki lokacin mount (a ɓangaren client kawai)
2. Yana bincika goyon bayan `serviceWorker` a browser
3. Yana rajistar `/sw.js` a ɓoye (ana yin watsi da kurakurai don kada su hana manhajar aiki)
4. Ba ya nuna komai (`return null`) — bangare ne da aikinsa kawai shi ne haifar da side effect

## Amfani Tare da Termux (Android)

Lokacin gudanar da OmniRoute a Android ta hanyar Termux, PWA yana aiki ba tare da matsala ba:

1. Fara OmniRoute a Termux: `npx omniroute`
2. Buɗe Chrome a wayar guda: `http://localhost:20128`
3. Girka PWA ta hanyar "Ƙara zuwa Fuskar Farko"
4. PWA yana haɗuwa da uwar garken Termux na cikin gida — komai yana gudana a kan na'urar

Wannan haɗin yana nufin wayarka ta Android ita ce **uwar garken** (Termux), kuma ita ce **client** (PWA) — cikakkiyar ƙofar AI mai zaman kanta.

## Amfani Daga Wasu Na'urori

Girka PWA a kowace na'ura da browser ɗinta zai iya shiga uwar garken OmniRoute ɗinka:

- **Wata waya/tablet**: Je zuwa `http://PHONE_IP:20128` sannan ka girka PWA
- **Laptop**: Buɗe Chrome/Edge sannan ka girka shi a matsayin PWA na desktop
- **Smart TV mai browser**: Shiga dashboard a cikakken allo

## Keɓancewa

### Sunan Instance

Taken PWA yana bin saitin **Instance Name** daga `Dashboard → Settings`. Idan ka sake sanya wa instance ɗinka suna zuwa "Ƙofar AI Ta", PWA da aka girka zai nuna wannan suna.

### Favicon na Musamman

Idan ka ɗora favicon na musamman ta hanyar `Dashboard → Settings`, gunkin PWA a desktop zai nuna gunkin da aka keɓance. Gumakan fuskar farko ta wayar hannu suna amfani da fayilolin `icon-512.png` da `apple-touch-icon.png` da aka riga aka gina.

## Iyakoki

- **Babu sanarwar turawa** — Service worker ɗin bai aiwatar da Push API ba. Maimakon haka, manhajar Electron ce ke sarrafa sanarwar.
- **Babu aiki tare a bango** — Ba a jera ayyukan da aka yi ba tare da intanet ba domin sake aiwatar da su. PWA ɗin galibi na duba dashboard ne.
- **Ƙuntatawar iOS** — Safari a kan iOS ba ya goyon bayan dukkan fasalolin PWA (misali, sai an yi buƙatar girkawa da hannu, sannan service workers masu aiki a bango suna da iyaka).
- **Girman cache** — Service worker ɗin yana adana static assets kawai a cache. Ba a taɓa adana manyan response payloads daga hanyoyin `/api/` a cache ba.
- **Keɓaɓɓun gumaka a wayar hannu** — Canza favicon a cikin saituna ba ya sabunta gunkin allon gida a wayar hannu (wannan yana buƙatar sake samar da gumakan PWA).

## Bayanin Fayiloli

| Fayil                                   | Manufa                                                                    |
| --------------------------------------- | ------------------------------------------------------------------------- |
| `src/app/manifest.ts`                   | Hanyar manifest ta Next.js (tana samar da `manifest.webmanifest`)         |
| `public/sw.js`                          | Service worker mai tsarin adanawa a cache                                 |
| `src/shared/components/PwaRegister.tsx` | Client component da ke rajistar service worker                            |
| `src/app/offline/page.tsx`              | Shafin madadin lokacin babu intanet tare da mai nuna halin haɗi kai tsaye |
| `src/app/layout.tsx`                    | Root layout mai metadata na PWA (apple-web-app, theme-color, da sauransu) |
| `public/icon-512.png`                   | Gunkin PNG mai girman 512×512 (Android, allon farawa)                     |
| `public/apple-touch-icon.png`           | Gunkin PNG mai girman 180×180 (allon gida na iOS)                         |
| `public/icon-192.svg`                   | Gunkin SVG mai girman 192×192 (Android adaptive)                          |
| `public/apple-touch-icon.svg`           | Gunkin SVG mai girman 180×180 (madadin Apple)                             |