Home ▸ Phases (0-13) ▸ Phase 4: Admin App

PHASE 4: Admin Web App (Flutter)

Trigger: "Execute Phase 4 as per masterplan."

Goal: A web-based admin interface for club/studio administrators: member management, contract management, billing, settings, user/role management, reports. Multi-language support (32 languages) with RTL.

Prerequisite: Phase 3 is completed.

Step 4.0 — Technical Conception

Create doc/developer/conception/phase-4-conception.md.

(reference: Chapter 09 — Frontend Strategy, Chapter 08 — User Journeys)

Content: - Scope: Admin web app (Flutter Web), responsive layout, 8 main navigation areas - Component Design: Shared codebase with mobile (conditional routing by role + platform) - Admin-Specific Widgets: DataTable with server-side pagination, filter bar, bulk actions - Role-Based Navigation: Navigation items filtered by user permissions from JWT - Design Chapter References: Ch07 (Roles), Ch08 (Journey 2: Admin Member Management), Ch09

Result: Technical conception for Phase 4.

Step 4.1 — Admin Scaffold and Navigation

(reference: Chapter 09 — Frontend Strategy)

  1. Responsive layout: NavigationRail (desktop) / Drawer (tablet)
  2. Dashboard as landing page
  3. Navigation: Dashboard, Members, Contracts, Transactions, Products, Settings, Users, Reports

Result: Admin shell with responsive layout.

Step 4.2 — Member Management

(reference: Chapter 08 — Journey 2: Admin Member Management)

Approach:

  1. Member List (DataTable): - Columns: avatar, name, member number, status (chip), membership template, join date, balance - Search: full-text across name, email, member number, phone - Filters: status (Active/Suspended/Cancelled), membership template, date range, balance (positive/negative/zero) - Sorting: any column, server-side - Pagination: configurable page size (25/50/100), server-side - Bulk actions: export CSV, send email, change status, assign membership - Row click → member detail

  2. Member Detail (tabbed layout): - Tab 1 — Personal Data: Name, email, phone, address, birthday, gender, memberNumber, photo upload, custom attributes (dynamic JSONB form with configured fields from Organization.memberAttributes) - Tab 2 — Emergency Contacts: List with name, phone, relationship; add/edit/delete - Tab 3 — Contracts: Active + historical contracts, status badge, start/end date, price, cancel/suspend buttons - Tab 4 — Transactions: Transaction list (date, description, amount, status), balance summary, manual payment button, storno button - Tab 5 — Check-ins: Check-in history (date, time, zone, method), attendance chart, frequency stats - Tab 6 — Documents: Linked documents (contracts, invoices), upload, download, preview - Tab 7 — Notes: Admin notes (AuditLog with type ADMIN_NOTE), trainer notes (read-only)

  3. Create Member Wizard (4 steps): - Step 1 — Personal data (name, email, phone, address, birthday, gender) - Step 2 — Bank account (IBAN, account holder, SEPA mandate checkbox) - Step 3 — Membership selection (template list, start date, first billing date) - Step 4 — Confirmation summary → create member + bank account + contract in single transaction

  4. Apply Gestalt Laws: grouped form sections (proximity), consistent status chips (similarity), progress stepper (continuity)

Result: Full admin member management with tabbed detail view and creation wizard.

Step 4.3 — Contract and Billing Management

(reference: Chapter 08 — Journey 2, Journey 6)

Approach:

  1. Membership Template Management: - CRUD for templates: name, description, price, billing cycle, minimum term, cancellation notice, age restrictions, capacity, features (JSONB checklist), visibility - Template list: DataTable with name, price, active contracts count, status - Archive template (can't delete if active contracts exist)

  2. Contract Overview: - DataTable: member name, template, status (chip), start date, end date, monthly price - Filters: status (ACTIVE/PENDING/CANCELLED/EXPIRED/SUSPENDED), template, date range - Actions: cancel (with reason, validates notice period), suspend, resume, view detail - Contract detail: all fields, linked transactions, status history

  3. Billing Dashboard: - Cards: total open debt, MRR (monthly recurring revenue), this month's billing, failed payments count - Open transactions table: overdue items sorted by age - Manual billing trigger button (for testing/ad-hoc) - SEPA export history with download

  4. Dunning Management: - Overdue transactions list (days overdue, amount, member, attempts) - Status: overdue → reminder sent → in debt collection - Actions: send reminder, record payment, escalate, write off

Result: Complete financial management: templates, contracts, billing, and dunning.

Step 4.4 — Club Settings and User Management

(reference: Chapter 07 — User Roles and Permissions)

Approach:

  1. Organization Settings (tabbed): - General: Name, address, phone, email, logo upload, timezone, locale, currency - Password Policy: Min length, require uppercase/number/special, lockout attempts, lockout duration - Custom Attributes: Define custom fields for members (JSONB schema editor: field name, type, required, options) - Feature Toggles: Enable/disable modules (shop, courses, check-in, franchise, etc.) - Billing Settings: Billing day (1-28), payment methods enabled, dunning schedule, My-Factura API key - Branding: Primary color, accent color, email footer text, homepage config

  2. User Management: - User list: DataTable with name, email, role, last login, status - Create/edit user: name, email, role selection (dropdown from ~16 seed roles), force password change - Deactivate/reactivate user (soft delete, preserves audit trail) - Role assignment: hierarchical display (System Admin → Org Owner → Club Admin → Staff → Receptionist → Trainer) - Permission matrix: read-only view of selected role's permissions (from Chapter 07 matrix)

  3. Data Export: - Export members: CSV, Excel (XLSX), JSON — configurable columns - Export transactions: CSV with date range filter - Export contracts: CSV with status filter - GDPR Art. 20: Member data portability export (JSON, all personal data)

Result: Admins configure organization, manage users/roles, and export data.

Step 4.5 — Reports and Dashboard

(reference: Chapter 08 — Journey 5: Executive KPI Review)

Approach:

  1. Dashboard (landing page): - Row 1 — KPI Cards: Total active members, new registrations (this month), MRR (EUR), open debt (EUR), check-ins (today), contracts expiring (next 30 days) - Row 2 — Charts: Member growth trend (line chart, 12 months), revenue by month (bar chart), membership distribution (pie chart by template) - Row 3 — Action Items: Overdue payments (count + link), pending contracts (count + link), open support tickets (count + link) - Cards clickable → navigate to respective list view

  2. Reports Page (tabbed): - Demographics: Age distribution (histogram), gender split, geographic distribution (city/country) - Financial: Revenue by month, revenue by membership template, average revenue per member, churn-related revenue loss - Retention: Churn rate (monthly/annual), member lifetime, retention curve, cancellation reasons (pie chart) - Activity: Check-in frequency (daily heatmap), peak hours, average duration, popular resources/courses - Growth: New vs. cancelled (net growth chart), lead conversion rate (if CRM active), trial-to-paid rate - Date range picker (preset: this month, last 3 months, this year, custom)

  3. Export: Every report exportable as PDF (chart snapshots) or CSV (raw data)

Result: Data-driven admin dashboard with KPIs, charts, and exportable reports.

Step 4.6 — Internationalization (i18n)

(reference: Rule 11, Rule 18)

All admin UI via AppLocalizations, language switcher (32 languages), RTL verification for Arabic, admin-specific translation keys.

Step 4.7 — Phase 4 Documentation

  1. Create doc/enduser/admin-manual.md (admin web app guide)
  2. Update doc/developer/frontend-guide.md (admin architecture, responsive patterns)

Step 4.8 — Update Intranet

Run python doc/intranet/build.py.

Phase 4 — Quality Gate

# Check Target
1 Conception exists
2 flutter analyze 0 issues
3 flutter test all pass
4 Admin flow login -> create member -> assign membership -> billing -> report
5 Role enforcement MEMBER role cannot access admin screens
6 RTL layout Arabic admin screens correct
7 Documentation admin-manual exists
8 Intranet + CLAUDE.md updated

Report: "Phase 4 completed."

---