Architettura Tecnica MVP

Executive Summary

Architettura completa per marketplace bevande artigianali con modello puro intermediario. Stack scelto: Rails 8 + Hotwire + PostgreSQL + Solid Queue/Cache/Cable + Stripe Connect. Priorità: SEO-first, time-to-market veloce, costi infrastruttura minimi.

3 mesi

Timeline sviluppo (1 founder full-time)

~€45

Costo infrastruttura MVP/mese (hosting + monitoring)

1.000+

Produttori scalabili senza refactoring

1. Principi Architetturali

1.1 Core Principles

SEO-first: Ogni pagina produttore/prodotto è renderizzata server-side, indicizzabile da Google dal giorno 1
Asset-light: Zero gestione magazzino/logistica, tutto a carico produttore
Scalabilità graduale: MVP semplice che evolve con i ricavi, non over-engineering
Developer velocity: Un solo dev (founder) deve poter mantenere e evolvere la piattaforma
Costi fissi minimi: Nessuna infrastruttura enterprise, scale-up solo quando necessario

1.2 Non-Requirements (MVP)

❌ App mobile nativa (web-first, responsive)
❌ Micro-services (monolite Rails fino a 100k utenti)
❌ Real-time notifications (email + polling sufficiente)
❌ ML/AI recommendations (curation manuale iniziale)
❌ Multi-currency/i18n (solo Italia/€ per MVP — dominio iniziale brewsters.it; domini nazionali ccTLD per mercato, con lingua e catalogo prodotti localizzati per dominio, attivati con l’espansione internazionale)

2. Stack Tecnologico

2.1 Backend

Framework: Ruby on Rails 8

Maturo, stabile, veloce per marketplace
Hotwire (Turbo + Stimulus) per interattività senza SPA
Action Cable per real-time opzionale (post-MVP)

Database: PostgreSQL 18

Relazioni complesse produttore-prodotto-ordine-commissione
Estensioni: earthdistance (geo-filtering km 0)
Ricerca full-text: Meilisearch (search engine esterno, typo-tolerant, faceting, filtri avanzati)
Backup automatizzato su Cloudflare R2

Background Jobs / Cache / Real-time: Rails 8 Solid Stack

Solid Queue — job asincroni (email, indicizzazione Meilisearch, geocoding) su PostgreSQL, zero Redis
Solid Cache — fragment caching durable su database (256MB namespace)
Solid Cable — WebSocket per aggiornamenti real-time (notifiche ordini)
Mission Control Jobs per UI gestione code

Storage: ActiveStorage + Cloudflare R2

Sviluppo: storage locale su disco
Produzione: Cloudflare R2 (S3-compatible, free tier 10GB + 10M reads/mese)
Image processing: libvips (ruby-vips) + mini_magick fallback
PDF fatture/ricevute

2.2 Frontend

View Layer: ERB templates + Hotwire (server-rendered HTML per SEO nativo)
CSS: Tailwind CSS 4 (utility-first, via tailwindcss-rails)
JavaScript: Importmap + Stimulus controllers (zero bundler, bundle minimo)
Maps: Leaflet.js + OpenStreetMap (zero API costs)
Checkout: Stripe.js (PCI compliance out-of-the-box)

2.3 Dashboard Produttori

Framework: Rails + Hotwire (Turbo + Stimulus) — stesso stack del frontend pubblico

Rationale stack unificato: Hotwire fornisce reattività sufficiente per dashboard analytics con aggiornamenti real-time (Turbo Streams) e interazioni complesse (Stimulus controllers). Evita complessità double-stack, riduce bundle size, facilita manutenzione.

3. Architettura Dati

3.1 Schema Database (Core Entities)

                Users
                id (UUID), email (unique, index)
password_digest (bcrypt)
role (enum: consumer, producer, admin)
OAuth identities (Google, Facebook, LinkedIn)
avatar (ActiveStorage attachment)
timestamps

            

                Producers
                id (UUID), user_id (FK)
business_name, slug (unique via friendly_id, SEO-friendly URLs)
ProducerProfile (modello separato per dati editoriali)
ProducerAddress (indirizzo + geocoding asincrono via Nominatim)
latitude, longitude (per km 0)
commission_rate (decimal, default 12% — scala a 8% oltre soglia volume)
plan (enum: free, pro, partner)

            

                Products
                id (UUID), producer_id (FK, index)
name, slug (scoped to producer, via friendly_id)
description (Markdown via Redcarpet)
category, style, region, product_attributes
ABV (alcohol_percentage), volume_ml
price_cents
stock_quantity, published (boolean)
images (ActiveStorage, has_many_attached)
tags (Gutentag — genere, stile, attributi)
ProductListing (modello separato per arricchimento editoriale SEO)
Indicizzato su Meilisearch (name, description, producer_name, category)

            

                Orders
                id, user_id (FK consumer)
producer_id (FK, for filtering)
order_number (unique: #BRW-20260215-0042)
status (enum: pending, paid, shipped, delivered, cancelled)
subtotal_cents, commission_cents, total_cents
stripe_payment_intent_id, stripe_transfer_id
shipping_tracking_url, shipped_at, delivered_at

            

3.2 Relazioni Chiave

User has_one Producer
Producer has_many Products
Order belongs_to User (consumer)
Order belongs_to Producer
Order has_many OrderItems

3.3 Indici Critici per Performance

idx_products_producer_published ON products(producer_id, published)
idx_orders_user_status ON orders(user_id, status)
idx_producers_location USING GIST per query geospaziali
idx_producers_slug UNIQUE
idx_products_slug_producer UNIQUE

4. Pagine Principali (MVP)

4.1 Pubbliche (SEO-critical)

Home (/): Hero con value proposition, Featured producers, "Scopri per regione"
Produttori Index (/produttori): Lista con filtri (regione, prodotto, km 0), paginazione
Produttore Single (/produttori/:slug): Storia, processo produttivo, territorio + lista prodotti + Schema.org LocalBusiness markup
Prodotti Index (/prodotti): Lista cross-produttori con filtri categoria, regione, prezzo, km 0
Prodotto Single (/produttori/:producer_slug/prodotti/:product_slug): Foto, descrizione, ingredients + pricing + Schema.org Product markup
Carrello (/cart): Session-based, raggruppato per produttore
Checkout (/checkout): Login/signup required, Stripe Payment Intent

4.2 Autenticate (Produttori)

Dashboard (/dashboard): Ordini recenti, analytics vendite
Prodotti (/dashboard/prodotti): CRUD prodotti, upload foto, gestione inventario
Ordini (/dashboard/ordini): Lista ordini da evadere, azioni spedizione
Profilo (/dashboard/profilo): Modifica storia, processo produttivo, foto + export PDF profilo stampabile (con QR code per marketing offline) + [Post-MVP Fase 2] ordina copie stampate e rilegati professionalmente (Brewsters Print)
Analytics (/dashboard/analytics): [Post-MVP] Grafici vendite, breakdown prodotto (Hotwire + Stimulus + Chart.js)

5. Flussi Principali

5.1 Onboarding Produttore

Produttore richiesta accesso (form pubblico /richiedi-accesso)
Admin review (verifica licenze, P.IVA)
Admin approva → email invite con link setup
Produttore completa profilo (storia, foto, prodotti iniziali)
Admin final review → pubblica profilo
Stripe Connect onboarding (Standard o Express account)

5.2 Acquisto Consumer

Consumer naviga /produttori o /prodotti
Aggiunge prodotti al carrello (session-based)
Checkout → login/signup
Inserisce indirizzo spedizione
Conferma ordine → Stripe Payment Intent
Pagamento riuscito: email conferma + notifica produttore
Stripe Connect Transfer a produttore (subtotal - commission, hold 7 giorni)
Produttore spedisce → segna "shipped" con tracking URL
Consumer riceve email con tracking

5.3 Gestione Commissioni (Stripe Connect)

Application fee model: Brewsters trattiene commissione al momento del pagamento
Split payment: Consumer paga 100% a Brewsters → transfer (100% - commission) a produttore
Payout produttore: automatico via Stripe (settimanale o mensile)
Costi Stripe: 1.5% + €0.25 transazione (EU cards) → assorbito nella commissione 8%

6. Integrazioni Esterne

Servizio	Provider	Use Case	Costo
Stripe Connect	Stripe	Pagamenti + trasferimenti produttori	1.5% + €0.25/tx
Ricerca	Meilisearch	Full-text search prodotti (typo-tolerant, faceting)	Self-hosted (Fly Machine dedicata)
AI Contenuti	Anthropic (Claude API)	Generazione testi, traduzioni, arricchimento prodotti	Pay-per-use
Geocoding	Nominatim (OpenStreetMap)	Geolocalizzazione produttori per filtro km 0	Gratuito
Storage	Cloudflare R2	Immagini prodotti/produttori (ActiveStorage)	Free tier 10GB; poi ~€0.015/GB/mese
Analytics	Google Analytics 4	Tracking conversioni, e-commerce events	Gratuito
Maps	Leaflet + OpenStreetMap	Filtro km 0, visualizzazione produttori	Gratuito
SEO	meta-tags + json-ld + sitemap_generator	Dynamic meta tags, Schema.org (LocalBusiness, Product), XML sitemap	Gratuito

7. Infrastruttura e Deployment

7.1 Hosting e Deploy (MVP)

Fly.io (scelta MVP)

Fly Machines per app Rails (~$5-15/mo shared CPU)
Fly Postgres (managed, 1GB free tier)
Meilisearch su Fly Machine dedicata
Cloudflare R2 per storage file (S3-compatible, free tier generoso)
Zero Redis — Rails 8 Solid Stack su PostgreSQL

✅ Deploy con fly deploy, SSL automatico, edge networking globale. Scaling orizzontale semplice con Fly Machines. CDN e R2 via Cloudflare.

7.2 CI/CD

GitHub Actions (2k minuti/mese gratuiti)
Pipeline: test → lint → deploy staging → manual approval → deploy production
Test suite: RSpec (model/integration tests), no full E2E MVP

7.3 Monitoring (MVP)

Sentry: Error tracking (€26/mese tier base)
Uptime Robot: Gratuito, ping ogni 5 minuti
Health check: endpoint /up integrato Rails 8

8. Sicurezza e Compliance

8.1 Autenticazione

Devise gem (Rails standard)
Password: bcrypt hashing
Session: signed cookies (Rails encrypted)
OAuth: OmniAuth (Google, Facebook, LinkedIn) — già implementato

8.2 Verifica Età (Compliance Alcol)

MVP: Checkbox obbligatorio checkout "Dichiaro di avere almeno 18 anni"
Post-MVP: Integration con servizio verifica ID (Onfido, Veriff)

8.3 GDPR

Privacy policy e Cookie policy (template legalizzato)
Consenso cookie (banner con opt-in analytics)
Data export/deletion su richiesta utente

8.4 Payment Security

PCI Compliance: gestito da Stripe (zero PCI scope per Brewsters, usiamo Stripe.js). No credit card data stored on Brewsters servers.

9. Performance e Scalabilità

9.1 Target Performance (MVP)

< 300ms

Time to First Byte (TTFB)

< 1.5s

Page Load Time (Lighthouse)

100+

Concurrent users senza degradation

9.2 Ottimizzazioni MVP

Fragment caching produttori/prodotti (Solid Cache, TTL 1h, invalidazione automatica on update)
HTTP headers: Cache-Control: no-cache per pagine dinamiche (browser richiede sempre ultima versione)
Database connection pooling (PostgreSQL native)
Image optimization: libvips resize on upload, WebP format, lazy loading
CDN: CloudFlare free tier (caching solo assets statici CSS/JS/immagini, HTML sempre fresco)

10. Timeline Sviluppo

Mese 1 - Setup & Core (Settimane 1-4)

Setup progetto Rails 8 + PostgreSQL + Solid Queue/Cache/Cable
Schema database migrations (UUID primary keys)
Models: User, Producer, Product, Order, OrderItem
Autenticazione (Devise + OmniAuth Google/Facebook/LinkedIn)
Layout base + Tailwind CSS 4 + Importmap setup

Mese 2 - Features MVP (Settimane 5-8)

CRUD Produttori (admin) + CRUD Prodotti (producer dashboard)
Pagine pubbliche: home, produttori index/show, prodotti index/show
Carrello (session-based)
Checkout + Stripe Payment Intent integration
Order management (producer dashboard)

Mese 3 - Polish & Launch (Settimane 9-12)

Redcarpet (Markdown) per storytelling produttore
Image upload (ActiveStorage + libvips)
Email transazionali
SEO: sitemap_generator, meta-tags, json-ld (Schema.org)
Testing: RSpec suite core flows
Deploy staging + produzione via Fly.io
Onboarding manuale primi 5 produttori (beta)

11. Costi Ricorrenti (MVP - Anno 1)

Servizio	Costo Mensile	Note
Fly.io (hosting)	~€30	App + Postgres + Meilisearch Machines
Sentry (monitoring)	$26	Error tracking
Dominio (.it)	$2	Registrazione annuale / 12
Stripe (payment)	Variabile	1.5% + €0.25 per transazione (assorbito)
Totale fisso	~€55-60/mese	R2 free tier; email da aggiungere quando necessario

Note: Costi scalano con traffico, ma restano asset-light. Nessun costo logistica/magazzino.

12. Rischi Tecnici e Mitigazione

Rischio 1: Complessità Stripe Connect

Probabilità: Media | Impatto: Alto

Mitigazione:

Usare Stripe Standard Connect (onboarding hosted, zero custom UI)
Testing su Stripe test mode con account dummy
Consultazione documentazione ufficiale + Rails gem stripe-ruby
Fallback: se troppo complesso, MVP con pagamenti diretti PayPal produttore

Rischio 2: Performance Database (1.000+ prodotti)

Probabilità: Bassa (MVP) | Impatto: Medio

Mitigazione:

Indici ottimizzati su query critiche
Fragment caching aggressivo (invalidazione smart on update)
Monitoring query N+1 (Bullet gem)
Upgrade Fly Machine se necessario (scaling verticale/orizzontale semplice)

Rischio 3: CTO Single Point of Failure

Probabilità: Media | Impatto: Alto

Mitigazione:

Documentazione inline codice
README completo con setup instructions
Deploy automatizzato (zero deploy manuale)
Utente non tecnico può gestire contenuti via dashboard admin
Post-Anno 1: onboarding dev junior per supporto manutenzione

13. Metriche Tecniche di Successo MVP

Metrica	Target MVP	Strumento Monitoraggio
Deploy time	< 10 minuti	Fly.io deploy
Page load time (avg)	< 1.5s	Google Lighthouse
Uptime	> 99.5%	Uptime Robot
Error rate	< 1%	Sentry
Test coverage	> 80% (models/controllers)	SimpleCov
Database query time (p95)	< 100ms	Sentry + Fly Metrics
Bugs critical (Mese 1)	< 10	GitHub Issues

Conclusioni

Architettura tecnica validata e pronta per execution.

Stack scelto (Rails 8 + Hotwire + PostgreSQL + Solid Stack + Fly.io + Cloudflare R2 + Stripe Connect) è:

✅ Maturo e battle-tested per marketplace
✅ SEO-first nativo (server-rendering)
✅ Veloce da sviluppare (3 mesi per MVP completo)
✅ Costi fissi bassi (~€55-60/mese)
✅ Scalabile fino a 1.000 produttori senza rewrite

Prossimo step: Start sviluppo Mese 1.

Riferimenti Tecnici

Documentazione ufficiale e fonti per ogni tecnologia adottata nello stack MVP.

Framework e Linguaggi

Ruby on Rails 8 — rubyonrails.org | Rails Guides
Motivazione scelta: server-rendering nativo (SEO-first), convention over configuration, ecosistema maturo per marketplace (Stripe, Devise, ActionMailer). Rails 8 Solid Stack elimina dipendenza da Redis.
Hotwire (Turbo + Stimulus) — hotwired.dev
Motivazione: SPA-like UX senza JavaScript framework separato; reduce complexity; stessa base Rails.

Database, Search e Storage

PostgreSQL 18 — postgresql.org/docs
Motivazione: earthdistance per geolocalizzazione km 0, ACID transactions per pagamenti, UUID primary keys. Database separati per cache (Solid Cache), queue (Solid Queue) e cable (Solid Cable).
Meilisearch — meilisearch.com/docs
Usato per: ricerca full-text prodotti (typo-tolerant, faceting, filtri per categoria e stato pubblicazione). Integrazione via gem meilisearch-rails.
Rails 8 Solid Stack — Solid Queue, Solid Cache, Solid Cable
Motivazione: background jobs, caching e WebSocket senza Redis. Database-backed, zero infrastruttura aggiuntiva.
ActiveStorage + Cloudflare R2 — storage locale in sviluppo, Cloudflare R2 (S3-compatible) in produzione.
Image processing via libvips (ruby-vips) con mini_magick fallback. R2: free tier 10GB storage + 10M reads/mese, zero egress fees.

Pagamenti

Stripe Connect — stripe.com/connect | Pricing EU
Usato per: split payment (consumer → Brewsters → produttore), KYC produttori via Stripe Express, payout automatici. Costo: 1,5% + €0,25/tx (EU cards).
Stripe.js / Stripe Elements — stripe.com/docs/stripe-js
Motivazione: PCI DSS compliance out-of-the-box; zero card data stored su server Brewsters.

Hosting e Infrastruttura

Fly.io — fly.io/pricing
Fly Machines per app Rails e Meilisearch. Fly Postgres managed. Deploy con fly deploy, SSL automatico, edge networking. ~€30/mese base stack.
Cloudflare R2 + CDN — cloudflare.com/r2 | CDN plans
R2: object storage S3-compatible, free tier 10GB + 10M reads/mese, zero egress fees. CDN: caching asset statici, DDoS protection, SSL. HTML sempre servito fresco.
Docker — Multi-stage build (ruby:4.0.1-slim), container per app + worker Solid Queue + Meilisearch + PostgreSQL.

Monitoring e Qualità

Sentry — sentry.io/pricing — Error tracking, performance monitoring. Team tier ~€26/mese.
ActionMailer + letter_opener (dev) — Email transazionali via Rails ActionMailer. In sviluppo: letter_opener per preview in browser. Produzione: servizio SMTP da configurare (es. Postmark, SendGrid).
SimpleCov — github.com/simplecov-ruby/simplecov — Code coverage Ruby. Target: >80% su models/controllers.
RuboCop — rubocop.org — Linter e formatter Ruby standard.

Autenticazione e Sicurezza

Devise gem — github.com/heartcombo/devise — Authentication standard Rails: registrazione, login, password reset, email verification.
OmniAuth — OAuth login: Google, Facebook, LinkedIn. CSRF protection via omniauth-rails_csrf_protection.

AI e Contenuti

Anthropic (Claude API) — docs.anthropic.com — Generazione contenuti produttore, traduzioni editoriali, arricchimento schede prodotto. Gem anthropic.
Redcarpet — github.com/vmg/redcarpet — Parser Markdown per storytelling produttore e descrizioni prodotti.

SEO e Performance

Google Search Console — search.google.com/search-console — Monitoraggio indicizzazione, Core Web Vitals, backlink organici.
Schema.org — LocalBusiness / Product Markup — schema.org/LocalBusiness — Structured data per rich snippet in SERP (produttore locale, prodotti con prezzo e disponibilità).