00 · System overview

Verified live 2026-06-30. NIE Experts Spain is an automated NIE-application service for Italians in Spain: a customer pays once, fills two short forms, and the system generates and delivers their official paperwork (EX-18 + Tasa 790/012) with no human in the critical path. This file is the map — every surface, the end-to-end data flow, and where each piece is documented.

Purpose

A customer buys a NIE package (digital / expert / concierge) on the website. The backend then, automatically: opens one "practice" (case) per person, collects their data, generates the Spanish forms after a deliberate human-like delay, emails them, files them to Drive, shares the situation guide, and handles upsells, bookings, outcomes, reviews, refunds and delivery failures. The only routine human touch is the WhatsApp agent answering questions.

Surfaces

Surface	Role	Where it lives
Website	Checkout UI, affiliate signup/dashboard, Stripe webhook bridge, Discord pings	Vercel/Netlify (Next.js) — this repo
Stripe	Payments, upsells, refunds, disputes	Stripe dashboard (see AUDIT-FINDINGS B3 — test keys)
Supabase Postgres	System of record (orders, practices, tokens, affiliates, KPIs)	Project `kbmvtawsdhmzjnsonazr`, eu-west-1 — see `01-data-model.md`
n8n	All backend automation (37 workflows)	`n8n.nieexpertsspain.com`, n8n 2.61.0 — see `03-flow-catalog.md`
Tally	Fase-1 contact form + Fase-2 EX-18 questionnaire	Forms `LZk4ov` / `aQvplB` — see `02-tally-forms.md`
Notion	CRM mirror of orders (`NIE Website Orders` DB)	Synced by W15 every 5 min
Resend	Transactional email	`RESEND_FROM_EMAIL` (see AUDIT-FINDINGS B1/B2)
Google Drive	Generated docs + situation guides storage/sharing	Per-practice subfolders
Cal.com	Consultation / group-call booking	Booking webhook -> W12
Discord	Ops alerts + error routing	Channels per `03-flow-catalog.md` Discord routing table
WhatsApp agent	Customer Q&A, payment links, escalation	Live path = W07 + GeneratePaymentLink (agent name "Milene")

End-to-end data flow

checkout (Stripe)
  -> W01  creates order row + sends Fase-1 invite (chases non-responders)
  -> customer fills Fase-1 (Tally LZk4ov)
  -> W02  opens one practice per person + mints Fase-2 token, starts tier onboarding
  -> customer fills Fase-2 (Tally aQvplB)
  -> W03  after a human-like 45-60 min delay: generates EX-18 + Tasa 790/012,
          emails them, files to Drive
  -> W04  shares the situation/tier guide
  -> upsells          (W09: priority appointment / consultation)
  -> consultation     (W12: Cal.com booking recorded on practice)
  -> outcome/review   (W17 outcome check, W20 dissatisfaction escalation)
  -> errors recovered (W05: delivery-failure recovery, 2-attempt cap -> Discord)
  -> refunds/disputes (W10 chargeback, W16 refund handler)
Orders sync to Notion every 5 min (W15).

Key timing note: documents do not arrive instantly. W03 waits a randomized 45-60 min (with a 5-20 min interstitial email) so delivery feels human. This is by design, not a fault.

Handoff & scope

Node Agency built the system and has handed off the running tooling and all credentials (Supabase, n8n, Stripe, Tally, Notion, Resend, Drive, Cal.com, Discord, WhatsApp agent) to NIE Experts. From go-live onward, day-to-day operation is NIE's responsibility — monitoring Discord error channels, clearing Tally corrections, approving payouts, and watching the n8n execution log. The audit (AUDIT-FINDINGS.md) was a one-time read-only review; fixes are proposed, not applied.

What	Where it's documented
Data model / tables / enums	`01-data-model.md`
Tally form fields	`02-tally-forms.md`
Every n8n workflow + error handling	`03-flow-catalog.md`
Go-live switches (keys, overrides)	`07-go-live-checklist.md`
Audit findings (blockers/defects/hardening)	`AUDIT-FINDINGS.md`
Operator runbooks (Italian, per-area)	`docs/handoff/00-panoramica.md` … `13-*.md`
Affiliate go-live / collaudo	`docs/handoff/13-affiliate-collaudo-go-live.md`

Status: pre-launch on Stripe TEST keys

The system is currently running on Stripe test keys (sk_test…) with email redirected to a single test inbox (EMAIL_OVERRIDE_TO) and a sandbox Resend sender. It is not yet taking real money or sending real customer email. The exact switches to flip — Stripe live keys + webhook secret, unset EMAIL_OVERRIDE_TO, verified RESEND_FROM_EMAIL, TURNSTILE_SECRET_KEY, and clearing test-mode Notion rows — are tracked in 07-go-live-checklist.md and itemized as blockers B1-B5 in AUDIT-FINDINGS.md.