AVAX Application Bundle Format¶

Specifikace formátu balíčku pro přidání aplikace do AVAX platformy. Používají AI asistenti (Claude Code, Gemini, OpenCode) i vývojáři. Aktualizováno: 2026-05-02

Přehled¶

Aplikace se do AVAX platformy přidávají jako ZIP archiv obsahující manifest a soubory aplikace. Launcher stahuje pouze změněné soubory (checksum diff) — aplikace musí být portable (žádné instalace do systému).

Struktura ZIP archivu¶

my-app-1.0.0.zip
├── avax-manifest.json          ← povinný, popis aplikace
├── app/                        ← povinný, soubory aplikace
│   ├── MyApp.exe               ← spustitelný soubor (Windows)
│   ├── MyApp.dll
│   ├── config/
│   │   └── defaults.json
│   └── ...
├── icons/                      ← volitelné, ikony
│   ├── icon_256.png            ← 256×256 px PNG
│   ├── icon_64.png
│   └── icon_16.png
└── screenshots/                ← volitelné, screenshoty pro katalog
    ├── screen1.png
    └── screen2.png

avax-manifest.json¶

{
  // ── Identifikace ──────────────────────────────────────────────────
  "id": "my-app",                    // unikátní snake_case ID, neměnné po publikaci
  "name": "Moje Aplikace",           // zobrazovaný název
  "version": "1.0.0",               // SemVer — MAJOR.MINOR.PATCH
  "build": 42,                       // inkrementální číslo buildu (int)
  "channel": "stable",              // "alpha" | "beta" | "stable"

  // ── Popis ─────────────────────────────────────────────────────────
  "description": "Krátký popis pro katalog (max 160 znaků).",
  "description_long": "Dlouhý popis s markdown formátováním.\n\nPodporuje **tučné** a _kurzívu_.",
  "category": "accounting",         // "accounting" | "hr" | "crm" | "utility" | "other"
  "tags": ["faktury", "DPH"],        // max 5 tagů, lowercase

  // ── Spuštění ──────────────────────────────────────────────────────
  "entry_point": "app/MyApp.exe",    // relativní cesta k exe (od kořene ZIP)
  "entry_args": [],                  // volitelné argumenty příkazové řádky
  "working_dir": "app/",            // pracovní adresář při spuštění (relativní)
  "requires_admin": false,           // vyžaduje UAC elevaci?

  // ── Platformy ─────────────────────────────────────────────────────
  "platforms": ["win32", "win64"],   // podporované platformy
  "min_windows": "10",               // minimální verze Windows (10 | 11)

  // ── AVAX SDK ──────────────────────────────────────────────────────
  "sdk_required": true,              // musí volat AVAX SDK při startu
  "sdk_min_version": "1.0",          // minimální verze AVAX SDK

  // ── Soubory (automaticky generováno při uploadu) ───────────────────
  "files": [
    {
      "path": "app/MyApp.exe",
      "size": 1234567,               // bajtů
      "sha256": "abc123...",         // SHA-256 hex digest
      "modified": "2026-05-01T10:00:00Z"
    },
    {
      "path": "app/MyApp.dll",
      "size": 456789,
      "sha256": "def456...",
      "modified": "2026-05-01T10:00:00Z"
    }
  ],

  // ── Metadata ──────────────────────────────────────────────────────
  "publisher": "Moje Firma s.r.o.",  // název vydavatele
  "publisher_ico": "12345678",       // IČO vydavatele (nepovinné)
  "homepage": "https://example.cz",  // web aplikace (nepovinné)
  "license": "proprietary",          // "proprietary" | "freeware" | "trial" | "open-source"
  "created_at": "2026-05-01T10:00:00Z"  // ISO 8601 UTC — generováno při uploadu
}

Pole avax-manifest.json — pravidla¶

Pole	Typ	Povinné	Popis
`id`	string	✅	Snake_case, max 64 znaků, `[a-z0-9_-]`, neměnné
`name`	string	✅	Max 80 znaků
`version`	string	✅	SemVer `X.Y.Z`
`build`	int	✅	Monotonně roste — launcher rozhoduje o aktualizaci
`channel`	string	✅	alpha → beta → stable (propagace přes AVAX admin)
`entry_point`	string	✅	Relativní cesta od kořene ZIP
`sdk_required`	bool	✅	Vždy `true` pro distribuované aplikace
`files`	array	✅ při finalizaci	Generováno automaticky při uploadu na server
`platforms`	array	✅	Min. jedna platforma
`description`	string	✅	Krátký popis
`category`	string	✅	Jedna z povolených kategorií
`publisher`	string	doporučené	Zobrazuje se v katalogu
`requires_admin`	bool	ne	Výchozí `false`
`sdk_min_version`	string	doporučené	Pokud `sdk_required = true`

Pravidla pro portable aplikaci¶

Aplikace MUSÍ: - Být spustitelná bez instalace (xcopy deployment) - Ukládat uživatelská data přes AVAX SDK (ne do C:\Users\... přímo) - Volat AVAXApp.register() při startu (přes Named Pipe / Unix Socket) - Přijímat IPC příkaz {"action": "shutdown"} a čistě se ukončit

Aplikace NESMÍ: - Zapisovat do C:\Windows\ nebo C:\Program Files\ - Instalovat registry klíče (bez unikátního prefixu AVAX_{app_id}) - Vyžadovat .NET Framework / VC++ Redistributable bez přiloženého instalátoru - Spouštět vlastní update mechanismus (update řídí launcher)

AVAX SDK volání při startu¶

Aplikace musí po spuštění zavolat SDK přes Named Pipe:

Pipe name (Windows): \\.\pipe\avax_sdk_{app_id}

Registrační zpráva (JSON, newline-terminated):

{
  "action": "register",
  "app_id": "my-app",
  "version": "1.0.0",
  "pid": 12345
}

Heartbeat každých 30 s:

{
  "action": "heartbeat",
  "app_id": "my-app",
  "pid": 12345
}

Čistý shutdown (po přijetí příkazu z launcheru):

{
  "action": "shutdown_complete",
  "app_id": "my-app"
}

Upload proces (přes AVAX Admin → Přidat aplikaci)¶

Vývojář vytvoří ZIP archiv dle formátu výše
Nahraje přes AVAX Admin UI (POST /admin/apps/upload — multipart)
Backend:
Rozbalí ZIP, ověří avax-manifest.json (schema validace)
Vypočítá SHA-256 pro všechny soubory v app/
Doplní pole files do manifestu
Nahraje soubory do S3: apps/{app_id}/{version}/
Vytvoří/aktualizuje záznam v DB tabulce apps
Vytvoří verzi v app_versions s channel = "alpha" (výchozí)
Verzi lze propagovat: alpha → beta → stable přes AVAX Admin

S3 struktura aplikací¶

s3://claudeai/
└── apps/
    └── {app_id}/
        ├── {version}/
        │   ├── avax-manifest.json    ← finální manifest se soubory
        │   ├── app/
        │   │   ├── MyApp.exe
        │   │   └── MyApp.dll
        │   └── icons/
        │       └── icon_256.png
        └── latest-stable.json        ← pointer na nejnovější stable verzi

DB tabulky (backend)¶

`apps`¶

Sloupec	Typ	Popis
`id`	UUID	PK
`app_id`	VARCHAR(64)	Unikátní string ID z manifestu
`name`	VARCHAR(80)	Zobrazovaný název
`category`	VARCHAR(32)	Kategorie
`description`	TEXT	Krátký popis
`publisher`	VARCHAR(100)	Vydavatel
`is_active`	BOOLEAN	Viditelná v katalogu
`created_at`	TIMESTAMPTZ
`updated_at`	TIMESTAMPTZ

`app_versions`¶

Sloupec	Typ	Popis
`id`	UUID	PK
`app_id`	FK → apps.id
`version`	VARCHAR(20)	SemVer
`build`	INTEGER	Build číslo
`channel`	VARCHAR(10)	alpha / beta / stable
`manifest_path`	TEXT	S3 cesta k manifestu
`files_json`	JSONB	Pole `files` z manifestu
`released_at`	TIMESTAMPTZ	Datum publikace
`created_at`	TIMESTAMPTZ

Příklad minimálního manifestu¶

{
  "id": "demo-accounting",
  "name": "Demo Účetnictví",
  "version": "0.1.0",
  "build": 1,
  "channel": "alpha",
  "description": "Ukázková účetnická aplikace pro testování AVAX platformy.",
  "category": "accounting",
  "tags": ["účetnictví", "demo"],
  "entry_point": "app/DemoAccounting.exe",
  "working_dir": "app/",
  "requires_admin": false,
  "platforms": ["win64"],
  "min_windows": "10",
  "sdk_required": true,
  "sdk_min_version": "1.0",
  "publisher": "AVAXIS.CZ s.r.o.",
  "publisher_ico": "01695541",
  "license": "proprietary",
  "files": []
}

Validace manifestu (Python schema)¶

# backend/app/schemas/apps.py
from pydantic import BaseModel, field_validator
from typing import Optional, Literal
import re

class AppManifestFile(BaseModel):
    path: str
    size: int
    sha256: str
    modified: str

class AppManifest(BaseModel):
    id: str
    name: str
    version: str
    build: int
    channel: Literal["alpha", "beta", "stable"]
    description: str
    description_long: Optional[str] = None
    category: Literal["accounting", "hr", "crm", "utility", "other"]
    tags: list[str] = []
    entry_point: str
    entry_args: list[str] = []
    working_dir: str = "app/"
    requires_admin: bool = False
    platforms: list[str]
    min_windows: Optional[str] = None
    sdk_required: bool = True
    sdk_min_version: Optional[str] = None
    files: list[AppManifestFile] = []
    publisher: Optional[str] = None
    publisher_ico: Optional[str] = None
    homepage: Optional[str] = None
    license: str = "proprietary"

    @field_validator("id")
    @classmethod
    def validate_id(cls, v: str) -> str:
        if not re.match(r'^[a-z0-9_-]{1,64}$', v):
            raise ValueError("id musí být snake_case [a-z0-9_-], max 64 znaků")
        return v

    @field_validator("version")
    @classmethod
    def validate_version(cls, v: str) -> str:
        if not re.match(r'^\d+\.\d+\.\d+$', v):
            raise ValueError("version musí být SemVer (X.Y.Z)")
        return v

Kanály a propagace verzí¶

alpha  →  beta  →  stable
  │          │         │
  │          │         └── všichni zákazníci
  │          └── vybrané beta firmy
  └── pouze AVAXIS interní testování

Propagace verze přes AVAX Admin UI: - POST /admin/apps/{app_id}/versions/{version_id}/promote → posune do dalšího kanálu - Downgrade (stable → beta) možný jen pro super_admin

Tento dokument je součástí technické dokumentace AVAX platformy. Viz také: docs/dev/ai-context.md pro kompletní přehled API a infrastruktury.