# Progressive Web App (PWA) Guide (Filipino)

🌐 **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) · 🇵🇱 [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)

---

Ang OmniRoute ay ibinibigay bilang isang ganap na mai-install na Progressive Web App. Kapag in-access mo ang dashboard mula sa anumang mobile browser — Android (Chrome) o iOS (Safari) — maaari mo itong **"Idagdag sa Home Screen"** at magkaroon ng karanasang tulad ng isang native app nang hindi nangangailangan ng app store.

## Ano ang PWA?

Ginagawang parang isang native mobile app ng Progressive Web App ang web dashboard ng OmniRoute. Kapag na-install na, ito ay:

- Nailulunsad mula sa iyong home screen gamit ang sarili nitong icon
- Nagbubukas nang fullscreen — walang address bar ng browser o tab UI
- Gumagana offline gamit ang nakalaang pahina para sa konektibidad
- Nagka-cache ng mga static asset para sa mas mabilis na pag-load
- Sinusuportahan ang parehong portrait at landscape na oryentasyon

## Pag-install

### Android (Chrome)

1. Buksan ang dashboard ng OmniRoute sa Chrome: `http://YOUR_IP:20128`
2. Awtomatikong ipapakita ng Chrome ang banner na **"Idagdag ang OmniRoute sa Home screen"**, o:
   - I-tap ang menu na **⋮** (tatlong tuldok) → **"Idagdag sa Home screen"** o **"I-install ang app"**
3. Kumpirmahin ang prompt
4. Lalabas ang OmniRoute sa iyong home screen bilang isang standalone app

### iOS (Safari)

1. Buksan ang dashboard ng OmniRoute sa Safari: `http://YOUR_IP:20128`
2. I-tap ang button na **Ibahagi** (kahon na may arrow)
3. Mag-scroll pababa at i-tap ang **"Idagdag sa Home Screen"**
4. Pangalanan ito (ang default ay "OmniRoute") at i-tap ang **Idagdag**
5. Lalabas ang OmniRoute sa iyong home screen kasama ang icon ng app

### Desktop (Chrome / Edge)

1. Buksan ang dashboard ng OmniRoute
2. I-click ang **icon ng pag-install** sa address bar (o ⋮ → "I-install ang OmniRoute...")
3. Kumpirmahin ang prompt
4. Magbubukas ang OmniRoute bilang isang standalone na window — walang mga tab at walang address bar

## Mga Feature

### Fullscreen na Karanasan

Naka-configure ang manifest gamit ang `display: "fullscreen"`, na nangangahulugang ginagamit ng naka-install na app ang buong screen — walang mga kontrol ng browser at walang pag-o-overlap sa status bar. Dahil dito, tunay na parang native app ang dashboard.

### Suporta sa Offline

May kasamang service worker (`sw.js`) ang OmniRoute na nagbibigay ng matalinong pag-cache:

| Uri ng Asset                                                    | Diskarte                               | Gawi                                                                                                                   |
| --------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **App Shell**                                                   | Cache-first                            | Paunang naka-cache ang `/`, `/offline`, manifest, at mga icon sa pag-install                                           |
| **Mga static asset** (CSS, JS, mga larawan, mga font)           | Network-first na may cache fallback    | Kumukuha ng bago mula sa network; bumabalik sa cache kapag offline                                                     |
| **Mga bundle ng Next.js** (`/_next/`)                           | Network-first na may cache update      | Kumukuha mula sa network at ina-update ang cache; naghahatid ng naka-cache na bersyon kapag offline                    |
| **Mga navigation request**                                      | Bypass (hindi kailanman ini-intercept) | Browser ang namamahala sa HTTP/3→HTTP/2 fallback; hindi dapat maging `Response.error()` ang isang patay na QUIC socket |
| **Mga ruta ng API / dashboard** (`/api/`, `/a2a`, `/dashboard`) | Bypass (hindi kailanman kino-cache)    | Palaging direktang pumupunta sa server — hindi kailanman ini-intercept ng service worker                               |

### Offline na Pahina

Kapag hindi available ang network at nag-navigate ang user sa isang bagong pahina, maghahatid ang service worker ng nakalaang pahinang `/offline` na:

- Nagpapakita ng malinaw na mensaheng **"Problema sa Konektibidad"**
- Nagpapakita ng live na **online/offline na status indicator** na nag-a-update nang real time
- Nagbibigay ng button na **"Subukang Kumonekta Muli"** upang mag-reload kapag bumalik ang konektibidad
- Nagli-link sa **Pahina ng Status** para sa mga diagnostic

### Mga Icon ng App

Nagbibigay ang OmniRoute ng mga icon na na-optimize para sa bawat platform:

| File                   | Laki             | Ginagamit Ng                                    |
| ---------------------- | ---------------- | ----------------------------------------------- |
| `icon-512.png`         | 512×512          | Prompt sa pag-install ng Android, splash screen |
| `apple-touch-icon.png` | 180×180          | Icon sa home screen ng iOS                      |
| `icon-192.svg`         | 192×192 (vector) | Adaptive icon ng Android                        |
| `apple-touch-icon.svg` | 180×180 (vector) | Fallback ng Apple                               |
| `favicon.svg`          | Vector           | Mga tab ng browser                              |
| `favicon.ico`          | Multi-size       | Mga legacy browser                              |

### Awtomatikong Pagpaparehistro

Awtomatikong nirerehistro ang service worker sa pamamagitan ng component na `<PwaRegister />` sa root layout. Walang kinakailangang gawin ang user — maaari nang i-install ang app sa sandaling matukoy ng browser ang wastong manifest at service worker.

## Teknikal na Arkitektura

### Web App Manifest (`manifest.webmanifest`)

Binuo ng Next.js sa pamamagitan ng `src/app/manifest.ts`:

```json
{
  "name": "OmniRoute",
  "short_name": "OmniRoute",
  "description": "Ang OmniRoute ay isang AI gateway para sa mga multi-provider na LLM. Isang endpoint para sa lahat ng iyong AI provider.",
  "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`)

Isang vanilla service worker (walang dependency sa framework) na may:

- **Yugto ng pag-install**: Paunang kina-cache ang app shell (root, offline page, manifest, mga icon)
- **Yugto ng pag-activate**: Nililinis ang mga lumang bersyon ng cache at kinukuha ang kontrol sa lahat ng client
- **Yugto ng pag-fetch**: Matalinong pagruruta batay sa uri ng request (navigation, static asset, API)
- **Pagbe-bersyon ng cache**: `omniroute-pwa-v3` — dagdagan ito upang sapilitang gumamit ng bagong cache kapag nag-update

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

Ibinibigay ng root layout ang lahat ng meta tag na kinakailangan para sa pagsunod sa mga pamantayan ng PWA:

- Link na `manifest` patungo sa `/manifest.webmanifest`
- `apple-web-app-capable: true` para sa standalone mode ng iOS
- `apple-web-app-status-bar-style: black-translucent`
- `mobile-web-app-capable: yes` para sa Android Chrome
- `theme-color: #0b0f1a`
- `viewport-fit: cover` para sa edge-to-edge na pag-render

### Component: `PwaRegister`

Matatagpuan sa `src/shared/components/PwaRegister.tsx`, ang client component na ito ay:

1. Tumatakbo kapag na-mount (sa client-side lamang)
2. Tinitingnan kung sinusuportahan ng browser ang `serviceWorker`
3. Tahimik na nirerehistro ang `/sw.js` (hindi pinapansin ang mga error upang maiwasang ma-block ang app)
4. Walang nire-render (`return null`) — isa itong component na para lamang sa side effect

## Paggamit Kasama ang Termux (Android)

Kapag pinapatakbo ang OmniRoute sa Android sa pamamagitan ng Termux, gumagana nang maayos ang PWA:

1. Simulan ang OmniRoute sa Termux: `npx omniroute`
2. Buksan ang Chrome sa parehong telepono: `http://localhost:20128`
3. I-install ang PWA sa pamamagitan ng "Idagdag sa Home Screen"
4. Kumokonekta ang PWA sa lokal na Termux server — lahat ay tumatakbo mismo sa device

Nangangahulugan ang kombinasyong ito na ang iyong Android phone ay parehong **server** (Termux) at **client** (PWA) — isang kumpleto at self-contained na AI gateway.

## Paggamit Mula sa Ibang Mga Device

I-install ang PWA sa anumang device na may access sa pamamagitan ng browser sa iyong OmniRoute server:

- **Ibang telepono/tablet**: Pumunta sa `http://PHONE_IP:20128` at i-install ang PWA
- **Laptop**: Buksan ang Chrome/Edge at i-install ito bilang desktop PWA
- **Smart TV na may browser**: I-access ang dashboard nang fullscreen

## Pag-customize

### Pangalan ng Instance

Sinusunod ng pamagat ng PWA ang setting na **Pangalan ng Instance** mula sa `Dashboard → Mga Setting`. Kung papalitan mo ang pangalan ng iyong instance ng "Aking AI Gateway", iyon ang pangalang ipapakita ng naka-install na PWA.

### Custom na Favicon

Kung mag-a-upload ka ng custom na favicon sa pamamagitan ng `Dashboard → Mga Setting`, ipapakita ng icon ng PWA sa desktop ang custom na icon. Ginagamit ng mga icon sa home screen ng mobile ang mga paunang binuong file na `icon-512.png` at `apple-touch-icon.png`.

## Mga Limitasyon

- **Walang mga push notification** — Hindi ipinapatupad ng service worker ang Push API. Sa halip, ang mga notification ay pinangangasiwaan ng Electron app.
- **Walang background sync** — Hindi inilalagay sa pila ang mga offline na pagkilos upang muling isagawa. Pangunahing ginagamit ang PWA bilang viewer ng dashboard.
- **Mga paghihigpit sa iOS** — Hindi sinusuportahan ng Safari sa iOS ang lahat ng feature ng PWA (hal., manu-mano ang mga prompt sa pag-install, at limitado ang mga background service worker).
- **Laki ng cache** — Mga static asset lamang ang kina-cache ng service worker. Hindi kailanman kina-cache ang malalaking response payload mula sa mga route na `/api/`.
- **Mga custom na icon sa mobile** — Hindi ina-update ng pagpapalit ng favicon sa mga setting ang icon sa home screen sa mobile (nangangailangan ito ng muling pagbuo ng mga PWA icon).

## Sanggunian ng mga File

| File                                    | Layunin                                                             |
| --------------------------------------- | ------------------------------------------------------------------- |
| `src/app/manifest.ts`                   | Next.js manifest route (bumubuo ng `manifest.webmanifest`)          |
| `public/sw.js`                          | Service worker na may caching logic                                 |
| `src/shared/components/PwaRegister.tsx` | Client component na nagrerehistro sa service worker                 |
| `src/app/offline/page.tsx`              | Offline fallback page na may live status indicator                  |
| `src/app/layout.tsx`                    | Root layout na may PWA metadata (apple-web-app, theme-color, atbp.) |
| `public/icon-512.png`                   | 512×512 PNG icon (Android, splash screen)                           |
| `public/apple-touch-icon.png`           | 180×180 PNG icon (home screen ng iOS)                               |
| `public/icon-192.svg`                   | 192×192 SVG icon (Android adaptive)                                 |
| `public/apple-touch-icon.svg`           | 180×180 SVG icon (Apple fallback)                                   |