Goable
Un'API B2B che trasforma meteo e dati fisici in un punteggio da 0 a 100: per quell'attività, in quel posto, a quell'ora, si può uscire o no.
Goable prende previsioni meteo, dati marini e atmosferici e risponde a una domanda sola: conviene andare? Il risultato è un punteggio da 0 a 100 con un verdetto e una spiegazione leggibile, per sport d'acqua, neve, aria e terra. Ci si integra con un'API REST, con gli SDK TypeScript e Python o con la specifica OpenAPI.
- Il mio ruolo
- Fondatore e unico sviluppatore: prodotto, front end, back end, AI e infrastruttura.
- Per chi è
- Piattaforme di prenotazione, scuole e operatori outdoor che ogni giorno devono decidere se un'uscita si fa, e sviluppatori che vogliono quella decisione dentro il loro software.
Il problema
Le previsioni danno numeri: vento a 18 nodi, onda da un metro e venti, marea in salita. Non dicono se si può uscire. Ogni sport ha soglie diverse, che cambiano con il posto e con il livello di chi lo pratica, e chi lavora all'aperto le interpreta a mano ogni giorno. Mancava un servizio che desse questa risposta a un software, per più sport insieme e in modo spiegabile.
Come l'ho costruito
Ho progettato e scritto Goable da solo, dal motore di calcolo alla console per i clienti, dall'infrastruttura AWS al sito con le demo che chiamano l'API vera.
Il cuore è un motore di scoring in TypeScript. La parte fisica è fatta di funzioni pure, senza rete né stato: vento, onde, maree, neve, fulmini, qualità dell'aria. Ogni formula viene dalla letteratura scientifica e si testa da sola, in millisecondi. Sopra la fisica c'è uno strato probabilistico che tiene conto dell'incertezza delle previsioni e combina più fonti di dati.
L'AI ha un ruolo preciso. Un modello linguistico scrive la spiegazione del punteggio per chi la legge, ma non decide il verdetto. Le regole di sicurezza, come il rischio fulmini o l'aria pericolosa, stanno sopra il motore e valgono qualunque sia il punteggio.
Il contratto dell'API nasce dallo schema: validazione, documentazione OpenAPI e SDK escono dalla stessa fonte e non possono divergere. Il prodotto gira su AWS, con l'infrastruttura descritta in Terraform e i deploy da GitHub Actions, e il ciclo di apprendimento (controllo del drift, riaddestramento, backtest del motore) gira su job pianificati che si attivano man mano che arrivano dati reali.
Scelte tecniche
La fisica come funzioni pure
Ogni modulo fisico è matematica senza I/O: stesso input, stesso risultato. Si testa in isolamento e chi conosce il dominio può verificare ogni formula, perché ognuna cita la sua fonte.
L'LLM spiega, non decide
Il modello linguistico scrive la spiegazione per una persona. Il verdetto viene dal motore, e le regole di sicurezza su fulmini e qualità dell'aria danno "non sicuro" qualunque sia il punteggio.
Schema prima del codice
Validazione, documentazione OpenAPI e SDK nascono dallo stesso schema. Il client che usa uno sviluppatore non può dire una cosa diversa da quella che l'API fa davvero.
Apprendimento sotto controllo
Controllo del drift ogni giorno, riaddestramento ogni notte e un backtest ogni settimana, che misura quante volte il motore avrebbe detto di uscire in una giornata da restare a terra. Sono già pianificati e lavorano man mano che arrivano dati reali. Le modifiche al catalogo calcolate dai dati arrivano come proposta da rivedere, mai come modifica diretta.
Infrastruttura come codice
AWS descritto in Terraform: API serverless dietro una CDN, code per il lavoro asincrono, Postgres con PostGIS e ripristino a un punto nel tempo. Console e sito su Vercel.
Si vede quando qualcosa si rompe
Log strutturati, allarmi su errori, code e job pianificati, e una pagina di stato pubblica con monitor di uptime.
In numeri
Contati sul codice sorgente del prodotto.
- 9app nel monorepo: API, console, sito, worker e cinque acquisizioni di dati pianificate
- 25pacchetti condivisi
- 20moduli di fisica, funzioni pure senza I/O
- 6pacchetti Python per dati climatici e calibrazione
- 16job pianificati: 11 su GitHub Actions, 5 su AWS
- 496file di test: 431 TypeScript, 65 Python
- 2SDK pubblici: TypeScript su npm, Python su PyPI
- 4famiglie di sport: acqua, neve, aria e terra
Stack
- TypeScript
- Node.js
- Hono
- Zod
- OpenAPI
- PostgreSQL
- PostGIS
- Drizzle
- DynamoDB
- Python
- Anthropic Claude
- Next.js
- AWS Lambda
- Amazon SQS
- CloudFront
- Terraform
- GitHub Actions
- Vercel
- Better Stack
- Stripe
- Turborepo
- Vitest
- Playwright
