menuescolar.es - Gestor de Menús Escolars (2025)

Una plataforma SaaS per transformar PDFs de menús escolars en calendaris digitals accessibles

El Projecte

menuescolar.es és una aplicació web que resol un problema real: moltes escoles publiquen els menús mensuals en format PDF, cosa que dificulta la consulta ràpida per part de les famílies.

La solució: una plataforma on cada escola pot tenir la seva pròpia pàgina pública amb el menú del dia sempre visible i actualitzat.

El procés és senzill: l'escola puja un PDF del menú mensual, la Intel·ligència Artificial (Google Gemini) extreu automàticament els àpats de cada dia, i en segons queda publicat en format web accessible des de qualsevol dispositiu.

Com Funciona

Per a les Escoles (Gestors)

1. Registre → Creació de compte i organització amb URL única (exemple: menuescolar.es/escola-abellerol)
2. Configuració → Personalització amb logo, descripció i preferències d'idioma
3. Pujada de PDF → Upload del calendari mensual en format PDF
4. Processament IA → Google Gemini analitza el document i extreu els àpats estructurats
5. Publicació → Els menús queden disponibles automàticament a la URL pública
6. Compartir → Enviament de l'enllaç a famílies i personal del centre

Per a les Famílies (Visitants)

1. Accés directe → Visita la URL de l'escola (sense necessitat de registre)
2. Visualització → Consulta el menú d'avui o navega pel calendari mensual
3. Multi-dispositiu → Funciona perfectament en mòbil, tablet i ordinador
4. Multi-idioma → Disponible en català, castellà, anglès, basc i gallec

Arquitectura Tècnica

Sistema Multi-Tenant

Cada escola té les seves dades completament aïllades:

• Una base de dades amb relacions estrictes organització → àpats
• Un sol usuari-propietari per organització (model 1:1)
• URLs úniques generades automàticament (slugs)
• Logos i configuracions personalitzades per cada centre

Seguretat i Rendiment

Autenticació i Autorització:

• JWT tokens gestionats per PocketBase
• Validació de propietat en cada operació de modificació
• API keys d'IA mantingudes en servidor (mai exposades al client)
• Headers de seguretat amb Helmet (CSP, X-Frame-Options, etc.)

Protecció d'Abús:

• Rate limiting: 10 peticions generals cada 15 minuts
• Rate limiting PDFs: màxim 5 pujades per hora
• CORS configurat amb origins permesos
• Validació de formats i tamany de fitxers

Optimitzacions:

• Build multi-stage amb Docker (imatge lleugera)
• Cache d'estàtics amb hash de Vite (1 any)
• Compilació TypeScript per detecció d'errors en temps de desenvolupament
• Lazy loading de components React

Processament d'IA

El cervell del sistema és Google Gemini:

1. El PDF es converteix a Base64 per transport segur
2. S'envia a Gemini amb un prompt específic per extreure menús
3. La IA retorna dades estructurades (data + àpat)
4. Es validen i guarden a la base de dades
5. Queden disponibles immediatament a la web pública

Reptes Superats

🤖 Precisió de l'Extracció

Els PDFs de menús escolars venen en formats molt variats (taules, text lliure, imatges). Gemini ha demostrat ser prou flexible per adaptar-se a diferents layouts i extreure correctament les dades.

🏢 Aïllament Multi-Tenant

Assegurar que cada escola només vegi i modifiqui les seves pròpies dades va requerir:

• Relacions foranes estrictes a PocketBase
• Middleware de validació de propietat en cada endpoint
• Tests exhaustius d'accés no autoritzat

📧 Sistema de Correus

Integració amb Resend per enviar:

• Emails de benvinguda
• Verificació de comptes
• Notificacions de nous menús (futur)

🌍 Internacionalització

Suport per 5 idiomes amb fitxer de traduccions de 94KB que cobreix:

• Interfície completa (botons, missatges, errors)
• Formats de data adaptats a cada llengua
• Configuració per usuari i per organització

🐳 Desplegament Docker

Dockerfile multi-stage que:

1. Stage 1: Compila el frontend React amb Vite
2. Stage 2: Copia el build i prepara el backend Node.js
3. Resultat: Una sola imatge que serveix frontend estàtic + API

Compatible amb Dokploy per desplegaments automàtics des de GitHub.

Stack Tecnològic

Frontend

• React 18 amb TypeScript
• Vite (build tool ultraràpid)
• React Router 7 (enrutament client-side)
• Tailwind CSS (styling utility-first)
• PocketBase SDK (client d'autenticació)
• pdfjs-dist (previsualització de PDFs)

Backend

• Node.js 22 & Express
• PocketBase (base de dades SQLite + auth)
• Google Gemini API (extracció IA)
• Resend (servei d'emails transaccionals)
• Multer (gestió de pujades de fitxers)
• Helmet (capçaleres de seguretat)
• Rate Limit (protecció anti-abús)

Infraestructura

• Docker (contenidorització)
• Dokploy (desplegament automàtic)
• GitHub (control de versions)
• PocketBase (hosting separat per a auth i dades)

Característiques Principals

Per a Gestors d'Escola

• ✅ Registre i creació d'organització amb URL única
• ✅ Pujada de PDFs de menús mensuals
• ✅ Extracció automàtica de menús amb IA
• ✅ Personalització amb logo i descripció
• ✅ Configuració d'idioma per defecte
• ✅ Validació d'email obligatòria
• ✅ Gestió completa de menús (edició, eliminació)
• ✅ Dashboard privat amb estadístiques

Per a Famílies

• ✅ Accés públic sense registre
• ✅ Vista del menú d'avui destacat
• ✅ Calendari mensual navegable
• ✅ Disseny responsive (mòbil, tablet, desktop)
• ✅ Canvi d'idioma (5 llengües disponibles)
• ✅ Càrrega ràpida i optimitzada
• ✅ URLs amigables per compartir

Funcionalitats del Sistema

• ✅ Multi-tenant amb aïllament de dades
• ✅ Una organització per usuari
• ✅ Slugs únics autogenerats
• ✅ Sistema de templates (modern/classic/colorful)
• ✅ Detecció de menús duplicats (data + organització)
• ✅ Validació de formats PDF
• ✅ Gestió d'errors amb missatges clars
• ✅ Logs de servidor per debugging
• ✅ Health check endpoint per monitoring

Roadmap i Millores Futures

Funcionalitats Planificades

• 🔄 Múltiples menús per organització: Menú basal, celíac, vegetarià, etc.
• 🔄 Col·laboradors: Permetre múltiples usuaris per escola
• 🔄 Notificacions email: Alertes automàtiques de nous menús
• 🔄 Dominis personalitzats: menudescola.escolapius.cat
• 🔄 API pública: Integració amb altres sistemes escolars
• 🔄 App mòbil: Versions natives per iOS i Android
• 🔄 Exportació: Descarregar menús en diferents formats
• 🔄 Analytics: Estadístiques d'ús i visualitzacions

Millores Tècniques

• 🔄 Tests automatitzats: Cobertura amb Jest i React Testing Library
• 🔄 CI/CD pipeline: GitHub Actions per tests i desplegament
• 🔄 Monitoring: Integració amb Sentry per tracking d'errors
• 🔄 Performance: Lighthouse score 90+ en totes les categories
• 🔄 SEO: Meta tags dinàmics per cada organització
• 🔄 PWA: Capacitats offline amb Service Workers

Documentació Tècnica

El projecte inclou documentació exhaustiva:

• README.md - Guia d'inici ràpid i configuració local
• DEPLOYMENT.md - Desplegament a producció amb Dokploy
• MULTI_TENANT_SETUP.md - Configuració de l'esquema multi-tenant
• POCKETBASE_SETUP.md - Instal·lació i inicialització de PocketBase
• PDF_UPLOAD_IMPLEMENTATION.md - Detalls del processament de PDFs
• TESTING_CHECKLIST.md - Escenaris de testing i casos límit

Estat del Projecte

Estat actual: ✅ 95% complet i llest per testing

Implementat

• ✅ Arquitectura multi-tenant funcional
• ✅ Sistema d'autenticació i autorització
• ✅ CRUD complet d'organitzacions
• ✅ Pujada i processament de PDFs amb IA
• ✅ Interfície pública per organitzacions
• ✅ Internacionalització 5 idiomes
• ✅ Desplegament Docker automatitzat
• ✅ Sistema d'emails transaccionals
• ✅ Rate limiting i seguretat
• ✅ Documentació completa

En Poliment

• 🔧 Branding de capçaleres
• 🔧 Refinament de rutes entre components
• 🔧 Optimització de rendiment

Prova la plataforma: https://menuescolar.es

GitHub: Codi privat (disponible sota petició)

Data de llançament: Novembre 2025

Desenvolupat per Albert Sarlé