This document introduces the key people and personas that guide our architectural decisions. Understanding their needs helps us design solutions that deliver real business value.
Background: Former Head of Growth at a leading ride-sharing company.
Goals:
- Increase customer retention from 20% to 55% within 18 months
- Reduce vehicle unavailability from 25% to under 5%
- Launch in 5 new cities by end of 2026
Pain Points:
- "We're losing €2.3M monthly in missed bookings because vehicles are in the wrong locations"
- "Our ad-hoc usage model isn't building customer loyalty"
- "Manual operations don't scale—we need intelligent automation"
Success Metrics:
- Daily Active Users (DAU) growth
- Customer Lifetime Value (CLV)
- Net Promoter Score (NPS)
Quote: "I need data-driven insights to position vehicles where customers actually need them, not where we guess they'll be."
How We Solve This:
- ADR-02: AI-Driven Demand Forecasting - ML models predict demand 24 hours ahead
- ADR-14: MLOps Pipeline - Automated training, validation, A/B testing
- Analytics Dashboards - Real-time KPI tracking
Impact:
"In the Amsterdam pilot (Phase 2), demand forecasting reduced vehicle unavailability from 25% to 8%, increasing DAU by 22%."
Background: 15 years in fleet management, rose from field coordinator to VP level.
Current Role:
- Oversees 50,000 vehicles across 5 EU cities
- Manages 8 regional operations managers, 120+ field staff
Goals:
- Reduce manual battery swap costs from €15/swap to €6
- Improve fleet utilization from 45% to 75%
- Cut vehicle downtime by 40%
Pain Points:
- "I waste 2 hours every morning reviewing reports from regional managers"
- "Staff spend 60% of their time driving between locations inefficiently"
- "By the time field teams reach vehicles, they're already rented—we need predictive intelligence"
- "Reactive maintenance is 3x more expensive than preventive"
Success Metrics:
- Cost per vehicle operation
- Fleet utilization rate
- Planning time reduction
- Field staff productivity
Quote: "Show me which vehicles need attention RIGHT NOW and optimize my team's routes. Every wasted trip costs us money."
How We Solve This:
- ADR-02: AI Task Prioritization - Prioritizes tasks by urgency × impact, reducing planning time from 2 hours → 15 minutes
- ADR-14: Predictive Maintenance - Predicts failures 7 days ahead with 92% confidence
- WORKFLOWS/STAFF_WORKFLOWS.md - AI-powered task prioritization system
- See Use Case 3 for detailed morning workflow
Impact:
- Planning Time: 2 hours → 15 minutes (88% reduction)
- Cost: €15/swap → €6/swap (AI-optimized)
- Annual Savings: €11.176M from automation + predictive maintenance
Background: Ex-AWS solutions architect with 18 years in cloud platforms and cybersecurity.
Goals:
- Achieve 99.95% uptime with zero security incidents
- Scale infrastructure cost-effectively
- Ensure GDPR, PCI-DSS, ISO 27001 compliance
- Secure 50,000+ IoT devices
Pain Points:
- "Our monolithic architecture can't handle peak demand"
- "We lack observability—troubleshooting takes hours"
- "50,000 IoT devices are potential attack vectors"
- "One data breach destroys our brand and costs millions"
Success Metrics:
- 99.95% uptime SLA compliance
- P95 API latency <200ms
- Zero security incidents
- <24 hour MTTD for threats
Quote: "I need an architecture that scales independently per service, fails gracefully, and embeds security from day one—not as an afterthought."
How We Solve This:
- ADR-01: Microservices - 8 independently scalable services on AWS ECS
- ADR-09: Multi-Region - Active-passive (Frankfurt + Ireland)
- ADR-13: Data Compliance - GDPR, PCI-DSS automation
- See Use Case 5 for incident response example
Impact:
- Uptime: 99.97% actual vs 99.95% target
- Security ROI: €295K/year (breach prevention)
Profile:
- Age: 28, Marketing Manager
- Location: Amsterdam city center
- Usage: Daily 4km commute (home → office)
Pain Points:
- "Half the time, there's no scooter available when I need it"
- "I'd use the app daily if I could rely on it, but I keep Uber as backup"
- "The pricing varies wildly—I can't budget my transport costs"
Needs:
- Predictable availability at her location
- Transparent, consistent pricing
- Ability to pre-book for recurring trips
Quote: "I want to delete Uber and just use MobilityCorp, but I can't risk being late to work."
How We Solve This:
- ADR-02: Predictive Rebalancing - ML predicts Emma's 8:15 AM demand, triggers overnight relocation
- Pre-Booking - 30-minute advance booking guarantee
- See Use Case 1 for full workflow
Impact: Retention improved from occasional user → daily commuter (20% → 58%)
Profile:
- Age: 34, Tourist from London
- Location: Barcelona for 3 days
- Usage: Spontaneous sightseeing trips
Pain Points:
- "I don't know where vehicles are available"
- "The app should suggest routes and attractions"
- "I'm worried about getting fined if I don't park correctly"
Needs:
- Real-time vehicle availability map
- Route recommendations with attractions
- Clear parking instructions in English
Quote: "Make it as easy as Google Maps—I shouldn't need to think about logistics."
How We Solve This:
- ADR-12: Conversational AI - Claude 3.7 Sonnet with multilingual support
- ADR-04: Maps Integration - Route planning and parking zones
- See Use Case 2 for interaction example
Impact: Tourist conversion rate +40% with conversational UI
Profile:
- Age: 41, Teacher with two kids
- Location: Munich suburbs
- Usage: Weekend errands and family outings
Pain Points:
- "Last time, the van was dirty with someone's coffee cup inside"
- "I've had a van run out of charge mid-trip—terrifying with kids"
- "Booking is complicated—too many steps"
Needs:
- Cleanliness verification with photos
- Reliable battery range predictions
- Simple, family-friendly booking flow
Quote: "I need to trust that the vehicle will be clean, charged, and reliable—my kids depend on it."
How We Solve This:
- Battery Health Prediction - ML predicts remaining range with 95% accuracy (±2 km)
- See Use Case 4 for booking journey
Impact: NPS +25 points, "Finally, a rental I can trust with kids"
Profile:
- Age: 32, Fleet Coordinator
- Location: Madrid operations center
- Manages: 12-person field team across 2,000 vehicles
Pain Points:
- "I waste 2 hours every morning planning routes"
- "By the time my team reaches a vehicle, it's already been rented"
- "We don't know which vehicles will actually be needed today"
Needs:
- AI-powered task prioritization
- Dynamic route optimization
- Real-time vehicle status updates
Quote: "Give me a smart system that tells my team exactly where to go and why—don't make me guess."
How We Solve This:
- ADR-02: AI Task Prioritization - Same system as Marcus (VP Fleet Ops) uses
- WORKFLOWS/STAFF_WORKFLOWS.md - Detailed field operations workflow
- See Use Case 3: Marcus's AI-Optimized Morning - Javier's regional workflow mirrors this at city level
Impact:
- Planning Time: 2 hours → 15 minutes
- Wasted Trips: 40% → 8%
- Cost: €15/swap → €6/swap
Profile:
- Age: 27, Support Team Lead
- Location: Copenhagen support center
- Handles: 200+ tickets/day
Pain Points:
- "Customers dispute fines because we lack photo proof"
- "I can't tell if damage was pre-existing or caused by the renter"
- "Manual verification takes 10-15 minutes per case"
Needs:
- Automated photo verification
- Damage detection with timestamps
- Self-service dispute resolution
Quote: "If the system could automatically verify returns and detect damage, I could focus on real customer issues."
How We Solve This:
- Automated Dispute Resolution - 70% of cases auto-resolved with photo evidence
- Audit Trail - Immutable photo history in S3 with 30-day retention
Impact:
- Resolution Time: 15 min → 2 min (87% reduction)
- Auto-Resolution Rate: 70%
- Customer Satisfaction: +25%
| Persona | Key Need | Architectural Solution |
|---|---|---|
| Sarah (CPO) | Predictive demand insights | ML demand forecasting + analytics dashboards |
| Marcus (VP Fleet Ops) | Efficient resource allocation | AI route optimization + battery prioritization |
| David (CTO/CISO) | Scalable, resilient, secure infrastructure | Microservices + multi-region + zero-trust security |
| Emma (Commuter) | Reliable availability | Predictive rebalancing + pre-booking |
| Alex (Tourist) | On-demand discovery | Real-time availability + conversational AI |
| Lisa (Family User) | Vehicle quality assurance | Computer vision damage detection |
| Nina (Support) | Automated verification | Vision AI + automated dispute resolution |
Throughout our documentation, we reference these personas to illustrate:
- Requirements: "Emma needs reliable availability → Predictive rebalancing"
- ADRs: "David requires independent scaling → Microservices architecture"
- Workflows: "Javier's morning routine → AI task prioritization flow"
- Success Metrics: "Sarah measures retention → Track CLV improvements"
Example Usage:
"When Emma opens the app at 8:00 AM, the Demand Forecasting Service has already predicted high demand for her neighborhood and triggered the Relocation Incentive System to position scooters nearby (see ADR-02)."
- Reliability First (Emma, Lisa) → 99.95% uptime, predictive maintenance
- Operational Efficiency (Marcus) → AI-driven automation, cost reduction
- Scalability & Security (David) → Microservices, multi-region, zero-trust architecture
- User Experience (Alex, Nina) → Conversational AI, automated verification
- Data-Driven Decisions (Sarah, Marcus) → Real-time analytics, ML insights
These personas guide every architectural decision, ensuring we solve real problems for real people.
This matrix shows exactly where each persona's needs are addressed in our architecture:
| Persona | Core Solution | Primary ADR | Workflow | Business Metric |
|---|---|---|---|---|
| Sarah (CPO) | ML Demand Forecasting | ADR-02 | Customer Discovery | Retention: 20% → 55% |
| Marcus (VP Fleet Ops) | AI Relocation Incentives | ADR-02 | Staff Workflows | Cost: €15 → €6/swap |
| David (CTO/CISO) | Microservices + Multi-Region + Zero-Trust | ADR-01, ADR-09, | Event Storming | Uptime: 99.95% SLA, Zero breaches |
| Emma (Commuter) | Predictive Rebalancing | ADR-02 | Booking Flow | Availability: 75% → 95% |
| Alex (Tourist) | Conversational AI | ADR-12 | Customer Workflows | Conversion: +40% |
| Lisa (Family User) | Computer Vision Quality | Computer Vision AI | Return Verification | NPS: +25 points |
| Nina (Support) | Automated Dispute AI | Computer Vision AI | Support Automation | Auto-resolve: 70% |
Actors: Emma (Commuter), Sarah (CPO tracking retention), Marcus (VP Fleet Ops executing AI tasks)
Scenario Timeline:
Day Before (11:00 PM):
• Emma pre-books scooter for 8:15 AM
• Demand Forecasting Service predicts high demand in Emma's neighborhood
• System identifies scooter surplus 2 km away
• AI offers €3 credit to User-XYZ to relocate scooter near Emma's apartment
• User-XYZ accepts, drops scooter 50m from Emma's location
Morning (8:00 AM):
• Emma opens app, sees reserved scooter with 95% battery
• System sends push notification: "Your scooter is ready at corner of Main St"
• Emma walks 50m, NFC unlock, AI takes pickup photo (no damage detected)
Post-Rental:
• Sarah's dashboard: Emma completed 22 consecutive daily commutes this month
• Retention algorithm marks Emma as "High-Value Commuter" (CLV: €180/month)
• Business Impact: Emma deleted Uber app, now 100% MobilityCorp user
Systems Involved:
- Demand Forecasting Service (ADR-02)
- Relocation Incentive Engine (ADR-02)
- Booking Service (ADR-01)
- Vehicle Telemetry (ADR-03)
- Analytics Dashboard (ADR-14)
Success Metrics: Emma's retention → 100% | Sarah's KPI: +22% DAU | Marcus's cost: €3 AI incentive vs €15 manual
Actors: Alex (Tourist), David (CTO monitoring system performance)
Conversation Flow:
Alex: "I'm at Sagrada Familia. Show me scooters nearby."
AI Assistant (Claude 3.7 Sonnet):
"I found 8 scooters within 200m. The closest one is €2.50 for 30 min.
Would you like me to reserve it?"
Alex: "Yes, and suggest a route to Park Güell with scenic views."
AI Assistant:
"Reserved! Here's a 4.2 km route passing through Gothic Quarter.
Estimated 18 min. I'll guide you turn-by-turn.
Note: Park Güell has paid parking in blue zones—I'll show you where."
[Alex completes rental, AI prompts for feedback]
Alex: "Great experience! How do I explore more neighborhoods tomorrow?"
AI Assistant:
"I recommend the Waterfront Loop: 6 km through Barceloneta Beach and
Port Vell. Pre-book an eBike tonight—better for longer distances."
Systems Involved:
- Conversational AI Service (ADR-12)
- Google Maps API (ADR-04)
- Vehicle Telemetry (ADR-03)
- Booking Service (ADR-01)
David's Tech Monitoring:
- API Response Time: 120ms P95 (target: <200ms) ✅
- LLM Token Cost: $0.08 per conversation (budget: $0.15) ✅
- Uptime: 99.97% during tourist season ✅
Business Impact: Tourist conversion +40% | Alex's NPS: 10/10 | LLM cost: $0.08 vs €4.20 booking revenue (1.9% overhead)
Actors: Marcus (VP Fleet Operations)
Before AI (Manual Process):
6:00 AM: Marcus reviews spreadsheet of 2,000 vehicles (Madrid region)
6:30 AM: Manually identifies 50 vehicles needing attention
7:00 AM: Assigns tasks based on staff proximity (rough estimates)
8:00 AM: Team deployed, but 15 vehicles already rented (wasted trips)
10:00 AM: Reactive battery swaps as vehicles die mid-rental
Cost: €15 per manual swap × 50 vehicles = €750/day
Efficiency: 40% wasted trips, 2 hours planning time
After AI (Automated Prioritization):
6:00 AM: Marcus opens AI-powered dashboard
6:05 AM: AI task list ready (prioritized by urgency × impact)
Top Priority Tasks:
1. Battery Swap - E-SCOOT-1247 (Salamanca)
• Current: 15% battery
• Predicted Demand: 8-9 AM peak (85% probability)
• Lost Revenue if Unavailable: €45
• Action: Assign to Carlos (2.3 km away, ETA 8 min)
2. Preventive Maintenance - E-BIKE-0893 (Retiro Park)
• Brake sensor anomaly detected
• 7-day failure prediction (92% confidence)
• Cost Avoidance: €200 reactive repair → €50 preventive
• Action: Assign to Maria (1.8 km away, ETA 12 min)
3. AI Relocation - E-CAR-0456 (Low-demand suburb)
• Relocation Incentive: €3 credit offered to 5 users
• Status: Wait 2 hours before manual intervention
• Cost Savings: €5 (€8 manual - €3 AI incentive)
6:15 AM: Marcus approves, team dispatched with optimized routes
9:30 AM: All critical tasks completed, zero wasted trips
Cost: €6 per AI-optimized swap × 35 vehicles = €210/day
Efficiency: 8% wasted trips, 15 min planning time
Marcus's Business Dashboard:
- Daily Cost Savings: €540/day (€750 - €210)
- Annual Savings: €197K per city (€540 × 365)
- Fleet Utilization: 45% → 75% (+30 percentage points)
- Wasted Trips: 40% → 8% (-32 percentage points)
Systems Involved:
- AI Task Prioritization (ADR-02)
- Predictive Maintenance (ADR-07)
- Route Optimization (ADR-04 Maps API)
- Fleet Operations Service (ADR-01)
Actors: Lisa (Family User), Nina (Support Agent), David (CTO/CISO auditing data handling)
Booking Journey:
Thursday 8:00 PM: Lisa books family van for Saturday 9:00 AM
↓ [System shows van's latest inspection photos]
↓ [Computer Vision Quality Score: 9/10 (clean, no damage)]
↓ [Battery Health: 85% charge = 180 km range (±2 km accuracy)]
Lisa reviews photos:
• Exterior: No scratches, clean body
• Interior: Vacuumed, no trash, car seat anchor visible
• Battery: Sufficient for 40 km round trip to store + activities
Lisa confirms booking, pre-authorized payment: €45
Saturday 8:50 AM: Lisa arrives at van, opens app
↓ [App prompts: "Take 4 photos - front, rear, interior, dashboard"]
↓ [Lisa uploads photos, AI processes in 3 seconds]
↓ [Computer Vision detects: No new damage, cleanliness matches]
↓ [Family profile detected: Kid car seat in back row ✅]
Rental starts: 9:00 AM - 2:30 PM (5.5 hours)
Return: Lisa parks van, takes return photos
↓ [AI detects: Minor coffee stain on floor mat]
↓ [Damage Assessment: Below damage threshold (€0 charge)]
↓ [Cleanliness Score: 8/10 (acceptable, flagged for cleaning)]
Payment: €42.50 charged (base rate, no damage fees)
Lisa's Receipt: "Thank you! Minor cleaning needed (no charge to you)."
Nina's Support View (No Action Needed):
Dashboard Alert: Van-0456 needs cleaning before next rental
Action: Automated task assigned to cleaning crew
Status: ✅ No customer dispute (AI auto-resolved with photo evidence)
David's Security Audit:
Data Handling Check:
• Photos stored in S3 with AES-256 encryption ✅
• Retention: 30 days, auto-deleted after (GDPR compliant) ✅
• PII redaction: License plates blurred in stored images ✅
• Access logs: Only Lisa, Nina, and authorized staff viewed photos ✅
Business Impact:
- Lisa's NPS: 9/10 ("Finally, a rental I can trust with kids")
- Nina's workload: 0 tickets from this rental (AI handled everything)
- Damage dispute cost: €0 (auto-resolved with photo evidence)
- David's compliance audit: ✅ Passed GDPR data handling review
Systems Involved:
- Booking Service (ADR-01)
- Payment Service (ADR-05)
- Data Compliance (ADR-14)
- Support Dashboard (ADR-10 observability)
Actors: David (CTO/CISO), Operations Team
Incident Timeline:
Monday 2:14 AM: Suspicious activity detected
↓ [CloudWatch Alarm: 5 failed MFA attempts from non-EU IP (185.x.x.x)]
↓ [VictoriaMetrics: Login attempts for admin account "fleet-ops-admin"]
↓ [Automated Response: Account temporarily locked after 3rd failure]
2:15 AM: David's SOC team receives PagerDuty alert
↓ [On-call engineer reviews CloudWatch logs]
↓ [Identifies credential stuffing attack (leaked password database)]
↓ [Attacker attempted 47 passwords in 2 minutes]
2:20 AM: Immediate Response
↓ [WAF rule deployed: Block IP range 185.x.x.0/24]
↓ [User account password reset enforced]
↓ [Email sent to account owner: "Suspicious login detected, password reset required"]
2:25 AM: Threat Assessment
↓ [Zero-trust architecture prevented breach]
↓ [No services accessed (MFA blocked attacker at auth layer)]
↓ [No data exfiltrated (attacker never reached API layer)]
Tuesday 9:00 AM: Post-Incident Review
↓ [David presents incident report to executive team]
↓ [MTTD: 1 minute (alarm triggered immediately)]
↓ [MTTR: 11 minutes (attacker blocked, user secured)]
↓ [Root Cause: Employee password leaked in 3rd-party breach]
↓ [Action Plan: Mandatory password rotation + security training]
David's Resilience Dashboard:
Incident Impact Analysis:
• Services Affected: 0 (zero-trust prevented lateral movement)
• Data Breached: 0 bytes
• Downtime: 0 seconds
• Customer Impact: 0 users affected
• SLA Compliance: ✅ 99.97% uptime maintained
Security Posture:
• MFA Enforcement: 100% (blocked attacker)
• WAF Rules: Updated with new threat intelligence
• Incident Response Time: 11 minutes (target: <24 hours)
David's Compliance Report:
ISO 27001 Audit Trail:
✅ Incident detected within SLA (<24 hours MTTD)
✅ Zero-trust prevented unauthorized access
✅ User notified within 6 hours (GDPR requirement)
✅ Threat intelligence shared with AWS Shield
✅ Post-incident training scheduled for affected user
SOC 2 Type II Evidence:
• Access controls prevented breach
• Monitoring systems detected anomaly
• Incident response playbook executed correctly
• No customer data compromised
Business Impact:
- Financial Loss: €0 (no data breach, no downtime)
- Reputational Risk: Mitigated (incident contained before escalation)
- Compliance Status: ✅ Maintained (GDPR, ISO 27001, SOC 2)
- Customer Trust: Preserved (zero users affected)
David's Quote: "This is why we invested in zero-trust. The attacker never got past the front door."
Systems Involved:
- Zero-Trust Architecture
- AWS IAM + MFA
- CloudWatch Logs (ADR-10)
- VictoriaMetrics (ADR-10)
- WAF Rules
- Incident Response Playbook
Actors:
Emma (Commuter, subscription user)
Booking Microservice (Subscription Management)
Sarah (CPO tracking engagement & loyalty)
Billing Service (Handles payments & cancellation fees)
Scenario Timeline:
Day 1 (Start of Month): • Emma enrolls in the Daily Commute Subscription. • She sets her commute time for 8:15 AM on weekdays. • Subscription benefits: lower daily rate, automatic booking, predictable monthly cost. • Policy: If Emma cancels her ride less than 2 hours before the 8:15 AM slot, a small cancellation fee applies. Cancelling 2+ hours before = no fee. Daily (Ongoing):
Each morning, a scooter is automatically reserved for Emma.
Emma is reminded: “Your scooter is ready at your usual location!”
If Emma needs to skip a ride: - Cancels via app by 6:15 AM or earlier ⇒ No fee - Cancels after 6:15 AM, or is a no-show ⇒ Small cancellation fee is charged
Emma completes her ride or manages cancellations directly in the app.
End of Month: Emma receives a summary showing ride savings, cancellation instances, and any fees from late cancellations.
Systems Involved:
- Booking Microservice (recurring bookings, cancellation window enforcement)
- Billing Service (applies subscription charges and any late cancellation fees)
- Push Notification Service (booking and cancellation reminders)
- Analytics Dashboard (tracks usage, cancellations, and engagement)
Success Metrics:
- Subscription adoption and renewal rates
- % rides serviced as scheduled without late cancellations
- Increase in daily active commuters
- Predictive accuracy for demand and fleet allocation
How This Solves Emma’s Needs:
- Guaranteed scooter availability for her regular commute
- Predictable, budget-friendly monthly costs
- Easy, flexible cancellation with fair fee structure
- Improved reliability encourages full switch from competitor apps
Impact:
- Increased user retention and lifetime value
- Higher average ride consistency and reduced churn
- Better forecasting and operational efficiency for the business
- README.md - Complete architecture overview and business case
- PHASED_IMPLEMENTATION.md - €30.5M NPV migration plan with persona success stories
- EVENT_STORMING.md - Domain events and bounded contexts derived from persona workflows
- QUICK_REFERENCE.md - Navigation guide by role (CTO, CFO, CPO, Engineers)
- ADR/ - 19 Architecture Decision Records with persona-driven rationale