Goable è un'API REST B2B multi-tenant che restituisce punteggi di idoneità (0–100) per attività outdoor nelle quattro famiglie — acqua (kitesurf, surf, windsurf, vela, sub), neve (sci alpinismo, freeride, snowboard), aria (parapendio, deltaplano) e terra (trekking, trail running, arrampicata) — sulla base di previsioni meteorologiche in tempo reale e fisica multi-dominio. La piattaforma copre un monorepo Turborepo con quattro applicazioni (apps/api, apps/admin, apps/website, apps/worker-lambda), 23 package condivisi e una pipeline di calibrazione ML in Python, unificati sotto TypeScript Node 22 ESM con pnpm 10 workspaces.

Motore & API (apps/api — Hono 4.6, porta 4000)

• Motore di scoring: nove livelli attivi (L1–L9) dalla fisica grezza allo scoring ensemble probabilistico, narrative LLM, auto-calibrazione ML, underwriting parametrico, proiezioni climatiche, Personalized Decision Agent, Counterfactual Explainer, hardening di produzione e Concept-Drift Guardian. Ogni livello è un package puro (@goable-io/physics, @goable-io/scoring, @goable-io/intelligence, @goable-io/decision-agent, @goable-io/counterfactual, @goable-io/drift-monitor) iniettato nel composition root.
• Libreria di fisica (@goable-io/physics): 21 namespace — wind, wave, tide, astronomy, bathymetry, atmosphere, thermal, comfort, swell, visibility, snow, lightning, precipitation, airQuality, marine, hydrology, alpine, coastal, time, surface. Matematica pura, nessun I/O, ogni modulo porta un header con citazione.
• Architettura delle route: 50 file di route sotto src/routes/ (varianti score pubbliche, intelligence, proiezioni, osservazioni, admin calibration/drift/verification/decision, billing); 33 file di use case sotto src/usecases/. Le route non devono contenere logica di business — validate → chiama un use case → errorResponse(). Utility condivise: lib/httpErrors.ts (errorResponse + ErrorCodes), lib/schemas.ts (GeoPointSchema, TimeWindowStringSchema), middleware/planGate.ts (requirePlanAtLeast, requireScope, requireAuth).
• Dependency injection: tutti gli store, provider e servizi cablati in src/compose.ts (46 K LOC). Drizzle + Postgres per 20+ tipi di entità; Redis per sessione/rate-limit (finestra giornaliera per piano: free=100, starter=1 k, pro=10 k, scale=∞); DynamoDB KV cache (peer dep opzionale); fallback in-memory per lo sviluppo.
• Auth: Bearer token, prefisso = primi 16 caratteri (DB-indicizzato), hash = SHA-256(token completo). Gate universali: lightning_proximity ≥ 0.85 o AQI category = hazardous → verdict=unsafe, indipendentemente dal profilo.
• OpenAPI + docs: @hono/zod-openapi per la generazione dello schema; Scalar UI servita a /docs. L'SDK è generato dallo stesso schema via openapi-typescript.
• Migrazioni: 32 file SQL ordinati in infra/migrations/ (PostGIS geography(POINT, 4326), tipi custom tstzrange, tabelle pseudonimo con Row-Level Security). I binding Drizzle in @goable-io/tenants rispecchiano le migrazioni ma non generano lo schema.

Console Admin (apps/admin — Next.js 16, porta 4001)

• Doppio portale role-based: ops/ (staff interno — tutti i tenant, calibration, drift, verification, audit, provider-skill, recommendation-runs) e portal/ (cliente — impostazioni, chiavi API, usage, outcomes, webhook, billing), entrambi protetti da cookie JWT HS256 (goable_console_session, TTL 8h) via jose server-side. Il server della console si autentica all'API tramite header X-Goable-Key.
• 20 domini feature sotto src/features/: ogni cartella esporta via index.ts e isola server/dal.ts (tutte le chiamate API), server/keys.ts (chiavi TanStack Query), server/schemas.ts (Zod) e ui/ (componenti React). Nessun import diretto tra feature.
• Pattern dati: RSC per le letture iniziali, TanStack Query 5 per reactive/polling/mutations, Server Actions per le mutazioni (niente route /api), nuqs 2 per lo stato filtri/paginazione persistito nell'URL.
• Tabelle: TanStack Table 8 (headless); Grafici: Recharts 3; Mappe: MapLibre GL 5 + react-map-gl 8 per le viste geospaziali.
• Form: @tanstack/react-form con field path type-safe + validatori Zod esposti via shadcn FormMessage. Toast via Sonner 2.

Sito Marketing (apps/website — Next.js 16, porta 4002)

• 26+ route pubbliche: landing, /catalog (browser dei profili attività), /score (demo interattiva), /explain, /decision, /recommend, /adaptation, /forecast-verification, /sustainability-index, /underwriting, /spc-charter, /provider-skill, /personalize, /spot-discovery, /docs (27 route annidate), /research, /science, più routing dinamico /legal/[doc].
• Pagine ecosistema: /sealect (verticale acqua), /spc-charter (neve / syndicate Lloyd's), /partner-with-us.
• Animazioni: GSAP 3.15 + @gsap/react 2.1 per parallax hero, pill tab e transizioni. Embla Carousel 8.6 per caroselli di card.
• Contenuto: react-markdown + remark-gfm per le pagine doc; @goable-io/sdk (workspace) usato nelle demo interattive per chiamare l'API live.

Profiles Catalog & SDK

• @goable-io/profiles-catalog (repo esterno goable-io/profiles-catalog, CC BY 4.0, v2.3.4 su npm): 18+ profili attività base in YAML su quattro categorie, con varianti regionali e per spot. Aggiungere un'attività è una PR su quel repo, non una modifica a questo monorepo. Lo schema Zod è byte-identico tra i due repo — packages/profiles/test/schemaSync.test.ts verifica l'hash in CI.
• @goable-io/sdk (v0.2.0, pubblicato su npm): client TypeScript zero-dependency per tutti gli endpoint pubblici — score, scoreSeries, scoreMulti, scoreHistorical, scorePortfolio, explainCounterfactual, decision, deleteUserData, explain, briefing, projections, quote, health. Funziona su Node ≥18 e browser. Errori tipizzati: GoableApiError (422 + array Zod issues), GoableNetworkError (timeout/parse). Config: apiKey, baseUrl, timeoutMs, override fetch.

Infrastruttura & data layer

• Pipeline ML Python (packages/calibration/): cron settimanale di calibrazione L3 (.github/workflows/calibration-weekly.yml) — ensemble triple-method (sklearn isotonic, GaussianProcess, statsmodels Logit × 500 bootstrap) + Heckman IPW + gate Brier Skill Score. Genera diff YAML curve + PR body per la review degli operatori.
• AWS Lambda worker (apps/worker-lambda): eventi webhook Stripe via SQS → use case processStripeWebhookEvent → aggiornamento usage tenant su Drizzle. Bundle con esbuild (ESM, Node 22), deploy via Terraform.
• Terraform (infra/terraform/): moduli bootstrap + per-environment (env/prod/) per l'infrastruttura AWS.
• Job schedulati (GitHub Actions): calibration-weekly.yml, drift-daily.yml (scan CUSUM alle 04:00 UTC), decision-agent-nightly.yml (warm-start retrain MLP alle 03:00 UTC).
• Logging strutturato: Pino 9.5 con middleware request-id; probe di readiness /v1/health/ready (condizionato all'idratazione skill-lookup); graceful shutdown su SIGTERM (budget 10s per le richieste in volo).
• Email: @goable-io/emails — template React Email (@react-email/components, @react-email/render).

Highlights tecnici

• Full stack: Node 22 ESM, TypeScript 5.7, Hono 4.6, Next.js 16.2 (Turbopack), React 19, Tailwind CSS 4.3, Drizzle ORM 0.38, PostgreSQL + PostGIS, Redis, AWS Lambda, Vercel, Biome, Turborepo 2.3, pnpm 10
• Librerie chiave: @goable-io/sdk 0.2.0 (client API zero-dep), @goable-io/profiles-catalog 2.3.4 (profili YAML pubblici), @hono/zod-openapi (route OpenAPI-first), drizzle-orm 0.38 (Postgres type-safe), @tanstack/react-query 5 + react-table 8 + react-form 1.28 (data layer admin), maplibre-gl 5 + react-map-gl 8 (UI geospaziale), pdfkit 0.18 (generazione PDF SPC charter), recharts 3 (dashboard admin), jose 5.9 (JWT HS256 session crypto), pino 9.5 (logging strutturato), vitest 2.1 (test unitari + integrazione), stripe 22 (API) + 17 (Lambda)
• Qualità del codice: Biome 1.9.4 sostituisce ESLint + Prettier (Rust-based, line width 120 per i file src/, doppi apici, no semicoloni, trailing comma, organize-imports)
• Testing: Hono app.request() — nessun server HTTP reale; pattern makeMockProvider(samples) per i mock meteo; RUN_PG_INTEGRATION=1 abilita i test di integrazione Drizzle; pnpm turbo lint typecheck test deve rimanere verde prima di ogni commit
• Deploy: API → AWS Lambda (bundle ESM esbuild) o server Node; Admin + Website → Vercel (Next.js App Router, build Turbopack); Worker → AWS Lambda (trigger SQS); SDK → npm (sdk-release.yml)