BioLab Site — Architecture & Roadmap

Site web Astro v4 déployé sur Vercel à biolab-smoky.vercel.app.

📍 État actuel (mai 2026)

Stack :

Astro v4.16.19
TypeScript content collections
Vercel deployment (auto sur push main)
Lang : FR

Pages existantes :

/ Dashboard avec stats + alerts (feed overdue/due) + recent activity
/bestiary 69 espèces évaluées
/specimens 3 actifs (Hunter, Sentinel, Violet)
/specimens/[slug] détail spécimen
/equipment 10 items inventoriés
/vendors sources Bangkok
/notes field notes
/notes/[slug] détail note
/archetypes 6 archétypes
/about vision

Features built-in :

Feed/molt/cost tracking par spécimen
Activity log unifié
Cost breakdown mensuel
CLI commands npm run log feed/molt/cost
Alert system (feed overdue/due/soon/ok)

Branche actuelle : claude/init-jungle-kabal-lab-3z16e — PR #1 en cours de merge

Récents ajouts (par Claude Code) :

Wikipedia EN/FR auto-links sur fiches espèces
iNaturalist link auto-généré
Google Images link auto-généré
CSS background-image robuste (vs <img> tag) pour fallback brandé
Toutes URLs (Wikimedia, custom, local) sont tentées avec fallback visible

🏗️ Architecture étendue (PRD pour Claude Code v2)

Schemas TypeScript étendus à ajouter

Voir le PRD complet précédemment écrit. Highlights :

// Specimens (specimens acquis)
specimens: {
  id, slug, archetype, nickname, scientific_name, common_name,
  category,
  acquired_date, acquired_price_thb, vendor, vendor_link, cb_or_wc,
  cites_status, legal_notes,
  size_at_acquisition, longevity_expected, diet, feed_schedule_days,
  status, last_fed_date, last_molt_date,
  enclosure_id, climate (temp/humidity ranges),
  storytelling, archetype_lore_ref, visual_signature, caveats,
  primary_image, images,
  happiness_baseline, happiness_current
}

// Bestiary (espèces évaluées)
bestiary: {
  id, slug, scientific_name, common_names, category,
  origin_region, origin_country, climate_compat_bangkok,
  size_adult, longevity, diet, temperament,
  silent (bool), silent_caveats, dangerous (bool), eats_mammals (bool),
  cites_status, legal_notes,
  bangkok_availability, price_range_thb, primary_vendors,
  difficulty, setup_specs,
  scoring (brand_fit, storytelling, visual_quirky, metallic),
  storytelling, archetype_match, pros, cons,
  status, elimination_reason,
  primary_image, images, sources
}

// Archetypes (lore Jungle Kabal)
archetypes: {
  id, slug, name, symbol, short_description,
  mythology, jungle_kabal_lore, symbolic_codes, color_palette,
  specimens_incarnating[]
}

// Vendors (sources et breeders)
vendors: {
  id, name, type, location, contact,
  specialties, cb_focused, reliability_score,
  notes, affiliate_link
}

// Equipment (matos lab)
equipment: {
  id, name, category, purchased_date, price_thb,
  vendor, vendor_link, affiliate_link,
  used_for_specimens[], notes, quantity
}

// Notes (field notes)
notes: {
  id, slug, date, title, type,
  specimen_id, tags, images
}

// Events (activity log unifié)
events: {
  id, date, type, specimen_id,
  summary, details, cost_thb, cost_category,
  success, auto_generated, media_refs
}

📐 Pages à ajouter

/                      → Dashboard (existe, à enrichir avec Happiness)
/bestiary              → Liste filtrable (existe)
/bestiary/[slug]       → Fiche espèce détail (existe)
/specimens             → Liste (existe)
/specimens/[slug]      → Detail avec full storytelling + happiness (existe, à enrichir)
/archetypes            → Liste (existe)
/archetypes/[slug]     → Lore complet par archetype (NEW)
/vendors               → Sources Bangkok (existe)
/vendors/[slug]        → Vendor detail + ethics + history (NEW)
/equipment             → Inventory (existe)
/notes                 → Field notes (existe)
/notes/[slug]          → Note detail (existe)
/sourcing              → Breeders sourcing methodology + ethics statement (NEW)
/climate-setups        → Per-species climate specs (NEW)
/phases                → Phase 1/2/3 acquisitions tracker (NEW)
/happiness             → Happiness Factor system + dashboard public (NEW)
/open-source           → Jungle Lab OS documentation (NEW, futur)
/about                 → Vision + brand connection (existe)

🎨 Composants à créer / améliorer

SpecimenCard           → Avec happiness badge si activé
SpecimenHappinessChart → Graph timeline du score happiness
BestiaryCard           → Avec scoring multi-axe
BestiaryFilterPanel    → Filtres: category, status, scoring, climate, dispo
ArchetypeBadge         → Symbol + name + color
PhaseTracker           → Visualization Phase 1 / 2 / 3 avec progress bar
VendorCard             → Avec ethics badges (CB-focused, etc.)
ClimateSetupCard       → Specs visuels par espèce
EventTimeline          → Activity log unifié filtrable
HappinessDial          → Visualization 0-100 score
SourcingMethodology    → Section dédiée à l'éthique brand

🔧 CLI Commands à étendre

# Existants
npm run log feed -- --specimen=001 --prey=cricket-medium --consumed
npm run log molt -- --specimen=003 --successful
npm run log cost -- --category=food --amount=120 --description="cricket pack"

# NOUVEAUX
npm run log observation -- --specimen=001 --tags=behavior,grooming --content="..."
npm run log incident -- --specimen=002 --severity=low --content="..."
npm run log acquisition -- --species=mystrium-camillae --vendor=wild-ants --price=1900

# Happiness
npm run happiness compute -- --specimen=001 --period=7d
npm run happiness baseline -- --specimen=001 --import=baseline.json

# Bestiary management
npm run bestiary add -- --species=mystrium-camillae --status=wishlist-phase-1
npm run bestiary update-status -- --species=harpegnathos-venator --status=acquired

# Sync external (futur)
npm run sync frigate-events  # Pull events depuis Frigate
npm run sync ai-content      # Generate brand content via Claude API

🤖 Intégrations futures

Frigate (multi-cam AI)

API endpoint /api/frigate-webhook qui reçoit events
Auto-log activity events dans la collection events
Auto-trigger happiness recompute quand event notable

Claude API (content generation)

API endpoint /api/generate-narrative pour générer storytelling brand-voice
Use sur events notables (mues, repas, behaviors uniques)
Output dans events.details ou nouveau champ ai_narrative

Public dashboard (Phase 2)

Route /public pour external visitors
Aggregated happiness scores
Live cam streams (Twitch-like aggregation)
Lore + brand content

Token gating (futur, si Jungle Kabal token)

Wallet connect (MetaMask)
Holders accèdent à features premium

🖼️ Image strategy

Sources possibles

Wikimedia Commons — fallback générique gratuit (référence taxonomique)
Cloudinary ⭐ recommandé — own photos, transformations URL
Imgur — alternative Cloudinary, attention hotlinking
Self-hosted dans /public/images/ — for static immutable

URLs pattern

Wikimedia : https://upload.wikimedia.org/wikipedia/commons/...
Cloudinary : https://res.cloudinary.com/junglekabal/image/upload/specimens/{slug}.jpg
Imgur : https://i.imgur.com/{hash}.jpg

Pour les 3 specimens existants

Action immédiate : photographier les vrais spécimens (phone macro suffit). Upload Cloudinary. Replace placeholders Wikimedia (qui sont d’autres espèces que H. spinifer ≠ H. laoticus, M. splendidus ≠ M. violaceus).

🚀 Brief pour Claude Code (next iteration)

À copy-paste à Claude Code :

Hey Claude Code, j'ai besoin d'upgrader le MVP avec :

1. Schemas content collections étendus (voir doc spec)
2. Migration des 3 specimens existants vers le nouveau format
3. Nouvelles pages : /sourcing, /climate-setups, /phases, /happiness (placeholders OK)
4. Composants étendus (Specimen card avec happiness, Bestiary card avec scoring)
5. CLI commands étendus
6. Brand voice guidelines dans docs/brand-voice.md
7. Hooks/endpoints stubs pour Frigate API + Claude API + public dashboard

Stay native Astro, pas de framework lourd ajouté.

PR sur nouvelle feature branch puis merge sur main.

Quand pushé, je dump 70+ bestiary entries + archetypes lore + 
specimens via le journal de recherche `/research_journal/`.

🎯 Roadmap

Mois 1 (mai 2026)

Merger PR #1 sur main
Photographier 3 spécimens + Cloudinary
Briefer Claude Code v2 avec schemas étendus
Premier batch bestiary entries (10)

Mois 2-3

Bestiary complet (70+ entries)
Archetypes lore complets
Page /sourcing avec ethics statement
Frigate webhook setup pour activity log auto

Mois 4-6

/happiness module live (POC sur Mystrium)
Public dashboard /public
Brand content automation (Claude API)

Mois 6-12

Token gating si Jungle Kabal token launched
Open source platform repo “JungleLabOS”
Affiliate links integration

🔗 Liens

Site live
[GitHub repo] — à venir
Astro docs
Vercel

Mis à jour 2026-05-04