FormulaBase
FormulaBase è una web app avanzata per creare, organizzare e condividere formulari scientifici e cheat sheet. Permette di scrivere contenuti complessi in Markdown e LaTeX, organizzarli in capitoli e argomenti, salvarli nel proprio spazio personale, condividerli tramite link pubblici o codici QR e utilizzare assistenti AI di ultima generazione per generare o migliorare formule ed appunti.
Funzionalità principali
- Autenticazione Sicura: Accesso tramite Google Authentication e Google One Tap integrato con Firebase Auth.
- Sessioni Server-Side: Gestione delle sessioni sicura e performante lato server tramite
iron-session.
- Editor Avanzato a 3 Pannelli:
- Navigatore Struttura (Outline): Un menu ad albero laterale che mostra l'indice dell'argomento e permette di navigare istantaneamente tra le sezioni.
- Monaco Editor: Editor di codice integrato con evidenziazione della sintassi per Markdown e LaTeX.
- Anteprima KaTeX/Markdown: Rendering in tempo reale delle formule matematiche e del layout Markdown.
- Assistente AI Chat Integrato: Chat AI accessibile direttamente dall'editor (supportata da Gemini e Groq) che legge il contesto dell'argomento per generare formule, spiegazioni o riassunti.
- Condivisione & Community:
- Pubblicazione dei formulari nella sezione Community con filtri e ricerca globale.
- Condivisione immediata tramite link condivisibili o codici QR dinamici generati in-app.
- Possibilità di duplicare (clonare) formulari altrui per personalizzarli.
- Sistema di preferiti e contatore di visualizzazioni.
- Dashboard di Amministrazione: Pannello
/admin dedicato per il monitoraggio degli utenti attivi, la creazione di formulari, l'analisi della distribuzione delle risorse e la lettura dei feedback degli utenti.
- Aesthetics & UX: Design premium scuro/chiaro moderno basato su Tailwind CSS 4, Radix UI e framer-motion per micro-animazioni fluide.
- Ottimizzazione SEO: Sitemap e robots dinamici, metadati semantici ottimizzati per ciascuna pagina pubblica.
Stack tecnologico
- Framework: Next.js 16 (App Router)
- Libreria Core: React 19 (con React 19.2.3)
- Linguaggio: TypeScript
- Styling: Tailwind CSS 4, PostCSS, framer-motion (animazioni)
- Database: PostgreSQL (con estensione
pg_trgm per la ricerca fuzzy)
- Autenticazione: Firebase Client Auth + Firebase Admin SDK
- Editor di testo: Monaco Editor (
@monaco-editor/react)
- Rendering scientifico & diagrammi: KaTeX (
react-katex, rehype-katex), React Markdown e Mermaid.js
- Motori AI: Google Gemini API (
@google/generative-ai) e Groq API (groq-sdk)
- Analytics: Umami Analytics integrato
Setup Locale
Requisiti
Prima di iniziare, assicurati di avere installato:
- Node.js 20 o superiore
- npm o un package manager equivalente
- Un database PostgreSQL attivo
1. Installazione dipendenze
Clona la repository ed installa i pacchetti necessari:
npm install
2. Configurazione Variabili Ambiente
Crea il tuo file .env.local partendo dal modello di esempio:
cp .env.example .env.local
(Su Windows PowerShell):
Copy-Item .env.example .env.local
Compila il file .env.local configurando le chiavi per Firebase, il database PostgreSQL, Gemini/Groq e Umami.
3. Inizializzazione Database
Esegui lo script SQL fornito per generare le tabelle:
psql "$DATABASE_URL" -f sql/create_tables.sql
[!IMPORTANT]
Dashboard di Amministrazione (/admin):
Lo schema SQL di base non include di default privilegi di amministrazione per gli utenti. Per abilitare l'accesso alla dashboard admin, aggiungi la colonna is_admin alla tabella users:
ALTER TABLE users ADD COLUMN is_admin BOOLEAN DEFAULT FALSE;
Dopodiché, imposta a TRUE il flag per il tuo specifico uid utente (assegnato da Firebase):
UPDATE users SET is_admin = TRUE WHERE uid = 'IL_TUO_UID_FIREBASE';
4. Avvio in Sviluppo
Avvia il server locale di sviluppo:
npm run dev
L'applicazione sarà disponibile all'indirizzo:
http://localhost:3000
Variabili Ambiente
| Variabile | Descrizione |
|---|
DATABASE_URL | Stringa di connessione a PostgreSQL |
NEXT_PUBLIC_FIREBASE_API_KEY | Chiave API Firebase Client |
NEXT_PUBLIC_GOOGLE_CLIENT_ID | Client ID OAuth Google per il login ed il Google One Tap |
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN | Dominio di autenticazione Firebase |
NEXT_PUBLIC_FIREBASE_PROJECT_ID | ID progetto Firebase |
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET | Bucket di storage Firebase |
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID | ID mittente messaggi Firebase |
NEXT_PUBLIC_FIREBASE_APP_ID | App ID Firebase Client |
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID | ID di misurazione Analytics Firebase |
FIREBASE_PRIVATE_KEY | Chiave privata del Service Account Firebase Admin |
FIREBASE_CLIENT_EMAIL | Email del Service Account Firebase Admin |
SESSION_SECRET | Chiave segreta di crittografia per iron-session (min. 32 caratteri) |
NEXT_PUBLIC_APP_URL | URL pubblico dell'applicazione (es. per canonical URL/condivisione) |
NEXT_PUBLIC_FORMULARIO_BENVENUTO_ID | beautiful_id del formulario predefinito clonato per i nuovi utenti |
GEMINI_API_KEY | API Key per l'accesso ai modelli Google Gemini |
GROQ_API_KEY | API Key per l'accesso ai modelli di inferenza Groq |
|
Scorciatoie da Tastiera (Keyboard Shortcuts)
L'applicazione dispone di scorciatoie da tastiera integrate per velocizzare la navigazione e la formattazione scientifica all'interno dell'editor.
Navigazione & Applicazione
- Cerca nei formulari:
Ctrl + K
- Impostazioni Formulario:
Ctrl + Shift + I
- Aggiungi nuovo capitolo/argomento:
Ctrl + Shift + A
- Genera con AI:
Alt + A
- Visualizzazione Editor:
Alt + 1
- Visualizzazione Dividi (Split):
Alt + 2
- Visualizzazione Anteprima:
Alt + 3
Formattazione Contenuto
- Grassetto:
Ctrl + B
- Corsivo:
Ctrl + I
- Citazione (Quote):
Ctrl + Shift + Q
- Lista ordinata:
Ctrl + Shift + 7
- Lista non ordinata:
Ctrl + Shift + 8
- Divisore:
Ctrl + Shift + 9
- Tabella:
Alt + T
- Codice inline:
Ctrl + Shift + J
- Codice in blocco:
Ctrl + Shift + U
- Formula inline:
Ctrl + Shift + G
- Formula in blocco:
Ctrl + Shift + H
- Titoli (da H1 a H6):
Ctrl + Shift + [1-6]
Comandi Editor (Monaco)
- Salva:
Ctrl + S
- Annulla / Ripristina:
Ctrl + Z / Ctrl + Y
- Seleziona prossima occorrenza:
Ctrl + D
- Seleziona tutte le occorrenze:
Ctrl + Shift + L
- Inserisci cursore multiplo:
Alt + Click
- Sposta riga su/giù:
Alt + ↑ / Alt + ↓
- Duplica riga:
Shift + Alt + ↓
- Elimina riga:
Ctrl + Shift + K
Struttura del Progetto
src/
├── app/ # Pagine, rotte, API Next.js e logica di routing (robots.ts, sitemap.ts)
├── components/ # Componenti UI riutilizzabili e moduli di dominio (editor, auth, home)
├── data/ # Configurazione statica e costanti (es. kbs.json per shortcut)
├── hooks/ # Custom hooks di React (es. useIsMobile, useFilters)
├── lib/ # Utility, inizializzazione DB (pg), Firebase SDK e iron-session
├── proxy.ts # Logica e matcher per la protezione delle rotte ed i reindirizzamenti
└── styles/ # Fogli di stile CSS globali, KaTeX ed editor personalizzati
public/ # Asset statici (loghi, manifest.json, immagini e icone)
sql/ # Script di creazione delle tabelle del database PostgreSQL
Struttura del Database
Il database PostgreSQL utilizza le seguenti tabelle configurate in sql/create_tables.sql:
users: Informazioni sul profilo degli utenti registrati (UID Firebase, nome, email, foto profilo).formulari: Testata del formulario (titolo, descrizione, visibilità privata/pubblica/condivisa, contatore visualizzazioni, owner).capitoli: Sezioni intermedie collegate a un formulario con ordine di ordinamento personalizzato.argomenti: Le pagine effettive contenenti il testo scritto in Markdown/LaTeX.preferiti: Relazione molti-a-molti che traccia i formulari salvati dagli utenti nella dashboard.feedback: Valutazioni da 1 a 5 stelle e recensioni fornite dagli utenti per il monitoraggio della qualità.
Viene inoltre abilitata l'estensione pg_trgm per supportare ricerche testuali con corrispondenze parziali e similarità di stringhe.
Flusso Logico di Funzionamento
- Accesso utente: L'utente si autentica con Google Auth (Client). L'ID Token viene trasmesso via POST a
/api/auth/login.
- Verifica sessione: Il backend verifica il token con Firebase Admin SDK e crea una sessione cifrata server-side salvata tramite
iron-session. Se l'utente non è censito nel DB locale, viene registrato automaticamente nella tabella users.
- Controllo Accessi: La logica definita in
src/proxy.ts protegge le rotte riservate (come /home, /editor, /settings, /admin) reindirizzando gli utenti non autenticati al login.
- Scrittura e Modifica: Dall'editor
/editor/[argomentoId], l'utente può scrivere note con formattazione istantanea KaTeX. Può chiedere supporto all'AI Chat, che recupera il contenuto corrente per ottimizzare il prompt. I dati vengono salvati automaticamente su PostgreSQL.
- Condivisione: L'utente può cambiare la visibilità del formulario. Se impostato su pubblico, questo apparirà nella scheda
/community e i motori di ricerca lo indicizzeranno grazie alla sitemap dinamica (/sitemap.ts).
Script disponibili
npm run dev: Avvia il server di sviluppo locale.npm run build: Esegue la compilazione del progetto per l'ambiente di produzione.npm run start: Avvia l'applicazione Next.js già compilata in produzione.npm run lint: Esegue i controlli statici del codice con ESLint.npm run format:check: Controlla lo stile del codice usando Prettier.npm run format:fix: Applica automaticamente le correzioni di formattazione di Prettier in tutto il progetto.
