PHASE 11: Launch Preparation
Trigger: "Execute Phase 11 as per masterplan."
Goal: Migration tooling ready (project structure, entity mapping, validation queries), user documentation complete, operations documentation complete, production deployment operational with Helm charts, beta testing with early clients.
Prerequisite: Phase 10 is completed.
Step 11.0 — Technical Conception
Create doc/developer/conception/phase-11-conception.md.
(reference: Chapter 15 — Migration Strategy, Chapter 14 — Infrastructure)
Content: - Scope: Migration tool, documentation finalization, operations docs, Helm charts, beta - Migration Architecture: Standalone Spring Boot app, entity mapping table, execution order - Helm Chart Design: Chart structure, values files per environment, probes, resource limits - Staging Environment: Scaled-down production replica for beta testing - Design Chapter References: Ch14, Ch15
Result: Technical conception for Phase 11.
Step 11.1 — Migration Tooling
(reference: Chapter 15 — Migration Strategy)
Approach:
- Project Structure:
membership-migration/ ├── pom.xml ├── src/main/java/com/membership/migration/ │ ├── MigrationApplication.java │ ├── config/ │ │ ├── SourceDatabaseConfig.java (Cash360 DB connection) │ │ └── TargetDatabaseConfig.java (Membership DB connection) │ ├── mapper/ │ │ ├── EntityMapper.java (McEntity -> Organization) │ │ ├── UserMapper.java (McUser/McLogin -> User) │ │ ├── MemberMapper.java (CsrConsumer -> Member) │ │ ├── TemplateMapper.java (products -> MembershipTemplate) │ │ ├── ContractMapper.java (contracts -> Contract) │ │ ├── BankAccountMapper.java (CsrBankAccount -> BankAccount) │ │ └── TransactionMapper.java (PmTransaction -> Transaction) │ ├── executor/ │ │ ├── MigrationExecutor.java (orchestrates migration order) │ │ └── ValidationExecutor.java (post-migration checks) │ └── report/ │ └── MigrationReportGenerator.java (HTML report) - Entity Mapping Table (from Chapter 15):
| Cash360 Entity | Membership Entity | Key Transformations |
|---|---|---|
McEntity |
Organization |
statusCd -> status enum, settings JSONB merge |
McUser + McLogin |
User |
Join on id_mc_login, password hash migration |
CsrConsumer |
Member |
customAttributes JSONB, memberNumber generation |
product/pricing |
MembershipTemplate |
Price as BigDecimal, billing cycle mapping |
CsrContract2Product |
Contract |
Status mapping, date normalization |
CsrBankAccount |
BankAccount |
IBAN validation, SEPA mandate |
PmTransaction |
Transaction |
Amount as BigDecimal, status mapping |
-
Execution Order: Organizations -> Users -> Members -> MembershipTemplates -> Contracts -> BankAccounts -> Transactions
-
Validation Queries:
| # | Check | SQL Pattern | Pass Criteria |
|---|---|---|---|
| 1 | Record count | SELECT COUNT(*) FROM {target} WHERE migration_batch_id = ? vs. source count |
Exact match |
| 2 | Financial sum | SELECT SUM(amount) FROM transaction WHERE entity_id = ? |
Difference < 0.01 EUR |
| 3 | FK integrity | SELECT t.id FROM contract t LEFT JOIN member m ON t.member_id = m.id WHERE m.id IS NULL |
0 orphans |
| 4 | Unique check | SELECT member_number, COUNT(*) FROM member GROUP BY member_number HAVING COUNT(*) > 1 |
0 duplicates |
| 5 | Date sanity | SELECT id FROM contract WHERE start_date > end_date |
0 results |
| 6 | IBAN format | SELECT id FROM bank_account WHERE iban NOT SIMILAR TO '[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}' |
0 invalid |
| 7 | Email format | SELECT id FROM member WHERE email IS NOT NULL AND email NOT LIKE '%@%.%' |
0 invalid |
| 8 | Random sample | 5% of records: compare source fields vs. target fields for {name, email, iban, amount} | 100% match |
-
Migration Report (HTML): - Header: Source system, target entity, migration date, operator, duration - Summary table: Entity type, source count, migrated count, skipped count, error count - Validation results: Each of 8 checks with pass/fail badge - Financial reconciliation: SUM comparison per entity, per status - Warnings: Data quality issues (e.g., 15 members without email, 3 bank accounts without BIC) - Error log: Per-row errors with source row number, field, expected, actual - Rollback command: SQL DELETE statements to undo migration if needed
-
Tests with Cash360 test database (the Docker
cashcontrol-testdbat port 5432/5433)
Result: Migration tool that can migrate a Cash360 client in < 30 minutes.
Step 11.2 — User Documentation (Final Review)
Approach:
- Review and finalize all 4 end-user documents:
| Document | Target Audience | Content Sections |
|---|---|---|
admin-manual.md |
Club Admin, Receptionist | Dashboard, members, contracts, billing, courses, resources, check-in, reports, settings, users |
consumer-manual.md |
Members (mobile app) | Registration, login, memberships, QR code, courses, shop, profile, support |
trainer-manual.md |
Trainers | Dashboard, courses, attendance, notes, schedule, member profiles |
faq.md |
All users | 40+ Q&A across 8 categories: Getting Started, Members, Billing, Check-in, Courses, Shop, Reports, Troubleshooting |
-
Admin Manual Structure: - Chapter 1: Getting Started (login, dashboard overview, first steps) - Chapter 2: Member Management (create, search, edit, import, export, custom attributes) - Chapter 3: Contracts and Memberships (templates, purchase flow, cancellation, renewal) - Chapter 4: Billing and Payments (billing cycle, transactions, SEPA, storno, reports) - Chapter 5: Courses and Events (schedule, registration, attendance, trainers) - Chapter 6: Resources and Booking (rooms, equipment, calendar, conflicts) - Chapter 7: Check-in and Access Control (QR, kiosk, zones, logs) - Chapter 8: Communication (email templates, notifications, bulk messaging) - Chapter 9: CRM and Sales (leads, pipeline, conversion) - Chapter 10: Support (tickets, knowledge base, SLA) - Chapter 11: Accounting (ledger, DATEV export, period close) - Chapter 12: Reports (dashboard, demographics, financial, retention) - Chapter 13: Settings (organization, branding, users, roles, integrations) - Appendix A: Keyboard Shortcuts - Appendix B: Status Codes Reference
-
Quick-start guide section at top of admin manual (1-page summary of first 5 steps)
- Video scripts for 5 key workflows (ready for screen recording)
- Ensure all docs reflect final application state (post-Phase 10 features)
- Accessibility: All docs include alt-text descriptions for screenshots
Result: 4 complete end-user documentation files covering all features.
Step 11.3 — Operations Documentation and Helm Charts
(reference: Chapter 14 — Infrastructure)
Approach:
- Create
doc/operations/deployment-guide.md: - Production deployment (Docker, Kubernetes, Helm) - Blue/green deployment, rollback procedures - Create
doc/operations/monitoring-guide.md: - Prometheus metrics, Grafana dashboards, alerts - Create
doc/operations/support-runbook.md: - Common scenarios, troubleshooting, escalation, log analysis -
Create
doc/operations/itops-guide.md: - Infrastructure overview, backup/recovery, scaling, security hardening -
Helm Chart Structure:
infra/k8s/helm/membership/ ├── Chart.yaml ├── values.yaml (defaults) ├── values-dev.yaml (development overrides) ├── values-staging.yaml (staging overrides) ├── values-production.yaml (production overrides) └── templates/ ├── deployment.yaml (app pods: replicas, resources, env) ├── service.yaml (ClusterIP service) ├── ingress.yaml (Ingress with TLS) ├── configmap.yaml (non-secret config) ├── secret.yaml (sealed-secrets reference) ├── hpa.yaml (HorizontalPodAutoscaler) ├── pdb.yaml (PodDisruptionBudget) └── _helpers.tpl (template helpers) -
Probes: - Readiness:
GET /actuator/health/readiness(checks DB, Redis, RabbitMQ) - Liveness:GET /actuator/health/liveness(checks app is responsive) - Startup: 60s grace period for Flyway migrations -
Values per environment:
| Setting | dev | staging | production |
|---|---|---|---|
| Replicas | 1 | 2 | 3 (HPA 3-6) |
| CPU request / limit | 250m / 500m | 500m / 1000m | 500m / 2000m |
| Memory request / limit | 512Mi / 768Mi | 1Gi / 1.5Gi | 2Gi / 3Gi |
| Log level | DEBUG | INFO | WARN |
| PDB minAvailable | — | 1 | 2 |
| Ingress TLS | self-signed | Let's Encrypt staging | Let's Encrypt production |
| Database | Testcontainers | Hetzner managed PG (dev) | Hetzner managed PG (prod) |
| Redis | Docker sidecar | Hetzner Redis | Hetzner Redis |
| RabbitMQ | Docker sidecar | Hetzner RabbitMQ | Hetzner RabbitMQ |
| MinIO/S3 | Docker MinIO | Hetzner Object Storage | Hetzner Object Storage |
| Secrets | plain (dev only) | sealed-secrets | sealed-secrets |
Result: Operations documentation and production-ready Helm charts.
Step 11.4 — Beta Testing and Staging
Approach:
-
Staging Deployment: - Deploy full stack to Hetzner staging (values-staging.yaml) - Seed with realistic data: 5 organizations, 500 members, 200 contracts, 1,000 transactions - Run all E2E tests (Step 10.3) against staging - Verify all external integrations: Cash360 sandbox, email delivery, Push notifications
-
Beta Client Selection (3-5 clients):
| # | Client Type | Source | Expected Feedback Focus |
|---|---|---|---|
| 1 | Small studio | Personal network | Usability, setup wizard, billing |
| 2 | Medium club | Cash360 migration | Migration quality, feature parity |
| 3 | Sports association | Cold outreach | Events, courses, member management |
| 4 | Franchise (2+ locations) | Partner referral | Multi-location, franchise dashboard |
| 5 | Trial (self-onboarding) | Website signup | Self-service flow, documentation |
-
Beta Program Structure (30-60 days): - Week 1: Onboarding call (30 min), account setup, data migration (if applicable) - Week 2-3: Daily usage, in-app feedback widget (Canny or custom), Slack channel for support - Week 4: Structured feedback session (45 min video call, prepared questions) - Week 5-6: Issue fixes deployed to staging, re-testing - Week 7-8: Final validation, production readiness sign-off
-
Feedback Collection: - In-app widget: screenshot + description (auto-captures URL, browser, user role) - Weekly 15-min check-in calls (Professional/Enterprise clients) - NPS survey at Day 14 and Day 30 - Structured exit survey: feature gaps, UX friction, would-recommend score
-
Production Smoke Tests: - After each staging deployment: health check, login, create member, run billing, check-in - Automated via CI/CD pipeline (reuse E2E test subset)
Result: 3-5 beta clients actively using the system. Feedback collected and prioritized.
Step 11.5 — Update Intranet
Run python doc/intranet/build.py.
Phase 11 — Quality Gate
| # | Check | Target |
|---|---|---|
| 1 | Conception | exists |
| 2 | Migration tool | tested with Cash360 test data |
| 3 | Migration report | HTML report generated |
| 4 | User docs | all 4 enduser docs complete |
| 5 | Operations docs | all 4 operations docs complete |
| 6 | Helm charts | helm template validates without errors |
| 7 | Staging deployment | app running on staging |
| 8 | Beta clients | 3+ actively using system for 30+ days |
| 9 | Rollback tested | rollback procedure verified |
| 10 | Documentation + intranet | updated |
| 11 | CLAUDE.md | updated |
Report: "Phase 11 completed. System ready for launch."