KnitFlow — schemi di maglia guidati dall'AI

Il progetto

Progetto personale, sviluppato tra maggio e giugno 2026. KnitFlow riceve uno schema di maglia o uncinetto, in PDF o come testo, spesso in inglese e ricco di abbreviazioni come k2tog e ssk, e lo trasforma in istruzioni strutturate in italiano da seguire un passo alla volta.

Un modello AI estrae materiali, glossario delle abbreviazioni e passi numerati; l’utente avanza un’istruzione alla volta, con segnalibro automatico, note personali e percentuale di completamento.

Architettura

Un’app iOS in Flutter e una webapp in Next.js condividono lo stesso backend Supabase.

1. Il client estrae il testo dal PDF (fino a 20 MB) direttamente nel browser o sul telefono.
2. Una route API di Next.js valida la richiesta e la inoltra alla Edge Function parse-pattern, ricavando l’identità dell’utente dal token JWT.
3. La Edge Function è l’unico componente che conosce la chiave OpenAI: sceglie il modello, invoca l’AI, salva progetto e schema e scala il credito di import tramite RPC.
4. Web e iOS leggono gli stessi dati, quindi un progetto iniziato su un dispositivo si riprende sull’altro.

L’AI lavora con GPT-4o mini per gli import standard e GPT-4o per quelli premium, con output esclusivamente JSON e temperatura 0.2.

Funzionalità

• Import di PDF o testo, con titolo personalizzato e scelta tra modello standard e premium.
• Lettura guidata: un’istruzione per schermata, barra di avanzamento e navigazione avanti/indietro, con swipe su iOS.
• Segnalibro persistente che non arretra mai, con i comandi “Inizia”, “Riprendi” e “Ricomincia”.
• Note personali per ogni istruzione; materiali e abbreviazioni consultabili da qualsiasi passo.
• Dashboard con avanzamento dei progetti e import residui aggiornati in tempo reale, area account con piano, crediti e statistiche.
• Modello freemium: un import gratuito, import aggiuntivi tramite video rewarded e piano Premium in abbonamento.

Sicurezza e controllo dei costi

• Segreti solo lato server: la chiave OpenAI risiede esclusivamente nella Edge Function e nessuna chiave segreta usa il prefisso NEXT_PUBLIC_.
• Campi sensibili protetti: crediti e ruolo dell’utente si modificano solo tramite RPC SECURITY DEFINER o webhook; le policy di Row Level Security impediscono al client di alterarli.
• Validazione ripetuta sul server: testo tra 150 e 80.000 caratteri, corpo della richiesta limitato a 256 KB e verificato prima della lettura, e un filtro su 25 termini tecnici di maglia in inglese e italiano che richiede almeno tre corrispondenze, così all’AI non arriva testo arbitrario.
• Modello premium riservato agli utenti premium anche in caso di chiamata diretta all’API.
• Errori sanificati: gli errori della Edge Function diventano messaggi comprensibili, senza esporre dettagli interni.
• Interruttori di emergenza: un feature flag disattiva gli import e un pannello di controllo può sospendere il progetto su Vercel tramite API.

Performance

• Colonna generata instructions_count, che permette alla dashboard di mostrare l’avanzamento senza scaricare le istruzioni.
• Data access layer con cache() per singola richiesta, che evita letture duplicate di utente e profilo.
• Statistiche dell’account ridotte da tre query COUNT a una sola.
• Caricamento parallelo di progetto e nota nella pagina dell’istruzione.

Problemi risolti

• Note non salvate: il codice scriveva su una colonna inesistente e ignorava l’errore restituito da Supabase. Ho corretto lo schema e introdotto la gestione esplicita degli errori.
• Import falliti in produzione: alla Edge Function mancavano i permessi GRANT di lettura e scrittura sulla tabella projects.
• Compatibilità PDF: build legacy di pdf.js con worker dedicato, per supportare iOS 16 e iPhone 8.
• Responsive: l’analisi dell’interfaccia web ha rivelato due logiche di breakpoint in conflitto (oltre 100 regole desktop-first contro meno di 40 mobile-first), titoli a dimensione fissa e margini incoerenti tra le pagine. Ho pianificato e avviato un refactor mobile-first con una scala di breakpoint unica e tipografia fluida con clamp().

Design

Identità visiva calda e artigianale, coerente tra iOS e web: palette crema, terracotta, salvia e cioccolato, Playfair Display per i titoli e DM Sans per il testo. Ho realizzato un set di 24 icone line-art, un loader animato con i ferri da maglia e due mascotte, “Dritto” e “Rovescio”, dal nome dei due punti base della maglia.

Il mio contributo

Unico sviluppatore, dalla progettazione all’implementazione: specifiche di prodotto, schema del database, backend, app mobile, webapp e identità visiva.

Stato

Funzioni principali complete e operative su web e iOS. Restano l’integrazione dei pagamenti con Stripe, sospesa per una valutazione di fattibilità, e il rilascio in produzione su Vercel con dominio dedicato.

In numeri

Webapp di circa 4.200 righe di TypeScript, con 9 pagine e oltre 20 componenti; app iOS di circa 4.900 righe di Dart, con 6 schermate; backend con 4 tabelle, 6 funzioni RPC e una Edge Function.

Risultato

Funzioni principali complete su web e iOS, con un backend condiviso che protegge chiavi, crediti e costi dell'AI lato server.