# Progressive Web App (PWA) Guide (Kiswahili)

🌐 **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) · 🇳🇬 [ha](../../../ha/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) · 🇮🇳 [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 hutolewa kama Progressive Web App inayoweza kusakinishwa kikamilifu. Unapofungua dashibodi kutoka kwenye kivinjari chochote cha simu — Android (Chrome) au iOS (Safari) — unaweza kutumia chaguo la "Ongeza kwenye Skrini ya Mwanzo" na kupata matumizi yanayofanana na programu asilia bila kuhitaji duka la programu.

## PWA Ni Nini?

Progressive Web App hubadilisha dashibodi ya wavuti ya OmniRoute kuwa kitu kinachoonekana na kutenda kama programu asilia ya simu. Baada ya kusakinishwa, programu hiyo:

- Huzinduliwa kutoka kwenye skrini yako ya mwanzo ikiwa na ikoni yake
- Hufunguka katika hali ya skrini nzima — bila upau wa anwani wa kivinjari au kiolesura cha vichupo
- Hufanya kazi bila muunganisho wa intaneti kwa kutumia ukurasa maalumu wa muunganisho
- Huhifadhi rasilimali tuli kwenye akiba ili zipakie kwa haraka zaidi
- Hutumia mielekeo ya wima na mlalo

## Usakinishaji

### Android (Chrome)

1. Fungua dashibodi ya OmniRoute katika Chrome: `http://YOUR_IP:20128`
2. Chrome itaonyesha bango la **"Ongeza OmniRoute kwenye Skrini ya mwanzo"** kiotomatiki, au:
   - Gusa menyu ya **⋮** (nukta tatu) → **"Ongeza kwenye Skrini ya mwanzo"** au **"Sakinisha programu"**
3. Thibitisha ombi
4. OmniRoute itaonekana kwenye skrini yako ya mwanzo kama programu inayojitegemea

### iOS (Safari)

1. Fungua dashibodi ya OmniRoute katika Safari: `http://YOUR_IP:20128`
2. Gusa kitufe cha **Shiriki** (kisanduku chenye mshale)
3. Sogeza chini na uguse **"Ongeza kwenye Skrini ya Mwanzo"**
4. Ipe jina (jina chaguomsingi ni "OmniRoute") na uguse **Ongeza**
5. OmniRoute itaonekana kwenye skrini yako ya mwanzo ikiwa na ikoni ya programu

### Kompyuta ya Mezani (Chrome / Edge)

1. Fungua dashibodi ya OmniRoute
2. Bofya **ikoni ya kusakinisha** katika upau wa anwani (au ⋮ → "Sakinisha OmniRoute...")
3. Thibitisha ombi
4. OmniRoute itafunguka kama dirisha linalojitegemea — bila vichupo wala upau wa anwani

## Vipengele

### Matumizi ya Skrini Nzima

Manifest imesanidiwa kwa `display: "fullscreen"`, kumaanisha kuwa programu iliyosakinishwa hutumia skrini nzima — bila kiolesura cha kivinjari wala kufunika upau wa hali. Hii huifanya dashibodi ihisi kama programu asilia.

### Usaidizi wa Hali Isiyo na Muunganisho

OmniRoute inajumuisha service worker (`sw.js`) inayowezesha uhifadhi mahiri kwenye akiba:

| Aina ya Rasilimali                                          | Mkakati                                    | Tabia                                                                                                                             |
| ----------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| **Gamba la Programu**                                       | Akiba kwanza                               | `/`, `/offline`, manifest na ikoni huhifadhiwa mapema kwenye akiba wakati wa usakinishaji                                         |
| **Rasilimali tuli** (CSS, JS, picha, fonti)                 | Mtandao kwanza, akiba kama mbadala         | Hupata nakala mpya kutoka kwenye mtandao; hutumia akiba ikiwa hakuna muunganisho                                                  |
| **Vifurushi vya Next.js** (`/_next/`)                       | Mtandao kwanza pamoja na kusasisha akiba   | Hupata kutoka kwenye mtandao na kusasisha akiba; hutoa toleo lililohifadhiwa ikiwa hakuna muunganisho                             |
| **Maombi ya uelekezaji**                                    | Hupitwa (hayazuiliwi kamwe)                | Kivinjari hudhibiti urejeaji mbadala wa HTTP/3→HTTP/2; soketi ya QUIC isiyofanya kazi haipaswi kubadilika kuwa `Response.error()` |
| **API / njia za dashibodi** (`/api/`, `/a2a`, `/dashboard`) | Hupitwa (hazihifadhiwi kamwe kwenye akiba) | Daima huenda moja kwa moja kwenye seva — hazizuiliwi kamwe na service worker                                                      |

### Ukurasa wa Hali Isiyo na Muunganisho

Wakati mtandao haupatikani na mtumiaji anapoelekea kwenye ukurasa mpya, service worker hutoa ukurasa maalumu wa `/offline` ambao:

- Huonyesha ujumbe wazi wa **"Tatizo la Muunganisho"**
- Huonyesha **kiashirio cha hali ya kuwa mtandaoni/nje ya mtandao** kinachosasishwa papo hapo
- Hutoa kitufe cha **"Jaribu Kuunganisha Tena"** ili kupakia upya muunganisho unaporejea
- Huunganisha kwenye **Ukurasa wa Hali** kwa ajili ya uchunguzi

### Ikoni za Programu

OmniRoute hutoa ikoni zilizoboreshwa kwa kila jukwaa:

| Faili                  | Ukubwa          | Inatumiwa Na                                        |
| ---------------------- | --------------- | --------------------------------------------------- |
| `icon-512.png`         | 512×512         | Ombi la usakinishaji la Android, skrini ya uzinduzi |
| `apple-touch-icon.png` | 180×180         | Ikoni ya skrini ya mwanzo ya iOS                    |
| `icon-192.svg`         | 192×192 (vekta) | Ikoni inayobadilika ya Android                      |
| `apple-touch-icon.svg` | 180×180 (vekta) | Ikoni mbadala ya Apple                              |
| `favicon.svg`          | Vekta           | Vichupo vya kivinjari                               |
| `favicon.ico`          | Saizi nyingi    | Vivinjari vya zamani                                |

### Usajili wa Kiotomatiki

Service worker husajiliwa kiotomatiki kupitia kijenzi cha `<PwaRegister />` katika mpangilio mkuu. Hakuna hatua ya mtumiaji inayohitajika — programu inaweza kusakinishwa mara tu kivinjari kinapotambua manifest halali na service worker.

## Usanifu wa Kiufundi

### Manifesti ya Programu ya Wavuti (`manifest.webmanifest`)

Inazalishwa na Next.js kupitia `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 ya kawaida (isiyo na utegemezi wa mfumo wowote) yenye:

- **Awamu ya usakinishaji**: Huhifadhi mapema kwenye akiba kiunzi cha programu (mzizi, ukurasa wa nje ya mtandao, manifesti na ikoni)
- **Awamu ya uanzishaji**: Huondoa matoleo ya zamani ya akiba na kudai wateja wote
- **Awamu ya uchotaji**: Uelekezaji mahiri kulingana na aina ya ombi (urambazaji, rasilimali tuli, API)
- **Uwekaji matoleo wa akiba**: `omniroute-pwa-v3` — ongeza toleo hili ili kulazimisha akiba mpya wakati wa kusasisha

### Metadata ya Mpangilio (`src/app/layout.tsx`)

Mpangilio mkuu hutoa tagi zote za meta zinazohitajika kwa utiifu wa PWA:

- Kiungo cha `manifest` kwenda `/manifest.webmanifest`
- `apple-web-app-capable: true` kwa modi huru ya iOS
- `apple-web-app-status-bar-style: black-translucent`
- `mobile-web-app-capable: yes` kwa Chrome ya Android
- `theme-color: #0b0f1a`
- `viewport-fit: cover` kwa uonyeshaji kutoka ukingo hadi ukingo

### Kijenzi: `PwaRegister`

Kikiwa katika `src/shared/components/PwaRegister.tsx`, kijenzi hiki cha mteja:

1. Huendeshwa kinapopachikwa (upande wa mteja pekee)
2. Hukagua usaidizi wa `serviceWorker` katika kivinjari
3. Husajili `/sw.js` kimyakimya (hitilafu hupuuzwa ili kuepuka kuzuia programu)
4. Hakionyeshi chochote (`return null`) — ni kijenzi chenye athari tu

## Kutumia Pamoja na Termux (Android)

Unapoendesha OmniRoute kwenye Android kupitia Termux, PWA hufanya kazi kwa urahisi:

1. Anzisha OmniRoute katika Termux: `npx omniroute`
2. Fungua Chrome kwenye simu hiyo hiyo: `http://localhost:20128`
3. Sakinisha PWA kupitia "Ongeza kwenye Skrini ya Mwanzo"
4. PWA huunganishwa na seva ya Termux ya ndani — kila kitu huendeshwa kwenye kifaa

Mchanganyiko huu unamaanisha kuwa simu yako ya Android ni **seva** (Termux) na pia **mteja** (PWA) — lango kamili la AI linalojitegemea.

## Kutumia Kutoka kwenye Vifaa Vingine

Sakinisha PWA kwenye kifaa chochote chenye ufikiaji wa kivinjari kwenye seva yako ya OmniRoute:

- **Simu/kompyuta kibao nyingine**: Nenda kwenye `http://PHONE_IP:20128` na usakinishe PWA
- **Kompyuta mpakato**: Fungua Chrome/Edge na uisakinishe kama PWA ya eneo-kazi
- **Televisheni mahiri yenye kivinjari**: Fikia dashibodi katika skrini nzima

## Ubinafsishaji

### Jina la Instansi

Kichwa cha PWA huheshimu mpangilio wa **Jina la Instansi** kutoka `Dashboard → Settings`. Ukibadilisha jina la instansi yako kuwa "Lango Langu la AI", PWA iliyosakinishwa itaonyesha jina hilo.

### Favicon Maalum

Ukipakia favicon maalum kupitia `Dashboard → Settings`, ikoni ya PWA kwenye eneo-kazi itaonyesha ikoni hiyo maalum. Ikoni za skrini ya mwanzo ya vifaa vya mkononi hutumia faili zilizotengenezwa mapema za `icon-512.png` na `apple-touch-icon.png`.

## Vikwazo

- **Hakuna arifa za kutumwa** — Service worker haitekelezi Push API. Badala yake, arifa hushughulikiwa na programu ya Electron.
- **Hakuna usawazishaji wa chinichini** — Vitendo vya nje ya mtandao haviwekwi kwenye foleni ili vitekelezwe tena. PWA kimsingi ni kitazamaji cha dashibodi.
- **Vikwazo vya iOS** — Safari kwenye iOS haitumii vipengele vyote vya PWA (kwa mfano, vidokezo vya usakinishaji ni vya kufanywa mwenyewe, na service workers za chinichini zina mipaka).
- **Ukubwa wa kache** — Service worker huhifadhi kwenye kache rasilimali tuli pekee. Mizigo mikubwa ya majibu kutoka kwa njia za `/api/` kamwe haihifadhiwi kwenye kache.
- **Ikoni maalum kwenye simu** — Kubadilisha favicon kwenye mipangilio hakusasishi ikoni ya skrini ya nyumbani kwenye simu (hili linahitaji kuzalisha upya ikoni za PWA).

## Marejeleo ya Faili

| Faili                                   | Madhumuni                                                                   |
| --------------------------------------- | --------------------------------------------------------------------------- |
| `src/app/manifest.ts`                   | Njia ya manifest ya Next.js (huzalisha `manifest.webmanifest`)              |
| `public/sw.js`                          | Service worker yenye mantiki ya uhifadhi kwenye kache                       |
| `src/shared/components/PwaRegister.tsx` | Kijenzi cha mteja kinachosajili service worker                              |
| `src/app/offline/page.tsx`              | Ukurasa mbadala wa nje ya mtandao wenye kiashirio cha hali ya moja kwa moja |
| `src/app/layout.tsx`                    | Mpangilio mkuu wenye metadata ya PWA (apple-web-app, theme-color, n.k.)     |
| `public/icon-512.png`                   | Ikoni ya PNG ya 512×512 (Android, skrini ya uzinduzi)                       |
| `public/apple-touch-icon.png`           | Ikoni ya PNG ya 180×180 (skrini ya nyumbani ya iOS)                         |
| `public/icon-192.svg`                   | Ikoni ya SVG ya 192×192 (ikoni inayobadilika ya Android)                    |
| `public/apple-touch-icon.svg`           | Ikoni ya SVG ya 180×180 (mbadala wa Apple)                                  |