Software Requirements Specification: Flutter POC Auth

1. Purpose

This SRS documents the Flutter POC auth feature generated with the add-feat and add-srs workflows. The intended outcome is a small, auditable demo for sign-in, sign-up, forgot password, screenshot e2e, and generated report flows with traceability from user stories to tests.

2. Scope

The POC supports:

• Sign-in with demo email and password.
• Sign-up with email, password, and display name.
• Forgot password reset-link request with email validation.
• Loading, success, and error UI states.
• Local deterministic AuthService boundary.
• Unit, widget, integration, screenshot, and e2e report tests.
• Generated e2e-index.html and srs-index.html reports with traceability back to user stories, screen layouts, and screenshot artifacts.

The POC does not support production token storage, OAuth/OIDC, actual email delivery, biometric auth, or real identity-provider integration.

3. User Stories

4. Functional Requirements

5. Use Cases

UC-001 Sign in

1. User opens the auth POC.
2. User keeps sign-in mode selected.
3. User enters email and password.
4. User submits.
5. App shows returned user summary or error.

UC-002 Sign up

1. User opens the auth POC.
2. User switches to sign-up mode.
3. User enters email, password, and display name.
4. User submits.
5. App shows returned user summary or error.

UC-003 Forgot password

1. User opens the auth POC.
2. User taps Forgot password?.
3. User enters a valid email address.
4. User submits reset request.
5. App shows reset-link confirmation or validation error.

UC-004 Generate visual verification reports

1. Developer runs ./e2e.sh.
2. Runner executes format, analysis, Flutter tests, and screenshot capture tests.
3. Runner writes screenshot PNG files under screenshots/.
4. Runner generates e2e-index.html with summary counts, filters, and screenshot grid.
5. Developer runs ./resources/srs.sh.
6. Runner generates srs-index.html with user stories, requirements, screen layouts, traceability, and verification commands.

6. Flow Diagram

flowchart TD
  A[Open AuthPocApp] --> B[Render AuthPage]
  B --> C{Mode}
  C -->|Sign in| D[Email + password]
  C -->|Sign up| E[Email + password + display name]
  D --> F[Submit]
  E --> F
  F --> G[AuthService]
  G --> H{Valid input?}
  H -->|Yes| I[AuthResult]
  H -->|No| J[Error message]
  I --> K[Render success]
  J --> L[Render error]

Forgot Password Flow

flowchart TD
  A[Sign-in screen] --> B[Forgot password link]
  B --> C[Forgot password mode]
  C --> D[Email field]
  D --> E[Send reset link]
  E --> F{Valid email?}
  F -->|Yes| G[PasswordResetResult]
  F -->|No| H[Error message]
  G --> I[Render reset confirmation]

Report Generation Flow

flowchart TD
  A[Run e2e.sh] --> B[Dart format]
  B --> C[Flutter analyze]
  C --> D[Flutter tests]
  D --> E[Screenshot capture tests]
  E --> F[screenshots/*.png]
  F --> G[e2e-index.html]
  H[Run resources/srs.sh] --> I[resources/srs.md]
  I --> J[resources/screens/*.md]
  J --> K[srs-index.html]
  G --> L[Visual review]
  K --> L

7. Entities

8. Screens / UI Surfaces

Auth Sign-in and Sign-up Screen Layout

Source: resources/screens/ep01-auth-screen.md

Layout Mode: Single-column

┌──────────────────────────────────────────────┐
│  AppBar: "Flutter POC Auth"                  │
├──────────────────────────────────────────────┤
│                                              │
│  Auth Demo                                   │
│  Local deterministic sign-in/sign-up POC     │
│                                              │
│  ┌────────────────────────────────────────┐  │
│  │ [Sign in] [Sign up]                    │  │
│  └────────────────────────────────────────┘  │
│                                              │
│  ┌────────────────────────────────────────┐  │
│  │ [mail] Email                           │  │
│  │ [demo@shipflutter.dev             ]    │  │
│  └────────────────────────────────────────┘  │
│                                              │
│  ┌────────────────────────────────────────┐  │
│  │ [lock] Password                        │  │
│  │ [password123                      ]    │  │
│  └────────────────────────────────────────┘  │
│                                              │
│  [Forgot password?]                          │
│                                              │
│  ┌────────────────────────────────────────┐  │
│  │          [Sign in]                     │  │
│  └────────────────────────────────────────┘  │
│                                              │
│  Success/error result area                  │
│                                              │
└──────────────────────────────────────────────┘

Components

• App bar: Flutter POC Auth
• Mode selector: SegmentedButton<AuthMode> with Sign in and Sign up options
• Email field: TextField with email keyboard
• Password field: TextField with obscured text
• Display name field: TextField shown only in sign-up mode
• Forgot password link: TextButton shown only in sign-in mode
• Submit button: FilledButton with sign-in/sign-up label
• Result area: Text summary for success or error message

States

• Initial: Sign-in mode with demo email and password prefilled
• Sign-up: Display name field appears and submit label changes to Create account
• Loading: Submit button is disabled and label changes to Submitting...
• Success: Shows returned user id, email, and optional display name
• Error: Shows service validation error in red

Events

• AuthModeChanged -> switch between sign-in and sign-up modes
• SignInRequested -> call AuthService.signIn()
• SignUpRequested -> call AuthService.signUp()
• ForgotPasswordTapped -> switch to forgot password mode

Forgot Password Screen Layout

Source: resources/screens/ep02-forgot-password-screen.md

Layout Mode: Single-column

┌──────────────────────────────────────────────┐
│  AppBar: "Forgot Password"            [back] │
├──────────────────────────────────────────────┤
│                                              │
│  Reset your password                         │
│  Enter your email and we'll send you         │
│  instructions to reset your password.        │
│                                              │
│  ┌────────────────────────────────────────┐  │
│  │ [mail] Email                           │  │
│  │ [Enter your email...              ]    │  │
│  └────────────────────────────────────────┘  │
│                                              │
│  ┌────────────────────────────────────────┐  │
│  │         [Send Reset Link]              │  │
│  └────────────────────────────────────────┘  │
│                                              │
│  Remember your password? [Sign in]           │
│                                              │
└──────────────────────────────────────────────┘

Components

• Title: "Reset your password" (Text, headline style)
• Description: Instructions text (Text, body style, muted color)
• Email field: TextField with email validation
• Send button: FilledButton, disabled when loading or email invalid
• Sign in link: TextButton -> back to sign-in mode

States

• Initial: Email field prefilled from sign-in form, button enabled when valid
• Loading: Button shows "Sending...", disabled
• Success: Show success message "Reset link sent to {email}"
• Error: Show error message below button

Events

• ForgotPasswordRequested -> validate email, call AuthService.forgotPassword()
• BackToSignInTapped -> switch to sign-in mode

9. Non-Functional Requirements

• The POC must stay local and deterministic.
• The POC must not store passwords or tokens.
• The UI should remain readable on mobile and web-sized screens.
• Tests should run without external services.
• Screenshot names must remain stable for report filtering and traceability.
• HTML reports must be generated locally and link e2e output back to SRS output.

10. Traceability

11. Verification

flutter pub get
dart format --set-exit-if-changed .
flutter analyze
flutter test
./e2e.sh
./resources/srs.sh