🏠 Ospite Facile

The Italian-first SaaS platform for short-term rental management in Romagna.

Ospite Facile automates multi-channel listing sync, Italian regulatory compliance (Alloggiati Web, ISTAT, CIN, tassa di soggiorno), guest communication, cleaning coordination, dynamic pricing, and revenue intelligence — all from a single dashboard designed for Italian hosts and property managers.

---

✨ Feature Highlights

Category	Features
Multi-Channel	Airbnb & Booking.com iCal sync, direct booking website, unified calendar, conflict detection
Italian Compliance	Alloggiati Web auto-filing, ISTAT reporting, CIN tracking, tassa di soggiorno calculator, multi-municipality rules
Guest Communication	Automated trigger-based messaging (email/WhatsApp/in-app), multi-language templates (IT/EN/DE/FR), AI concierge
Operations	Cleaning task assignment, inventory management, maintenance tracking, smart lock integration (Nuki/Yale/TTLock)
Revenue	Dynamic pricing engine with Romagna event awareness, RevPAR/ADR analytics, what-if scenarios, channel ROI
Billing	Stripe subscription billing (Starter €19/Host €39/Professional €79/Agency), checkout, portal, webhooks
Platform	API gateway with key auth & rate limiting, webhook system, OpenAPI spec, GDPR export/delete, job engine
Observability	Structured logging, health checks, Sentry/Axiom/Slack alerting, admin metrics dashboard

63 Prisma models · 50+ API routes · 30+ dashboard pages · 3 languages

---

🏗 Tech Stack

Layer	Technology
Framework	Next.js 16 (App Router, output: "standalone")
Language	TypeScript 5 (strict mode)
UI	React 19, Tailwind CSS 4, Lucide React, CVA
ORM	Prisma 7.8 with better-sqlite3 (dev) / Turso libSQL (prod)
Billing	Stripe (subscriptions, checkout, customer portal, webhooks)
Comms	Resend (email), Twilio (SMS/WhatsApp)
AI	OpenAI / Anthropic (configurable provider for AI concierge)
OCR	Google Vision / fallback provider for document scanning
Storage	Cloudflare R2 (document uploads)
Cache	Upstash Redis
Observability	Sentry, Axiom, Slack webhooks
Deploy	Vercel (primary), Docker (self-hosted), GitHub Actions CI/CD

---

🚀 Getting Started

Prerequisites

• Node.js ≥ 20
• npm ≥ 9

Installation

# Clone and install
git clone <repo-url> ospite-facile
cd ospite-facile
npm ci

# Generate Prisma client
npx prisma generate

# Create local database
npx prisma db push

# (Optional) Seed demo data
npm run dev
# Then POST to /api/seed

Configuration

Copy .env.example to .env and configure:

cp .env.example .env

Required for local development:

Variable	Description
DATABASE_URL	SQLite path (default: file:./dev.db)
SESSION_SECRET	Session encryption key
CSRF_SECRET	CSRF token secret
ENCRYPTION_KEY	PII encryption key

Optional integrations:

Variable	Service
STRIPE_SECRET_KEY	Stripe billing
RESEND_API_KEY	Email delivery
TWILIO_ACCOUNT_SID	SMS/WhatsApp
OPENAI_API_KEY / ANTHROPIC_API_KEY	AI concierge
TURSO_DATABASE_URL + TURSO_AUTH_TOKEN	Managed SQLite (production)
ALLOGGIATI_API_URL + certs	Questura compliance filing
ISTAT_API_KEY	ISTAT tourism reporting

See .env.example for the full list of 50+ environment variables.

Development

# Start dev server
npm run dev

# Lint
npm run lint

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Type check
npx tsc --noEmit

# Build for production
npm run build

---

🐳 Docker

# Build and run
docker compose up --build

# Or build manually
docker build -t ospite-facile .
docker run -p 3000:3000 \
  -e DATABASE_URL=file:./data/prod.db \
  -e SESSION_SECRET=your-secret \
  -v ospite-data:/app/data \
  ospite-facile

The container:

• Uses multi-stage Node 20 Alpine build
• Runs as non-root nextjs user
• Exposes port 3000
• Health checks via GET /api/health
• Persists data in /app/data volume

---

📁 Project Structure

ospite-facile/
├── prisma/
│   └── schema.prisma          # 63 models — the complete domain
├── src/
│   ├── app/
│   │   ├── api/               # 50+ API route handlers
│   │   │   ├── auth/          # login, register, logout, CSRF
│   │   │   ├── billing/       # Stripe checkout, portal, webhooks
│   │   │   ├── compliance/    # Alloggiati, ISTAT
│   │   │   ├── dashboard/     # Dashboard data endpoints
│   │   │   ├── gdpr/          # Export, delete
│   │   │   ├── v1/            # Public API (keys, webhooks, OpenAPI)
│   │   │   └── ...            # bookings, calendar, pricing, etc.
│   │   ├── auth/              # Login & register pages
│   │   ├── book/[slug]/       # Direct booking pages
│   │   ├── cleaner/           # Cleaner portal
│   │   ├── dashboard/         # 30+ dashboard sub-pages
│   │   ├── onboarding/        # Guided setup wizard
│   │   └── portal/[token]/    # Guest self-service portal
│   ├── components/
│   │   ├── dashboard.tsx      # DashboardShell + StatCard
│   │   ├── features.tsx       # Marketing feature grid
│   │   ├── hero.tsx           # Landing page hero
│   │   ├── navbar.tsx         # Responsive navigation
│   │   ├── pricing.tsx        # Pricing section
│   │   └── ui/               # Shared UI primitives
│   ├── generated/             # Prisma-generated client
│   └── lib/                   # Business logic (45+ modules)
│       ├── alloggiati.ts      # Questura guest registration
│       ├── ai-concierge.ts    # LLM-powered guest assistant
│       ├── api-gateway.ts     # API keys, rate limiting, webhooks
│       ├── auth.ts            # Session management, roles
│       ├── booking-lifecycle.ts # FSM orchestrator
│       ├── compliance-engine.ts # Multi-region compliance
│       ├── gdpr.ts            # Data export, deletion, retention
│       ├── i18n/              # IT/EN/DE translations
│       ├── ical.ts            # iCal sync engine
│       ├── integration-bus.ts # External service adapters
│       ├── istat-reporting.ts # ISTAT tourism statistics
│       ├── job-engine.ts      # Background job scheduler
│       ├── monitoring.ts      # Alerts, metrics
│       ├── observability.ts   # Structured logging
│       ├── pricing-engine.ts  # Dynamic pricing rules
│       ├── prisma.ts          # DB client (SQLite/Turso)
│       ├── revenue-intelligence.ts # RevPAR, ADR, P&L
│       ├── security.ts        # CSRF, encryption, rate limiting
│       ├── smart-locks.ts     # IoT lock integration
│       ├── stripe-billing.ts  # Subscription management
│       ├── tax-calculator.ts  # Tourist tax rules
│       └── validation.ts      # Schema validation library
├── messages/                  # i18n JSON files (it/en/de)
├── __tests__/                 # Unit & integration tests
├── e2e/                       # Playwright E2E tests
├── .github/workflows/ci.yml   # CI/CD pipeline
├── Dockerfile                 # Multi-stage production build
├── docker-compose.yml         # Local Docker deployment
└── vercel.json                # Vercel deployment config

---

🧪 Testing

# Unit & integration tests (Jest)
npm test

# With coverage
npm run test:coverage

# E2E tests (Playwright)
npm run test:e2e

# Headed E2E debugging
npm run test:e2e:headed

Test coverage includes:

• Booking lifecycle state machine transitions
• Integration bus retry & dead-letter logic
• Dynamic pricing rule application
• Communication template interpolation
• Tourist tax calculation
• Job engine scheduling
• Revenue intelligence metrics

---

🌍 Internationalization

Three languages supported: Italian (default), English, German.

Translation files live in messages/ as flat JSON with dot-notation keys. The custom i18n system in src/lib/i18n/ provides:

• getTranslation(locale, key, params?) — server-side translation
• useTranslation(namespace?) — React hook for client components
• detectLocaleFromHeaders() — Accept-Language detection
• formatCurrencyLocale(), formatDateLocale() — locale-aware formatting

---

📜 Compliance & Regulations

Ospite Facile is built specifically for Italian short-term rental regulations:

Regulation	Implementation
Alloggiati Web	XML schedina generation, client-cert TLS, Questura filing with retry
CIN (Codice Identificativo Nazionale)	Validation, tracking, display on booking sites
Tassa di Soggiorno	Per-municipality rules (Forlì, Cesena, Bertinoro, etc.), child exemptions, remittance reports
ISTAT C/59	Monthly tourism statistics reporting to regional authorities
GDPR	Full data export, account deletion, configurable retention policies, PII encryption
Safety Checklists	Fire extinguisher, CO detector, evacuation plan tracking

---

🚢 Deployment

Vercel (Recommended)

• Region: fra1 (Frankfurt)
• Build: npx prisma generate && next build
• Database: Turso (managed SQLite) in production
• Security headers applied automatically via vercel.json

Docker (Self-Hosted)

docker compose up -d

CI/CD Pipeline

GitHub Actions workflow (.github/workflows/ci.yml):

1. Lint → ESLint
2. Test → Jest with coverage upload
3. Type Check → tsc --noEmit
4. Build → Next.js production build
5. Deploy Staging → On push to staging branch
6. Deploy Production → On push to main branch (with Slack notification)

---

📖 Documentation

• docs/ARCHITECTURE.md — System architecture, data flow, Mermaid diagrams
• docs/API.md — Complete API reference for all 50+ endpoints
• ANALYSIS.md — Feature extraction & market analysis
• MOONSHOT-ANALYSIS.md — Strategic roadmap & moonshot features

---

🏷 Pricing Tiers

Plan	Price	Properties	Key Features
Starter	€19/mo	Up to 2	Basic sync, compliance reminders, essential messaging
Host	€39/mo	Up to 10	Unlimited channels, cleaning tasks, analytics
Professional	€79/mo	Up to 50	Dynamic pricing, direct booking site, multi-property reports
Agency	Custom	Unlimited	Everything + API access + white label

---

📄 License

Source code is publicly available. No open-source license has been selected yet.