PHASE 13: Customer Onboarding
Trigger: "Execute Phase 13 as per masterplan."
Goal: Complete, largely automated customer lifecycle: acquisition, provisioning (<60s), configuration wizard, data migration, training, health scoring, churn prevention.
Prerequisite: Phase 12 is completed. Platform is live, Tenant Zero active.
Reference: Chapter 17 — Customer Onboarding
Note: Steps classified as
[SOFTWARE],[BUSINESS], or[HYBRID].
Step 13.1 — [HYBRID] Customer Acquisition Flow
(reference: Chapter 17 — Section 1)
- Lead Channels: Website form, trade shows, referrals, partners, cold outreach -> CRM lead
- Demo Process: Lead -> confirmation email (5 min) -> 30-min video demo -> proposal -> follow-up
- Trial: 14-day trial (full features, 50 member limit), automated provisioning, email sequence (Day 0,3,7,10,13)
- Contract Closing (Integrated Bundle):
| # | Contract | Provider |
|---|---|---|
| 1 | SaaS Agreement (AGB) | Membership One GmbH |
| 2 | AVV/DPA | Membership One GmbH |
| 3 | My-Factura Agreement | My-Factura |
| 4 | SEPA Lastschriftmandat | CashControl (via My-Factura) |
All 4 documents in single digital flow, one signature, Membership One orchestrates downstream.
- 3 Onboarding Scenarios:
| Scenario | Description | Additional Steps |
|---|---|---|
| A — Founder | New business | Registration guidance, insurance, bank, founding support (Franchise or M1) |
| B — Expansion | Additional location | Parent link, shared branding, cross-location reporting |
| C — Migration | System switch | Data migration path, parallel operation, reconciliation |
- Conversion tracking: per stage, per source, per scenario
Validation: - [ ] Lead from website, demo scheduling, trial provisioning, contract bundle generated, documents stored
Result: Complete acquisition funnel with 3 scenarios.
Step 13.2 — [SOFTWARE] Tenant Provisioning (<60s)
(reference: Chapter 17 — Section 2)
Self-service, fully automated tenant creation.
Provisioning Pipeline (RabbitMQ provisioning.create queue):
Step 1: Create Organization
- Generate tenant slug, create Entity, assign tier, set config
- [B] Link to parent [B] Copy parent branding
Step 2: Create Admin User
- Account, assign role, magic link (72h expiry)
Step 3: Default Configuration
- Currency, locale, timezone, VAT, SKR03, notifications
Step 4: Service Provider Integration
- Create Consumer in My-Factura, store ID, register SEPA, configure webhook
Step 5: Branding Setup
- Default branding (or copy from franchise parent), email templates
Step 6: Membership Templates
- 3 defaults (Basic/Standard/Premium) or copy from parent
Step 7: Scenario-Specific Setup
- [A] Founding checklist, insurance guides, bank setup
- [B] Staff links, cross-location reporting
- [C] Source system template, migration instructions
Step 8: Welcome Communication
- Email with magic link, quick-start PDF, scenario-specific attachments
- Drip sequence: Day 0, 3, 7, 14, 30
Status tracking: PENDING -> IN_PROGRESS -> COMPLETED/FAILED. Retry 3x, then alert support.
Performance Target: < 60 seconds for all scenarios.
Validation: - [ ] Self-signup provisions tenant without manual intervention - [ ] Admin logs in via magic link - [ ] My-Factura consumer created, SEPA registered - [ ] Scenario A: founding checklist visible - [ ] Scenario B: parent linked, branding inherited - [ ] Scenario C: migration instructions delivered - [ ] Total time < 60 seconds
Result: Fully automated self-onboarding for all 3 scenarios.
Step 13.3 — [SOFTWARE] Configuration Wizard
(reference: Chapter 17 — Section 3)
6-step wizard on first admin login:
- Step 0 — Scenario Selection (if not set during signup): Founder / Expansion / Migration
- Step 1 — Organization Profile: Name, address, logo, business type, member count estimate - [A] Founding status, [B] parent organization selection
- Step 2 — Membership Plans: Pre-populated from industry template, edit name/price/cycle/duration
- Step 3 — Payment Setup: IBAN, BIC, SEPA creditor ID, billing day, payment methods
- Step 4 — Communication: From name/email, signature, welcome email preview
- Step 5 — Team Invitation: Name, email, role; bulk invite; magic links
Industry Templates:
| Template | Plans | Resources | Features |
|---|---|---|---|
| Fitnessstudio | Basic/Standard/Premium | Gym, Sauna, Courses | Check-in, courses, PT |
| Sportverein | Kind/Jugend/Erwachsen/Familie | Halle, Platz, Vereinsheim | Events, teams |
| Tanzschule | Einzelkurs/Flatrate/10er-Karte | Studio 1/2, Saal | Course registration |
| Kampfsport | Anfaenger/Fortgeschritten/Wettkampf | Dojo, Ring, Kraft | Belt grading |
| Jugendorganisation | Basis/Aktiv/Ehrenamt | Gruppenraum, Lager | Events, volunteer hrs |
Scenario-specific extras: [A] Founding Checklist step, [C] Data Import step.
Automated Data Enrichment (during Step 1): - Impressum Extraction: Enter website URL → scrape Impressum page → extract company name, address, HRB number, USt-IdNr., managing director → pre-fill organization profile - Handelsregister Lookup: Enter company name or HRB → query public Handelsregister → verify legal entity, registration date, legal form - OpenStreetMap Address: Address autocomplete during input → verify coordinates → auto-fill city, postal code, country - libphonenumber: Phone number validation + formatting → detect country, format in E.164 + national display - All enrichment is optional (skip if website not available), results shown as "Suggested values" for admin approval
Implementation:
- DataEnrichmentService with 4 adapters: ImpressumScraper, HandelsregisterClient, GeocodingClient (OSM Nominatim), PhoneValidationService (libphonenumber)
- Async enrichment via RabbitMQ (don't block wizard progress)
- Cache results in Organization.enrichmentData (JSONB) for audit
Validation: - [ ] Wizard appears on first login, saves correctly, template pre-populates, skip works - [ ] Data enrichment: Impressum extraction, address autocomplete, phone validation - [ ] Industry template applies correct plans, resources, and features
Result: Admin operational in 15 minutes with automated data pre-fill.
Step 13.4 — [SOFTWARE] Data Migration
(reference: Chapter 15 — Migration Strategy, Chapter 17 — Section 4)
Migration Paths by Scenario:
| Scenario | Source | Method | Support Level |
|---|---|---|---|
| A — Founder | None (new business) | Manual entry or small CSV | Self-service |
| B — Expansion | Parent entity data | Clone from parent (API) | Automated |
| C — Migration (basic) | easyVerein, ClubDesk, SPORTSCLUB | Self-service CSV import (Phase 7 module) | Self-service + dry-run |
| C — Migration (complex) | Magicline, custom systems | Assisted CSV import with mapping | Team/Professional: email support |
| C — Migration (Cash360) | Cash360 database | Phase 11 migration tool | Membership One performs |
Self-Service CSV Import Flow (Scenario C — basic): 1. Admin selects "Import Data" in wizard (Step [C]) or via Settings → Data Import 2. Select source system template (easyVerein/ClubDesk/Magicline/SPORTSCLUB/Generic) 3. Upload CSV file (drag-and-drop, max 50 MB) 4. Dry-run: System validates all rows, shows: total, valid (green), errors (red with details per row) 5. Admin fixes errors in spreadsheet or clicks "Import valid rows only" 6. Execute: Creates members, bank accounts, contracts in batches of 100 7. Progress bar: X of Y rows imported 8. Post-import report: created records, skipped records, error CSV download
Post-Migration Validation (all scenarios): - Record count comparison: source row count vs. imported count - Financial reconciliation: SUM(open balances) matches between systems - Referential integrity: all contracts linked to valid members, all bank accounts linked - Random 5% sampling: spot-check field values (name, IBAN, contract dates) - Customer sign-off: admin confirms "migration looks correct" checkbox - 90-day rollback window: keep source data reference, allow deletion of all imported data
Validation: - [ ] CSV import works with all 5 templates - [ ] Dry-run catches validation errors - [ ] Error report downloadable with row-level details - [ ] Post-migration validation report generated - [ ] 90-day rollback mechanism functional
Result: Customers migrate from any system with confidence and validation.
Step 13.5 — [HYBRID] Training and Go-Live
(reference: Chapter 17 — Section 5)
Self-Service Resources:
| Resource | Content | Format |
|---|---|---|
| Knowledge Base | 20+ articles covering all features | Markdown, searchable, public |
| Quick-Start PDF | 4-page getting started guide | PDF, auto-generated with org branding |
| Video Tutorials | 5 key workflows (see below) | 2-5 min each, embedded in KB |
| In-App Tooltips | First-time user hints on key UI elements | Contextual, dismissible |
5 Video Tutorial Topics: 1. "Adding your first member" (create member + bank account + contract) 2. "Setting up billing" (SEPA configuration, first billing run) 3. "Managing your class schedule" (create course, assign trainer, resource booking) 4. "Using check-in" (QR setup, access zones, kiosk mode) 5. "Understanding your dashboard" (KPIs, reports, data export)
Live Training per Tier:
| Tier | Sessions | Duration | Topics | Delivered By |
|---|---|---|---|---|
| Starter | 0 | — | Self-service only | — |
| Team | 1 | 30 min video call | Dashboard, members, billing | Customer Success |
| Professional | 1 | 60 min | Full admin walkthrough + Q&A | Customer Success |
| Enterprise | 3 | 3x 60 min | Admin, trainer, receptionist (role-specific) | Customer Success + Dev |
Go-Live Checklist (Admin Dashboard Widget):
| # | Item | Auto-Validated | Description |
|---|---|---|---|
| 1 | Organization profile complete | Yes | Name, address, logo, timezone filled |
| 2 | 1+ membership plan active | Yes | At least one MembershipTemplate with status ACTIVE |
| 3 | SEPA/payment configured | Yes | BankAccount with SEPA mandate, billing day set |
| 4 | 1+ team member invited | Yes | At least one user besides admin created |
| 5 | 5+ members added | Yes | Member count >= 5 |
| 6 | Welcome email customized | Yes | CommunicationTemplate 'welcome_email' modified from default |
| 7 | Test transaction run | Yes | At least one Transaction created (any status) |
| 8 | Branding set | Yes | Organization logo + primary color differ from defaults |
Progress bar: 0/8 → 8/8. Confetti animation on completion.
Go-Live Support: - Team: email support during first 14 days - Professional/Enterprise: dedicated Slack/Teams channel for 30 days, weekly 15-min check-in call
Validation: - [ ] KB has 20+ articles (at least 2 per major feature area) - [ ] Quick-Start PDF generates with organization branding - [ ] Go-Live Checklist renders in admin dashboard, items auto-validate, progress bar works - [ ] 8/8 completion triggers confetti + "You're live!" notification - [ ] Support channel creation automated for Professional/Enterprise
Result: Clear, guided path from signup to productive use within 15 minutes (self-service) to 7 days (enterprise).
Step 13.6 — [SOFTWARE] Customer Health Scoring
(reference: Chapter 17 — Section 6)
Health Score (0-100, calculated weekly per organization):
| Dimension | Weight | Green (>=70) | Yellow (40-69) | Red (<40) |
|---|---|---|---|---|
| Login frequency | 25% | >=3x/week | 1-2x/week | <1x/week |
| Feature adoption | 25% | >=5 features | 3-4 features | <=2 features |
| Member activity | 20% | Growing/stable | Flat | Declining |
| Payment health | 20% | <5% failed | 5-15% failed | >15% failed |
| Support sentiment | 10% | No P1, CSAT>=4 | Open P2+ | Open P1, CSAT<3 |
Automated Touchpoints:
| Timing | Action |
|---|---|
| Day 1 | Welcome email + magic link |
| Day 3 | Setup tips email |
| Day 7 | Feature spotlight |
| Day 14 | Trial conversion offer (if trial) |
| Day 30 | Check-in + NPS survey |
| Day 90 | Quarterly review + feature highlights |
| Monthly | Usage summary |
| Annually | Thank-you + renewal offer |
Churn Prevention: - Yellow: automated help email - Red: personal outreach within 48h - Cancellation: exit survey, offer pause/downgrade/extended trial - Win-back: 30/60/90 day emails with incentive
Expansion Triggers: - Approaching tier limit (>80% of member limit) → upgrade notification email + in-app banner - Clicking locked feature → modal with upgrade CTA + "What you get with [Tier]" comparison - Not using available features (e.g., check-in module available but unused for 30 days) → educational email with tutorial link - High growth (>20% member increase in 30 days) → proactive outreach suggesting Professional features
Implementation:
- HealthScoreService: scheduled weekly calculation per organization, stores in OrganizationHealthScore table
- LifecycleAutomationService: scheduled daily, checks touchpoint timing, creates Communication records
- ChurnDetectionService: scheduled daily, checks Yellow/Red thresholds, creates support tickets for Red
- ExpansionService: event-driven (member count change, feature click), checks triggers, sends notifications
- All automated emails use CommunicationTemplate with type LIFECYCLE_*
- Admin dashboard: Customer Health section with score trend chart, at-risk customers list (Red/Yellow)
API Endpoints:
- GET /api/health-score/{entityId} — Current health score with dimension breakdown (internal/vendor only)
- GET /api/health-score/at-risk — List organizations with Yellow/Red scores (vendor admin)
- GET /api/health-score/history/{entityId} — Weekly score history for trend analysis
- PUT /api/health-score/config — Adjust weights and thresholds (vendor admin)
Validation: - [ ] Health score calculated correctly (verify each dimension) - [ ] Automated lifecycle emails triggered at correct intervals (Day 1,3,7,14,30,90) - [ ] Yellow score → help email sent automatically - [ ] Red score → support ticket created + personal outreach within 48h - [ ] Approaching tier limit → upgrade notification shown - [ ] Cancellation → exit survey displayed + pause/downgrade offers
Result: Proactive customer success. Churn detected early. Expansion opportunities automated.
Step 13.7 — [SOFTWARE] Phase 13 Documentation
- Update
doc/enduser/admin-manual.md(wizard, Go-Live checklist) - Update
doc/developer/api-reference.md(provisioning, health scoring APIs)
Step 13.8 — [SOFTWARE] Update Intranet
Run python doc/intranet/build.py.
Phase 13 — Quality Gate
| # | Check | Target |
|---|---|---|
| 1 | Lead-to-customer pipeline | operational in CRM |
| 2 | Tenant provisioning | < 60 seconds |
| 3 | Configuration wizard | guides admin through setup |
| 4 | CSV import | works with all 5 templates |
| 5 | Go-Live Checklist | functional in admin dashboard |
| 6 | Health scoring | calculated correctly |
| 7 | Automated emails | triggered at correct intervals |
| 8 | Churn prevention | alerts working |
| 9 | Upsell notifications | triggered at tier limits |
| 10 | Documentation + intranet | updated |
| 11 | CLAUDE.md | updated |
Report: "Phase 13 completed. Onboarding automated. Provisioning < 60s. Health scoring active."