Flutter Account Creation: Triptych & Bug Fixes

Hey there, team! Let's dive into a crucial part of our Flutter app: the Create Account flow. This task is all about fixing some pesky bugs using the "Triptych" method we learned in class. We'll be focusing on making sure account creation is robust, reliable, and user-friendly. Ready to get started?

🎯 Objective: Mastering the Create Account Flow

Our main goal is to use the Triptych framework (Domain → Requirements → Design) to squash bugs in the Create Account process of our Flutter app. We need to define domain terms, set up clear, measurable requirements, redesign the flow where necessary, and verify our code changes with thorough testing. Think of it as a comprehensive makeover for the signup process!

📝 Description: Fixing the Bugs

So, what's wrong with our current Create Account page? Well, we've spotted a few issues, including:

• Duplicate Submits: Users might accidentally create multiple accounts by hitting the submit button more than once.
• Validation Mismatches: Client-side and server-side validation don't always agree, leading to confusing error messages.
• Lack of Email Uniqueness: Users can sign up with the same email multiple times.
• Inconsistent Error States: Error messages aren't always displayed correctly.
• Race Conditions in Email Verification: Problems with the email verification and cooldown features can lead to issues.

We'll tackle these issues using the Triptych approach to make our account creation process smooth and reliable. This means we'll nail down the domain specifics, figure out the exact requirements, design the changes, and confirm everything works with tests. Let's make this signup process rock solid, guys!

✅ Acceptance Criteria: What Success Looks Like

To consider this task complete, we need to meet a bunch of criteria. Here's the checklist:

• Domain Glossary: A clear explanation of all the terms related to account creation is available under /docs.
• Testable Requirements: Requirements are spelled out and can be tested. This includes:
  • Idempotency: Submitting multiple times doesn't create duplicate accounts.
  • Uniqueness: Each email address can be used only once.
  • Cooldown: Users must wait a certain time before resending a verification email.
  • Expiry: Verification tokens expire after a certain time.
  • Accessibility: The UI is usable by everyone, including people with disabilities.
• Design Artifacts: We need a statechart (that shows the lifecycle) and sequence diagrams (that show the happy and negative paths) to visualize the process.
• UI Prevention of Duplicate Submits: The button is disabled and debounced while submitting to prevent double submissions.
• Idempotent Account Creation: Retries don't create duplicates. We'll verify this through tests and telemetry.
• Authoritative Server-Side Validation: The server validates everything, and the client displays these messages.
• Enforced Email Uniqueness: The database and API ensure that each email is unique. There's a friendly error message in the UI if an email is already in use.
• Robust Verification Flow: The verification flow handles resend cooldowns and token expiry without problems.
• Consistent Error States: Error messages are clear, accessible, and follow focus management, and screen-reader announcements are in place.
• Logging/Metrics: We'll log and track:
  • Duplicate account prevention.
  • Verification failures.
  • The time it takes for a user to successfully sign up.

Basically, we're building a system where account creation is smooth, secure, and user-friendly. Sounds good, right?

🧪 Testing Plan: Making Sure It Works

We're going to use various tests to make sure everything works perfectly. Here’s the plan:

• Unit Tests (Dart): We'll test:
  • Email/password validators.
  • The idempotency key generator.
  • Cooldown and expiry helpers.
• Widget Tests: These tests will cover:
  • The button disabling and showing a spinner during submission.
  • Inline errors rendering and focus jumping to the first invalid field.
• Integration Tests (API): We'll test:
  • Duplicate submissions and network retries.
  • Proper error mapping for already-used email addresses.
  • The recovery path for expired or invalid verification tokens.
• E2E (Cypress/Flutter integration): These end-to-end tests will cover:
  • The happy path: create → verify → auto-login/redirect to Home.
  • Blocking resends during cooldown and allowing them after the cooldown period.
  • Idempotency using simulated network timeouts and retries.
• Accessibility Checks: We'll make sure the app is accessible by checking:
  • Semantics and live region announcements.
  • Tab order.
  • Contrast on error states.
• Telemetry Checks: We'll monitor:
  • Counters for duplicate prevention and verification failures.
  • Timing metrics.

This testing strategy is designed to make sure that our Create Account flow is reliable, user-friendly, and accessible to everyone. We want to catch any problems before they annoy our users!

⏱️ Timeframe: Getting It Done

We estimate that this task will take about 1 day to complete. Let's make it happen!

⚡ Urgency: How Important Is This?

• Low

🎚️ Difficulty: How Tough Is This?

• Moderate

👨‍💻 Recommended Assigned Developer: Who's on It?

We recommend @alondra-arce for this task. Let's go make some magic, Alondra!