# Architecture de KA

## Vue d'ensemble

```
KA/
  App/        KAApp (racine 5 onglets + bulle KA Agent), OnboardingView
  Core/       Ecosystem (les univers + mapping JSON), Services (APIClient cache
              disque, UniverseService, AgentService SSE), FavoritesStore
  Design/     KATheme (papier/encre, accents), composants (KACard ombre décalée,
              KAWordmark, KAChip, KAItemRow, états vides), Haptics
  Features/   Home, Search (universelle), Universes (grille + explorateur +
              fiche), MapView (carte unifiée), Favorites, Profile, AgentChat
KAWidgets/    widget « Le pouls » (WidgetKit, timeline réseau 30 min)
KATests/      tests des adaptateurs / favoris / URL (hors réseau)
project.yml   XcodeGen — source de vérité du projet
```

## Le principe : tout est configuration

Un univers = une entrée `Universe` dans `Ecosystem.all` :
identité (wordmark, accent, SF Symbol, tagline, domaine) + API (`listPath`,
`itemsKey`, `searchParam`, clés du total dans /api/stats) + un **mapping**
`[String: JSONValue] → KAItem`. TOUTES les vues (grille, explorateur, fiche,
recherche universelle, carte, accueil, favoris) consomment le `KAItem`
universel — aucune vue par univers.

### Ajouter un futur univers (ex. Ora·Ka)

1. Ajouter l'entrée dans `Ecosystem.all` (accent officiel d'ecosystem.json du
   design system ka-ui, mapping calqué sur un adaptateur voisin).
2. C'est tout : grille, recherche, carte (si lat/lng), accueil et favoris le
   prennent en charge automatiquement. Ajouter un test de mapping dans
   `KATests` avec un échantillon JSON réel de son API.

## Connexion aux API

- **Listes/recherche** : les API publiques des plateformes
  (`/api/listings|vehicles|jobs|products|restaurants|events|creators`,
  `?q=&limit=`), JSON décodé en `JSONValue` (forme libre) puis mappé.
- **Compteurs live** : `/api/stats` de chaque plateforme (`/api/status` pour
  Trouve·Ka).
- **KA Agent** : `POST https://www.api-ka.com/api/agent/chat` (SSE — events
  delta/tool/done/error), parsé par `AgentService.stream` (URLSession.bytes).
  La clé Anthropic vit côté serveur, jamais dans l'app.
- **Cache/hors ligne** : `APIClient` écrit chaque réponse sur disque ; TTL
  120 s (300 s pour les stats) ; en cas d'échec réseau, la dernière copie est
  servie. Les favoris sont persistés localement (Application Support).

## Conventions

- Swift 5, zéro dépendance externe. Couleurs par univers via `--accent` du
  design system web (mêmes hex que ka-ui/ecosystem.json).
- Sombre = papier/encre inversés (`KATheme.paper/ink(scheme)`), cartes avec
  bordure encre + ombre décalée (signature Groupe-KA), coins continus.
- Aucune donnée inventée : prix placeholders (≤ 0,2 $ épicerie, ≤ 50 $ loyers,
  ≤ 1 000 $ propriétés) masqués ; états vides propres partout.
- Haptique sur les gestes clés (favori, recherche, envoi agent).