Adding app icons and localized texts to custom PhariaAI applications

Custom PhariaAI applications automatically discover app icons and translations for names and descriptions through a standardised web-manifest endpoint mechanism. Icons, names, and descriptions are displayed in the PhariaAssistant interface and in application listings.


Web manifest structure

Your web manifest should follow the structure below, although none of the icons, name_localized, or description_localized parameters are mandatory:

{
  "icons": [
    {
      "src": "/ui/icons/your-app-icon.svg",
      "type": "image/svg+xml",
    },
    {
      "src": "/ui/icons/your-app-icon.png",
      "type": "image/png",
    }
  ],
  "name_localized": {
    "en": "Test App",
    "de": "Testen App"
  },
  "description_localized": {
    "en": "This is a test application",
    "de": "..."
  }
}

Include the manifest router

Add the manifest router to your FastAPI application:

# service/src/service/main.py
from service.routes.manifest import router as manifest_router

app.include_router(manifest_router)

Add an icon to your application

Icon requirements

  • Primary: SVG (recommended for scalability)

  • Fallback: PNG

  • Size: 32x32 pixels (recommended)

  • Max file size: 100KB

1. Create the icon files

Create your icon files in the icons/ directory of your application service:

your-app/
├── service/
│   ├── icons/
│   │   ├── your-app-icon.svg    # SVG format (recommended)
│   │   └── your-app-icon.png    # PNG fallback
│   ├── src/
│   └── ...
└── ui/

2. Serve icons using static files

Mount the icons directory in your FastAPI application:

# service/src/service/main.py
from fastapi import FastAPI
from starlette.staticfiles import StaticFiles

app = FastAPI()

# Mount icons directory - must be before generic /ui mount
app.mount("/ui/icons", StaticFiles(directory="icons"), name="icons")
app.mount("/ui", StaticFiles(directory="ui-artifacts"), name="ui")

3. Create a web manifest endpoint

Add a web manifest endpoint to expose your icon metadata:

# service/src/service/routes/manifest.py
from fastapi import APIRouter

router = APIRouter()

@router.get("/manifest.webmanifest")
def get_manifest():
    return {
        "icons": [
            {
                "src": "/ui/icons/your-app-icon.svg",
                "type": "image/svg+xml",
            },
        ]
    }

Icon discovery process

PhariaAssistant fetches icon metadata for each custom application through the following process:

  1. Web manifest endpoint: PhariaAssistant calls /manifest.webmanifest on each custom app.

  2. Icon metadata: It parses the manifest to extract icon information.

  3. Icon fetching: It downloads icons from the specified URLs.

  4. Fallback handling: It uses default icons if the web manifest is unavailable or invalid.

Fallback behaviour

If PhariaAssistant cannot fetch icon metadata from a custom app’s web manifest endpoint, it displays a standard application icon.

Icon display locations

Icons are displayed in two main locations in PhariaAssistant:

  1. Sidebar navigation: In the left sidebar with the applications list.

  2. Application homepage: In the main apps page with the card layout.

Localizing names and descriptions

To localize PhariaAssistant names and descriptions:

Create a web manifest endpoint

Add a web manifest endpoint to expose your name/description localization:

# service/src/service/routes/manifest.py
from fastapi import APIRouter

router = APIRouter()

@router.get("/manifest.webmanifest")
def get_manifest():
    return {
        "name_localized": {
          "en": "Test App",
          "de": "Testen App"
        },
        "description_localized": {
          "en": "This is a test application",
          "de": "..."
        }
    }

Fallback behaviour

If PhariaAssistant cannot fetch localization metadata from a custom application’s web manifest endpoint, it displays the name and description provided by the PhariaOS API.