AVAX Legal — specifikace¶

Status: per-app container shipped (Phase 3 pilot, 2026-05-14) Verze spec: 0.2 Aktualizováno: 2026-05-14 Autor specifikace: Avaxis tým

Repo backend: git.avaxis.cz/avax-apps/app-legal (samostatný container) Repo klient: legacy /home/avax/avax-legal/client/ — desktop + web (vendor: claudai)

1. Cíl a motivace¶

Co aplikace dělá: Časová osa českých zákonů s diff viewerem, AI výklady a vzorci. Uživatel může procházet historický vývoj legislativy, porovnávat verze paragrafů vedle sebe a ptát se AI na výklad.

Proč ji děláme: Účetní a právní specialisté potřebují rychle ověřit, jak zákon vypadal v minulých letech, jaké přesné změny prošly novelou, a získat AI-asistovaný výklad těžkých pasáží. Ručně to znamená hodiny v PDF zákonů na zakonyprolidi.cz.

Kategorie: pravni

Cílová skupina: Účetní firmy, advokátní kanceláře, in-house právníci.

2. User stories¶

Jako účetní chci najít znění § 24 ZDP k 1. 1. 2024 abych mohl/a doložit historický odpočet.
Jako právník chci porovnat dvě verze paragrafu vedle sebe (diff) abych viděl/a co konkrétně se změnilo.
Jako uživatel bez právního vzdělání chci požádat AI o výklad paragrafu v lidské řeči abych pochopil/a co to znamená pro mou firmu.
Jako uživatel chci uložit si vyhledané paragrafy do osobní knihovny abych se k nim mohl/a vrátit.
[TODO: dále doplnit s vendorem]

3. UI / UX¶

[TODO: doplnit s vendorem — dnes existuje klient app-legal, ale konkrétní obrazovky tady ještě nejsou popsány.]

Hrubý odhad z manifestu:

Obrazovka	Účel	Stav
Vyhledávání	Najít paragraf / zákon	✅ implementováno
Časová osa	Verze paragrafu v čase	✅ implementováno
Diff viewer	Porovnání dvou verzí	✅ implementováno
AI výklad	Chat s AI nad konkrétním paragrafem	✅ implementováno
Osobní knihovna	Uložené paragrafy	[ověřit]

4. Datový model¶

Vlastní DB tabulky¶

[TODO: doplnit dle skutečného schématu v avax_legal_backend. Pravděpodobně:]

Tabulka	Účel
`legal_documents`	Zákony (id, sb. číslo, název)
`legal_versions`	Verze paragrafů v čase (document_id, valid_from, valid_to, text)
`legal_diffs`	Pre-computed diffy mezi verzemi
`legal_user_library`	Uložené paragrafy per uživatel
`legal_ai_conversations`	Historie AI dotazů

V cílové architektuře (viz per-app-container.md) půjde do schema legal.

S3 prefix struktura¶

[TODO: aplikace ukládá AI výstupy / cache? Pokud ano:]

backup-<ico>/apps/app-legal/
  └── <user_id>/conversations/<conv_id>.json

Sdílená data z core backendu¶

GET /auth/me — identity uživatele (kdo to volá)
GET /catalog/apps/app-legal — verze klienta, manifest
GET /storage/token — STS pro S3 backup AI konverzací (pokud užíváme)

5. Backend API (vlastní)¶

Aktuálně: Per-app container app-legal:0.1.0 (port 8101) routovaný apps-gateway jako /apps/app-legal/legal/*. Repo: git.avaxis.cz/avax-apps/app-legal.

Module-mount fallback (legacy _BOOTSTRAP_MODULES v backend/app/dynamic_mounts.py) odstraněn 2026-05-14.

[TODO: vytvořit seznam endpointů z kódu /home/avax/avax-legal/. Pravděpodobně:]

GET    /legal/documents                       → seznam dokumentů
GET    /legal/documents/{sb_id}               → detail dokumentu
GET    /legal/documents/{sb_id}/versions      → časová osa verzí
GET    /legal/documents/{sb_id}/diff/{a}/{b}  → diff mezi verzemi
POST   /legal/ai/explain                      → AI výklad paragrafu
GET    /legal/library                         → osobní knihovna uživatele
POST   /legal/library                         → přidat do knihovny
DELETE /legal/library/{id}                    → odebrat
GET    /legal/health                          → health check (povinný!)

Health endpoint — viz per-app-container.md §4.

6. Klient (desktop app)¶

Slug klienta: app-legal Stack: [TODO ověřit — pravděpodobně Python customtkinter] Distribuce: S3 bucket app-app-legal Gitea repo: qwen/avax-legal

Komunikace: - IPC s launcher2 přes AVAX SDK - REST na vlastní backend /legal/* (cílově /apps/legal/*) - REST na core backend pro auth/storage

7. Závislosti¶

Externí¶

Služba	Použití	Kritická?
AVAX core-api `/ai/chat`	AI výklad paragrafů (per-asistent API klíč)	ano
LM Studio (192.168.1.167:1234)	LLM backend pro `/ai/chat` (qwen3.6-27b)	ano
Zdroj legislativy	[TODO: scrape zakonyprolidi.cz? oficiální API?]	ano (data freshness)

Pozn.: Claude API a Ollama klienty byly odstraněny při Phase 3 migraci — veškeré AI volání jde přes core-api /ai/chat (viz ai-chat.md).

Interní¶

core-api: /auth/*, /catalog/*, /storage/*
vm-ai: AI Service orchestrace (pokud volá hybrid LLM)
vm-gpu: Ollama (pro embedding / fallback)

8. Oprávnění a role¶

[TODO: má app vlastní permissions? Dnes pravděpodobně:] - Všichni uživatelé s app-legal v subscription → full access - super_admin → vše + admin endpointy (např. force-resync legislativy)

9. Telemetrie a logging¶

[TODO: kontrolovat dnešní stav. Cílově (per-app container):] - Strukturovaný log do stdout (JSON formát) - Eventy: search_query, diff_view, ai_request, error - Metriky: počet queries/den, AI request latency p95, cache hit rate

10. Acceptance criteria¶

MVP (verze 0.x)¶

Klient se přihlásí přes launcher
Search paragrafů funguje
Časová osa + diff viewer
AI výklad přes core-api /ai/chat
Health endpoint v backendu (/health root + /legal/health)

Verze 0.1.0 — per-app container SHIPPED (2026-05-14)¶

Repo avax-apps/app-legal initial commit
Multi-stage Dockerfile (python:3.13-slim, port 8101, healthcheck)
avax-auth shared package (JWKS RS256) — nahradil HS256 python-jose
AI klient přepsán z Claude+Ollama → /ai/chat per-asistent API key
Nový endpoint POST /legal/ai/explain (user-facing AI výklad)
Container zaregistrovaný v apps tabulce: gateway_enabled=true, container_port=8101
apps-gateway routuje /apps/app-legal/legal/*
E2E test: launcher → JWT → gateway → container → core-api → LM Studio → odpověď
Legacy _BOOTSTRAP_MODULES odstraněn z dynamic_mounts.py

Verze 1.0 (stable)¶

CI v Gitea — auto build Docker image + push do registry
Per-app Alembic migrace samostatné PG user avax_app_legal + grants jen na schema legal
Background AI extraction tasks reimpl přes /ai/chat (V1.5 v moratoriu)
Documentation v docs/apps/app-legal.notes.md

Verze 2.0 (budoucnost)¶

[TODO: vendor roadmap]

11. Otevřené otázky¶

Vendor doplní detaily — UI screenshoty, kompletní endpointy, DB schéma
Zdroj legislativy — oficiální API, scraping, manuální upload? Cyklus aktualizace?
AI provider — Claude API vs Ollama vs hybrid? Náklady na request?
Caching — Redis pro hot paragrafy? TTL?
Migrace na per-app kontejner — kdo (qwen vs Avaxis), kdy, jak (downtime?)
Premium funkce — má app freemium model nebo flat-rate s předplatným?

12. Timeline a status¶

Fáze	Status	Cílový termín
Spec MVP	⏳ in-progress	2026-05-21
Spec úplný (s vendorem)	⏳	2026-06-01
Health endpoint v backendu	⏳	2026-06-01
Migrace per-app kontejner	⏳	Q3 2026
Stable release	⏳	Q3-Q4 2026

13. Související¶

Arch spec: per-app-container.md
Distribuce: app-distribution.md
Auto-doc: ../apps/app-legal.md (generováno z admin DB)
Notes (ruční): docs/apps/app-legal.notes.md