Fanel

Monòlit modular amb Spring Boot + Spring Modulith

Mon, 01 Jan 0001 00:00:00 +0000

Estat: Acceptat · Data: 2026-09-04

Context

Fanel és una app familiar (<10 usuaris per llar) auto-allotjable. El requisit principal d’operació és la simplicitat: un sol contenidor. Alhora ha de ser extensible (nous mòduls: receptes, automatitzacions, agents) sense degradar-se en un “big ball of mud”.

Opcions

Opció	Pros	Contres
Microserveis	Escalat independent	Complexitat operativa enorme per a una família; múltiples contenidors
Monòlit clàssic per capes	Senzill	Acoblament creixent, difícil d’extreure res després
Monòlit modular (Spring Modulith)	Un desplegable; fronteres verificades per tests; esdeveniments persistits; documentació generada	Disciplina de paquets; dependència d’un projecte Spring addicional

Decisió

Monòlit modular amb Spring Boot 4.x, Java 25 i Spring Modulith 2.x. Un paquet Java per mòdul de negoci (household, menu, recipes, shopping, calendar, chores, assistant, notifications, automation) més shared (OPEN). Cada mòdul exposa api/ (interfície, DTOs, esdeveniments) i amaga domain/, infra/, web/. La comunicació entre mòduls es fa per esdeveniments de domini amb el registre de publicació persistit (JPA). ApplicationModules.verify() s’executa al CI.

SPA React + TypeScript (PWA) servida des del JAR

Mon, 01 Jan 0001 00:00:00 +0000

Estat: Acceptat · Data: 2026-09-04

Context

Cal una UI web moderna, usable des del mòbil (PWA instal·lable, offline a la botiga) i reutilitzable per a futurs clients Android i escriptori, sense necessitar Node ni un segon contenidor en producció.

Opcions

Opció	Pros	Contres
React + Vite + TS	Ecosistema màxim (components, TanStack Query), bona generació per agents de codi, Capacitor/Tauri	Bundle mitjà, més boilerplate
Vue 3	Corba suau, molt productiu en solitari	Ecosistema menor
Svelte 5	Bundle mínim	Ecosistema petit, runes recents
Angular	Tot inclòs	Pesat per a aquest abast
Thymeleaf + htmx	Zero build JS	No reutilitzable per a Android; offline pobre
Flutter / Compose Multiplatform	Un codi per a tot	Web pesat/immadur; fora de l’ecosistema web

Decisió

React 19 + TypeScript strict + Vite, com a PWA (vite-plugin-pwa). El build (dist/) s’empaqueta en el mòdul Maven frontend com a recurs static/ i Spring Boot el serveix amb fallback a index.html per a rutes de la SPA. En desenvolupament, Vite fa proxy de /api al backend.

PostgreSQL i SQLite via perfils

Mon, 01 Jan 0001 00:00:00 +0000

Estat: Acceptat · Data: 2026-09-04

Context

“Auto-allotjable” vol dir dues coses per a públics diferents: qui té un NAS/servidor amb Postgres vol el motor estàndard; qui vol “descarrega i executa” vol un sol contenidor i un backup que sigui copiar un fitxer.

Opcions

Opció	Pros	Contres
Només PostgreSQL	Estàndard, pgvector, tooling	Obliga a 2 contenidors
Només SQLite	1 contenidor real, backup trivial	Sense pgvector; dialecte Hibernate community
H2	Integració Spring fàcil	No apte per producció
Postgres + SQLite per perfil	Millor experiència per a tots dos públics	Cal SQL portable i tests dobles

Decisió

Perfils Spring postgres (per defecte) i sqlite. Flyway amb migracions a db/migration/common (SQL portable) i, només quan sigui imprescindible, postgresql/ i sqlite/ (via placeholder {vendor}). UUID emmagatzemats de manera portable. Els tests d’integració s’executen amb els dos motors a cada PR.

API first com a base per a clients

Mon, 01 Jan 0001 00:00:00 +0000

Estat: Acceptat · Data: 2026-09-04

Context

Visió de futur: clients Android, escriptori i agents (MCP). Tots han de compartir les mateixes regles de negoci sense duplicar-les.

Decisió

Tota funcionalitat s’exposa primer com a REST JSON a /api/v1/**, documentada amb OpenAPI 3 (springdoc). El fitxer OpenAPI és el contracte: els clients es generen a partir d’ell (TS ara; Kotlin si cal).
Errors amb RFC 9457 Problem Details.
Temps real amb SSE (/api/v1/events), no WebSocket, tret que calgui bidireccionalitat.
Autenticació utilitzable per clients no-navegador: token d’API (Bearer) a més de sessió; CORS configurable.
Zero lògica de negoci al frontend.

Conseqüències

Un canvi incompatible d’API obliga a /api/v2 o a versionar el recurs.
El frontend web és “un client més” i pot ser substituït o duplicat (Capacitor, Tauri) sense tocar el servidor.

Multi-household des de l'inici

Mon, 01 Jan 0001 00:00:00 +0000

Estat: Acceptat · Data: 2026-09-04

Context

La majoria d’instal·lacions tindran una sola llar, però és probable voler allotjar-hi família extensa o amics. Afegir householdId a posteriori implica migrar totes les taules i tots els endpoints.

Decisió

Model: Household → Member (rol ADULT/CHILD, color, PIN opcional per al mode tauleta). Tota entitat de negoci pertany a un household i tota consulta filtra per household. Els tokens d’API i les credencials MCP tenen àmbit de household.

Spring AI amb proveïdor configurable; MCP server integrat

Mon, 01 Jan 0001 00:00:00 +0000

Estat: Acceptat · Data: 2026-09-04

Context

Es vol un assistent d’IA dins l’app i que agents externs (Claude Desktop/Code, Home Assistant, agents propis) puguin operar sobre les dades via MCP. Sense obligar a cap proveïdor ni a cap cost.

Opcions

Opció	Pros	Contres
Servei d’agents separat (Python/LangChain)	Ecosistema IA ampli	Segon contenidor; duplicació de la lògica de domini
Spring AI al mateix procés	Tools = mètodes Java ja provats; MCP server/client inclosos; proveïdor per propietats; Ollama local	API encara evolutiva (2.x)

Decisió

Spring AI 2.x, confinat al mòdul assistant. Tres capes sobre les mateixes @Tool:

Pla original

Mon, 01 Jan 0001 00:00:00 +0000

Document de planificació prèvia al codi que va originar aquest repositori. Es conserva íntegre com a referència de context i de “per què” de les decisions. Les decisions d’arquitectura vinculants viuen a AGENTS.md i als ADRs; l’estat real d’implementació viu a ROADMAP.md. Si aquest document i el ROADMAP.md discrepen, el ROADMAP.md mana (és el que es manté al dia).

Decisions ja preses respecte a la secció 6 d’aquest document (veure AGENTS.md/ADRs):

Frontend: React + TypeScript (Vite, PWA).

BD: PostgreSQL i SQLite suportats des del dia 1.

Nom/paquet: Fanel (the family organizer panel), paquet dev.agiro.fanel. UI per defecte en català, amb castellà com a segon idioma.

Multi-household des del model inicial.

Proveïdor d’IA per defecte: cap actiu per defecte, configurable (Ollama/OpenAI/Anthropic).

1. Què fa la POC (i què n’aprenem)

Mòdul	POC	Què cal per a la versió real
Menú	Graella dia × (esmorzar, dinar, berenar, sopar), text lliure	Setmanes reals (dates, no “Dilluns” genèric), receptes reutilitzables, generació de compra a partir del menú
Calendari	Llista d’esdeveniments amb data + títol + qui l’ha afegit	Hora, recurrència, per membre, sincronització CalDAV/ICS
Compra	Ítems amb `done`, “buida comprats”	Quantitats, categories/passadissos, múltiples llistes, mode botiga offline
Tasques	Text + assignat (Mamà/Papà/Nens) + `done`	Membres reals, recurrència, rotació, gamificació opcional
Identitat	`prompt('¿Cómo te llamas?')` local	Llar (household) + membres + login real però senzill (família, no empresa)
Persistència	`window.storage` clau-valor JSON	BD relacional, esdeveniments de domini, API estable

Conclusions: el model de dades és petit però totes les funcions es creuen (menú → compra, tasques → calendari, receptes → compra). L’arquitectura ha de facilitar aquestes interaccions sense acoblar els mòduls.

i18n català + castellà des de l'inici

Mon, 01 Jan 0001 00:00:00 +0000

Estat: Acceptat · Data: 2026-09-04

Context

La POC és en castellà; el projecte i la família usen català. Afegir i18n a posteriori és costós i deixa textos hardcodejats.

Decisió

Internacionalització des del primer commit: react-i18next al frontend (src/i18n/ca.json, es.json; ca per defecte, detecció del navegador) i MessageSource al backend (messages_ca.properties, messages_es.properties) per a errors i notificacions. Household.locale determina l’idioma per defecte de la llar; Member pot sobreescriure’l. Idioma del codi: anglès.

Cap llibreria de components UI general; `FullCalendar` (nucli MIT) només per al calendari

Mon, 01 Jan 0001 00:00:00 +0000

Estat: Acceptat · Data: 2026-09-06

Context

El Calendar.tsx actual mostra els esdeveniments com una llista agrupada per dia (sense vista de graella mensual/setmanal). Es va demanar avaluar Untitled UI React (https://www.untitledui.com/react/components/calendars) per al component de calendari, i alhora avaluar-ne l’adopció com a llibreria de components general per a tota la SPA. També es va revisar un recull d’alternatives (“9 React Calendar Components for Your Next App”, dev.to/jaydevm) que inclou react-calendar, react-big-calendar, react-datepicker, mantine, PrimeReact, MUI X i FullCalendar.

Assistent multiagent: un model/API per funció

Mon, 01 Jan 0001 00:00:00 +0000

Estat: Acceptat · Data: 2026-09-09

Context

L’ADR 0006 ja fixa Spring AI confinat al mòdul assistant, amb tools compartides i proveïdor configurable. La Fase 3 del roadmap afegeix xat, MCP i automatismes. Es vol un assistent multiagent on cada agent pugui tenir el model i la API més adequats a la seva funció: agents privats amb IA local (Ollama) per a consultes de la llar, i agents més potents (multimodals, cloud) per a tasques com extreure una recepta a partir d’una imatge.

Distribució i estratègia de releases

Mon, 01 Jan 0001 00:00:00 +0000

Estat: Acceptat · Data: 2026-09-13

Context

Fanel ja té un backend/frontend estable (Fase 2 completa) i un client Android natiu. Falta definir com es distribueixen els artefactes (imatge Docker, APK) i com es publica documentació consultable sense clonar el repositori. Fins ara: docker.yml publicava ghcr.io/giro-dev/fanel:latest en cada push a main (i, per error, també amb tags v* sense versionar la imatge); android/ només es compilava i testava a CI, sense publicar cap artefacte; no hi havia lloc de documentació ni tags de versió al repositori.