# Progressive Web App (PWA) Guide (አማርኛ)

🌐 **Languages:** 🇺🇸 [English](../../../../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) · 🇰🇪 [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 ሙሉ በሙሉ ሊጫን የሚችል Progressive Web App ሆኖ ይቀርባል። ዳሽቦርዱን ከማንኛውም የሞባይል አሳሽ — Android (Chrome) ወይም iOS (Safari) — ሲከፍቱ "ወደ መነሻ ማያ ገጽ ማከል" ይችላሉ፤ ምንም የመተግበሪያ መደብር ሳያስፈልግ እንደ ቤተኛ መተግበሪያ ያለ ተሞክሮ ያገኛሉ።

## PWA ምንድን ነው?

Progressive Web App የOmniRoute የድር ዳሽቦርድን ቤተኛ የሞባይል መተግበሪያ የሚመስልና እንደዚያው የሚሰማ ያደርገዋል። ከተጫነ በኋላ፦

- በራሱ አዶ ከመነሻ ማያ ገጽዎ ይጀምራል
- ሙሉ ማያ ገጽ ላይ ይከፈታል — የአሳሽ አድራሻ አሞሌ ወይም የትር UI የለም
- ለግንኙነት የተዘጋጀ ገጽ በመጠቀም ከመስመር ውጭ ይሰራል
- ፈጣን ጭነት እንዲኖር የማይለወጡ ሀብቶችን በመሸጎጫ ያከማቻል
- ቁመታዊና አግድማ አቀማመጦችን ይደግፋል

## ጭነት

### Android (Chrome)

1. የOmniRoute ዳሽቦርድን Chrome ውስጥ ይክፈቱ፦ `http://YOUR_IP:20128`
2. Chrome የ**"OmniRouteን ወደ መነሻ ማያ ገጽ አክል"** ማስታወቂያን በራስ-ሰር ያሳያል፤ ካልሆነ፦
   - የ**⋮** ምናሌን (ሦስት ነጥቦች) ይንኩ → **"ወደ መነሻ ማያ ገጽ አክል"** ወይም **"መተግበሪያውን ጫን"**
3. ጥያቄውን ያረጋግጡ
4. OmniRoute እንደ ራሱን የቻለ መተግበሪያ በመነሻ ማያ ገጽዎ ላይ ይታያል

### iOS (Safari)

1. የOmniRoute ዳሽቦርድን Safari ውስጥ ይክፈቱ፦ `http://YOUR_IP:20128`
2. የ**ማጋራት** አዝራሩን (ቀስት ያለው ሳጥን) ይንኩ
3. ወደ ታች ያሸብልሉና **"ወደ መነሻ ማያ ገጽ አክል"**ን ይንኩ
4. ስም ይስጡት (ነባሪው "OmniRoute" ነው) እና **አክል**ን ይንኩ
5. OmniRoute ከመተግበሪያው አዶ ጋር በመነሻ ማያ ገጽዎ ላይ ይታያል

### ዴስክቶፕ (Chrome / Edge)

1. የOmniRoute ዳሽቦርድን ይክፈቱ
2. በአድራሻ አሞሌው ውስጥ ያለውን **የመጫኛ አዶ** ጠቅ ያድርጉ (ወይም ⋮ → "OmniRouteን ጫን...")
3. ጥያቄውን ያረጋግጡ
4. OmniRoute እንደ ራሱን የቻለ መስኮት ይከፈታል — ትሮች የሉም፣ የአድራሻ አሞሌም የለም

## ባህሪያት

### የሙሉ ማያ ገጽ ተሞክሮ

ማኒፌስቱ በ`display: "fullscreen"` ተዋቅሯል፤ ይህም የተጫነው መተግበሪያ ሙሉውን ማያ ገጽ ይጠቀማል ማለት ነው — የአሳሽ መቆጣጠሪያዎች የሉም፣ ከሁኔታ አሞሌው ጋርም መደራረብ የለም። ይህ ዳሽቦርዱ በእውነት ቤተኛ መተግበሪያ እንዲመስል ያደርገዋል።

### ከመስመር ውጭ ድጋፍ

OmniRoute ብልህ የመሸጎጫ አያያዝን የሚያቀርብ service worker (`sw.js`) ያካትታል፦

| የሀብት ዓይነት                                              | ስልት                           | ባህሪ                                                                               |
| ------------------------------------------------------ | ----------------------------- | --------------------------------------------------------------------------------- |
| **የመተግበሪያ መሠረታዊ ክፍል**                                  | መሸጎጫ-ቅድሚያ                     | `/`፣ `/offline`፣ ማኒፌስት እና አዶዎች በጭነት ጊዜ አስቀድመው በመሸጎጫ ይከማቻሉ                         |
| **የማይለወጡ ሀብቶች** (CSS, JS, ምስሎች, ቅርጸ-ቁምፊዎች)             | መጀመሪያ አውታረ መረብ፣ ካልተሳካ መሸጎጫ    | አዲስ ይዘትን ከአውታረ መረቡ ያመጣል፤ ከመስመር ውጭ ከሆነ ወደ መሸጎጫው ይመለሳል                              |
| **Next.js ጥቅሎች** (`/_next/`)                           | መጀመሪያ አውታረ መረብ፣ ከመሸጎጫ ማዘመን ጋር | ከአውታረ መረቡ ያመጣና መሸጎጫውን ያዘምናል፤ ከመስመር ውጭ ከሆነ በመሸጎጫ ያለውን ስሪት ያቀርባል                    |
| **የአሰሳ ጥያቄዎች**                                         | ማለፊያ (ፈጽሞ አይጠለፍም)             | አሳሹ የHTTP/3→HTTP/2 መመለሻን ይቆጣጠራል፤ የሞተ QUIC socket ወደ `Response.error()` መቀየር የለበትም |
| **API / የዳሽቦርድ መስመሮች** (`/api/`, `/a2a`, `/dashboard`) | ማለፊያ (ፈጽሞ በመሸጎጫ አይቀመጥም)       | ሁልጊዜ በቀጥታ ወደ አገልጋዩ ይሄዳል — በservice worker ፈጽሞ አይጠለፍም                              |

### ከመስመር ውጭ ገጽ

አውታረ መረቡ በማይገኝበት ጊዜ አንድ ተጠቃሚ ወደ አዲስ ገጽ ሲሄድ፣ service worker ለዚህ የተዘጋጀውን `/offline` ገጽ ያቀርባል፤ ገጹም፦

- ግልጽ የሆነ **"የግንኙነት ችግር"** መልዕክት ያሳያል
- በቅጽበት የሚዘመን የቀጥታ **በመስመር ላይ/ከመስመር ውጭ ሁኔታ አመልካች** ያሳያል
- ግንኙነቱ ሲመለስ እንደገና ለመጫን የ**"ግንኙነትን እንደገና ሞክር"** አዝራር ያቀርባል
- ለምርመራ ወደ **የሁኔታ ገጽ** ያገናኛል

### የመተግበሪያ አዶዎች

OmniRoute ለእያንዳንዱ መድረክ የተመቻቹ አዶዎችን ያቀርባል፦

| ፋይል                    | መጠን            | የሚጠቀሙበት                   |
| ---------------------- | -------------- | ------------------------- |
| `icon-512.png`         | 512×512        | የAndroid መጫኛ ጥያቄ፣ የመነሻ ገጽ |
| `apple-touch-icon.png` | 180×180        | የiOS መነሻ ማያ ገጽ አዶ         |
| `icon-192.svg`         | 192×192 (ቬክተር) | የAndroid ተስማሚ አዶ          |
| `apple-touch-icon.svg` | 180×180 (ቬክተር) | የApple አማራጭ               |
| `favicon.svg`          | ቬክተር           | የአሳሽ ትሮች                  |
| `favicon.ico`          | ባለብዙ መጠን       | የቆዩ አሳሾች                  |

### ራስ-ሰር ምዝገባ

service worker በዋናው አቀማመጥ ውስጥ ባለው `<PwaRegister />` component በኩል በራስ-ሰር ይመዘገባል። ምንም የተጠቃሚ እርምጃ አያስፈልግም — አሳሹ ትክክለኛውን ማኒፌስት እና service worker እንዳገኘ ወዲያውኑ መተግበሪያው ሊጫን የሚችል ይሆናል።

## ቴክኒካዊ አርክቴክቸር

### የድር መተግበሪያ Manifest (`manifest.webmanifest`)

በNext.js በኩል ከ`src/app/manifest.ts` የሚመነጭ፦

```json
{
  "name": "OmniRoute",
  "short_name": "OmniRoute",
  "description": "OmniRoute ለብዙ አቅራቢዎች LLMs የሚያገለግል AI ጌትዌይ ነው። ለሁሉም የAI አቅራቢዎችዎ አንድ የመገናኛ ነጥብ።",
  "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`)

ምንም የframework ጥገኞች የሌሉት vanilla service worker፣ የሚከተሉት ባህሪያት አሉት፦

- **የመጫን ደረጃ**፦ የመተግበሪያውን shell (root፣ offline ገጽ፣ manifest፣ icons) አስቀድሞ cache ያደርጋል
- **የማግበር ደረጃ**፦ የድሮ cache ስሪቶችን ያጸዳል እና ሁሉንም clients ይቆጣጠራል
- **የFetch ደረጃ**፦ በጥያቄው ዓይነት (navigation፣ static asset፣ API) ላይ የተመሠረተ ብልህ routing
- **የCache ስሪት አስተዳደር**፦ `omniroute-pwa-v3` — ማሻሻያ ሲደረግ አዲስ cache እንዲፈጠር ለማስገደድ ይህን ያሳድጉ

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

Root layout ለPWA ተገዢነት የሚያስፈልጉትን ሁሉንም meta tags ያቀርባል፦

- የ`manifest` link ወደ `/manifest.webmanifest`
- `apple-web-app-capable: true` ለiOS standalone mode
- `apple-web-app-status-bar-style: black-translucent`
- `mobile-web-app-capable: yes` ለAndroid Chrome
- `theme-color: #0b0f1a`
- `viewport-fit: cover` ከጠርዝ እስከ ጠርዝ rendering ለማድረግ

### Component፦ `PwaRegister`

በ`src/shared/components/PwaRegister.tsx` የሚገኘው ይህ client component፦

1. ሲጫን ይሰራል (በclient-side ላይ ብቻ)
2. በbrowser ውስጥ የ`serviceWorker` ድጋፍ መኖሩን ያረጋግጣል
3. `/sw.js`ን ያለምንም ማሳወቂያ ይመዘግባል (መተግበሪያውን እንዳያግዱ errors ችላ ይባላሉ)
4. ምንም ነገር render አያደርግም (`return null`) — side-effect ብቻ ያለው component ነው

## ከTermux (Android) ጋር መጠቀም

OmniRouteን በAndroid ላይ በTermux በኩል ሲያስኬዱ፣ PWAው ያለችግር ይሰራል፦

1. OmniRouteን በTermux ውስጥ ያስጀምሩ፦ `npx omniroute`
2. በዚያው ስልክ ላይ Chromeን ይክፈቱ፦ `http://localhost:20128`
3. PWAውን በ"ወደ መነሻ ማያ ገጽ አክል" በኩል ይጫኑ
4. PWAው ከአካባቢያዊው Termux server ጋር ይገናኛል — ሁሉም ነገር በመሣሪያው ላይ ይሰራል

ይህ ጥምረት የAndroid ስልክዎ **server** (Termux) እና **client** (PWA) ሁለቱም ነው ማለት ነው — ሙሉ በሙሉ ራሱን የቻለ AI gateway።

## ከሌሎች መሣሪያዎች መጠቀም

የOmniRoute serverዎን በbrowser መድረስ በሚችል ማንኛውም መሣሪያ ላይ PWAውን ይጫኑ፦

- **ሌላ ስልክ/ታብሌት**፦ ወደ `http://PHONE_IP:20128` ይሂዱ እና PWAውን ይጫኑ
- **ላፕቶፕ**፦ Chrome/Edgeን ይክፈቱ እና እንደ desktop PWA ይጫኑት
- **Browser ያለው Smart TV**፦ dashboardን በሙሉ ማያ ገጽ ይድረሱበት

## ማበጀት

### የInstance ስም

የPWAው ርዕስ ከ`Dashboard → Settings` የሚገኘውን **Instance Name** setting ያከብራል። Instanceዎን "የእኔ AI Gateway" ብለው ከቀየሩት፣ የተጫነው PWA ያንን ስም ያሳያል።

### ብጁ Favicon

በ`Dashboard → Settings` በኩል ብጁ favicon ከሰቀሉ፣ በdesktop ላይ ያለው የPWA icon ብጁውን icon ያንጸባርቃል። የMobile መነሻ ማያ ገጽ icons ቀድሞ የተዘጋጁትን `icon-512.png` እና `apple-touch-icon.png` files ይጠቀማሉ።

## ገደቦች

- **የPush ማሳወቂያዎች የሉም** — Service worker-ው Push APIን አይተገብርም። በምትኩ ማሳወቂያዎች በElectron መተግበሪያው ይስተናገዳሉ።
- **የበስተጀርባ ማመሳሰል የለም** — ከመስመር ውጭ የሚከናወኑ ድርጊቶች በኋላ እንደገና እንዲፈጸሙ ወረፋ አይያዝላቸውም። PWAው በዋናነት የዳሽቦርድ መመልከቻ ነው።
- **የiOS ገደቦች** — በiOS ላይ ያለው Safari ሁሉንም የPWA ባህሪያት አይደግፍም (ለምሳሌ፣ የመጫን ጥያቄዎች በእጅ መከናወን አለባቸው፣ እንዲሁም የበስተጀርባ service worker-ዎች የተገደቡ ናቸው)።
- **የCache መጠን** — Service worker-ው ቋሚ ሀብቶችን ብቻ cache ያደርጋል። ከ`/api/` መስመሮች የሚመጡ ትላልቅ የምላሽ ውሂብ ጥቅሎች ፈጽሞ cache አይደረጉም።
- **ብጁ አዶዎች በሞባይል ላይ** — በቅንብሮች ውስጥ faviconን መቀየር በሞባይል ላይ ያለውን የመነሻ ማያ ገጽ አዶ አያዘምነውም (ይህ የPWA አዶዎችን እንደገና ማመንጨት ይጠይቃል)።

## የፋይሎች ማጣቀሻ

| ፋይል                                     | ዓላማ                                                           |
| --------------------------------------- | ------------------------------------------------------------- |
| `src/app/manifest.ts`                   | የNext.js manifest መስመር (`manifest.webmanifest`ን ያመነጫል)        |
| `public/sw.js`                          | የcache ማድረግ ሎጂክ ያለው service worker                            |
| `src/shared/components/PwaRegister.tsx` | Service worker-ውን የሚመዘግብ የclient ክፍለ አካል                      |
| `src/app/offline/page.tsx`              | የቀጥታ ሁኔታ አመልካች ያለው ከመስመር ውጭ መጠባበቂያ ገጽ                         |
| `src/app/layout.tsx`                    | የPWA metadata (apple-web-app፣ theme-color፣ ወዘተ) ያለው ዋና layout |
| `public/icon-512.png`                   | 512×512 PNG አዶ (Android፣ የመነሻ ማያ ገጽ)                          |
| `public/apple-touch-icon.png`           | 180×180 PNG አዶ (የiOS መነሻ ማያ ገጽ)                               |
| `public/icon-192.svg`                   | 192×192 SVG አዶ (Android adaptive)                             |
| `public/apple-touch-icon.svg`           | 180×180 SVG አዶ (የApple መጠባበቂያ)                                |