# User Authentication Requirements

## Universal Requirements
- U-001: The system **shall** require users to provide an email address and password for login.
- U-002: The system **shall** validate email addresses using RFC 5322 format.

## Event-Driven Requirements
- E-001: **When** the user clicks "Forgot Password", the system **shall** send a password reset link to the registered email.
- E-002: **Upon** successful authentication, the system **shall** generate a session token valid for 24 hours.

## State-Driven Requirements
- S-001: **If** the user has enabled two-factor authentication, the system **shall** prompt for the verification code.
- S-002: **When** the account is locked due to too many failed attempts, the system **shall** unlock it after 30 minutes.

## Unwanted Behavior
- N-001: The system **shall not** reveal whether an email address is registered during password reset.
- N-002: The system **shall not** allow the same account to be used from more than 3 IP addresses simultaneously.

## Optional Features
- O-001: The system **may** support social login providers (Google, Facebook, GitHub).

# Design: [Feature Name]

## Overview
High-level description of what this feature does and why it's needed.

## Architecture
### System Diagram

### Component Structure

## Data Models

### entities/Feature.ts
```typescript
interface FeatureEntity {
  id: string;
  name: string;
  status: 'active' | 'inactive';
  createdAt: Date;
  // ... other fields
}

interface CreateFeatureRequest {
  name: string;
  /* ... other fields */
}

interface CreateFeatureResponse {
  id: string;
  status: 'created';
}

User → Frontend: Click "Create Feature"
Frontend → API: POST /api/features
API → Validator: Validate data
Validator → API: Valid / Invalid
API → Database: Insert feature
Database → API: Created
API → Frontend: Return feature ID
Frontend → User: Show success message

### Implementation Task Tracking

```markdown
# Tasks: [Feature Name] Implementation

## Phase 1: Foundation
- [ ] Setup project structure and dependencies
- [ ] Create base data models
- [ ] Configure database schema
- [ ] Setup API endpoints scaffolding

## Phase 2: Core Functionality
- [ ] Implement feature creation endpoint
- [ ] Implement feature retrieval endpoint
- [ ] Implement feature update endpoint
- [ ] Implement feature deletion endpoint

## Phase 3: Frontend Integration
- [ ] Build main component
- [ ] Integrate with API
- [ ] Add loading and error states
- [ ] Implement user feedback messages

## Phase 4: Testing
- [ ] Unit tests for service layer
- [ ] Integration tests for API
- [ ] Component tests for UI
- [ ] End-to-end tests with Playwright

## Phase 5: Deployment
- [ ] Create migration scripts
- [ ] Setup CI/CD pipeline
- [ ] Deploy to staging environment
- [ ] Conduct QA review
- [ ] Deploy to production

## Phase 6: Documentation
- [ ] Update API documentation
- [ ] Write user documentation
- [ ] Update changelog

## Pre-Submission Checklist

### Repository Understanding
- [ ] Read README.md for project overview
- [ ] Read CONTRIBUTING.md for contribution rules
- [ ] Reviewed issue and PR templates
- [ ] Checked for existing related issues or PRs

### Environment Setup
- [ ] forked repository (if required)
- [ ] cloned repository locally
- [ ] setup development environment
- [ ] installed all dependencies

### Development Standards
- [ ] Understand coding style conventions
- [ ] Familiar with branching strategy
- [ ] Aware of commit message conventions
- [ ] Know testing requirements

## Issue: [Brief Title]

### Type: [Feature Request / Bug Report / Question / Documentation]

### Priority: [Low / Medium / High / Critical]

### Description
[Detailed description of the issue or feature request]

### Reproduction Steps (for bugs)
1. [First step]
2. [Second step]
3. [Third step]

### Expected Behavior
[What should happen]

### Actual Behavior
[What actually happened]

### Environment
- OS: [e.g., Windows 10, macOS 12.5]
- Browser: [e.g., Chrome 120, Firefox 115]
- Version: [If applicable]

### Additional Context
[Any other information that might be helpful]
- Screenshots
- Error messages
- Logs

## Branch Naming Convention

### Feature Branches
`feature/[JIRA-TICKET]/[short-description]`
Examples:
- feature/PROJ-123/user-authentication
- feature/PROJ-456/dark-mode-support

### Bugfix Branches
`bugfix/[JIRA-TICKET]/[issue-description]`
Examples:
- bugfix/PROJ-789/login-redirect-loop
- bugfix/PROJ-321/memory-leak-report

### Hotfix Branches (production issues)
`hotfix/[JIRA-TICKET]/[critical-description]`
Examples:
- hotfix/PROJ-999/security-vulnerability
- hotfix/PROJ-888/database-down

### Release Branches
`release/v[major].[minor]`
Examples:
- release/v1.2.0
- release/v2.0.0

### Branch Protection Rules
- Protect `main` and `develop` branches
- Require pull request reviews (at least 1 approval)
- Require status checks to pass (CI builds, tests)
- Require branches to be up-to-date before merging

## Conventional Commit Format

### Commit Types

| Type       | Purpose                        | Example                          |
|------------|--------------------------------|----------------------------------|
| `feat`     | New feature                     | `feat(auth): add OAuth2 support`   |
| `fix`      | Bug fix                         | `fix(api): resolve null reference`  |
| `docs`     | Documentation only              | `docs(readme): update setup guide`  |
| `style`    | Formatting/style (no logic)      | `style(ui): fix indentation`       |
| `refactor` | Code refactor (no feature/fix)   | `refactor(svc): extract helpers`  |
| `perf`     | Performance improvement          | `perf(db): add index on email`    |
| `test`     | Add/update tests                | `test(auth): add unit tests`      |
| `build`    | Build system/dependencies        | `build(ci): upgrade Node to v20`  |
| `ci`       | CI/config changes              | `ci(github): add workflow for PRs`|
| `chore`    | Maintenance/misc               | `chore(deps): update packages`    |
| `revert`   | Revert commit                 | `revert: feat(login)`             |

### Breaking Changes

### Good Commit Examples

### Bad Commit Examples (Don't use)

### Commit Workflow
```bash
# Stage changes
git add .

# Interactive staging (optional)
git add -i

# Commit with good message
git commit -m "feat(auth): implement OAuth2 login"

# Or use multi-line for body and footer
git commit -m "fix(db): optimize query performance

Added composite index on user_email and created_at
Reduced query time from 500ms to 50ms

Closes issue #123"

## Pull Request Checklist

### Before Submitting
- [ ] Branch is up-to-date with target branch
- [ ] Code compiles without errors
- [ ] All tests pass locally
- [ ] Linters pass without errors
- [ ] Documentation updated (README, API docs, code comments)
- [ ] Self-review completed

### PR Description
- [ ] Clear title following conventional commits
- [ ] Description explains "why" not just "what"
- [ ] Screenshots for UI changes included
- [ ] Breaking changes documented
- [ ] Related issues referenced (e.g., "Closes #123")
- [ ] Testing instructions provided

### Code Quality
- [ ] Follows project coding standards
- [ ] No commented-out code
- [ ] No console.log statements
- [ ] meaningful variable and function names
- [ ] No sensitive data exposed

### Testing
- [ ] New features tested
- [ ] Bug fixes verified
- [ ] Edge cases covered
- [ ] Manual testing completed as described

## Description
[Provide a brief description of the changes in this PR]

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation
- [ ] Refactoring
- [ ] Performance improvement

## Issue
[Closes #xxx] or [Related to #xxx]

## Changes Made
### Main Changes
- [Describe the main changes implemented]

### Technical Details
[Any technical details reviewers should know]

### Breaking Changes
[Any breaking changes and migration steps]

## Testing
### Manual Testing Steps
1. [Step 1]
2. [Step 2]

### Automated Testing
- [ ] Unit tests added and passing
- [ ] Integration tests added and passing
- [ ] E2E tests added and passing

## Screenshots
[Include before/after screenshots for UI changes]

## Checklist
- [ ] I have read the contributing guidelines
- [ ] My code follows the project style guidelines
- [ ] I have performed a self-review
- [ ] I have commented my code appropriately
- [ ] Changes have no linting errors
- [ ] All tests are passing
- [ ] Changes do not break existing functionality

## Code Review Principles

### Be Constructive
- Focus on improving code, not criticizing it
- Provide specific examples and suggestions
- Ask questions rather than making demands
- Acknowledge good code and smart solutions

### Review Focus Areas

#### Correctness
- [ ] Logic is correct and handles edge cases
- [ ] Error handling is adequate
- [ ] No obvious bugs or race conditions
- [ ] API contracts are maintained

#### Code Quality
- [ ] Code is readable and maintainable
- [ ] Naming follows conventions
- [ ] Complexity is reasonable
- [ ] No code duplication

#### Architecture
- [ ] Follows established patterns
- [ ] Good separation of concerns
- [ ] Proper abstractions used
- [ ] No tight coupling

#### Security
- [ ] No security vulnerabilities
- [ ] Input validation present
- [ ] Authentication/authorization correct
- [ ] No sensitive data exposure

### Review Priority Comments
🔴 **Blocker**: Must be fixed before merge
🟡 **Concern**: Discuss before merge
🟢 **Suggestion**: Nice to have, not blocking

### [TYPE] - [ACTION] - [TIMESTAMP]

**Objective**: [Goal being accomplished]

**Context**: [Current state, requirements, reference to prior steps]

**Decision**: [Approach chosen and rationale]

**Execution**: [Steps taken with parameters and commands]

**Output**: [Complete results, logs, metrics]

**Validation**: [Success verification and results]

**Next**: [Continuation plan to next action]

### Decision - [TIMESTAMP]

**Decision**: [What was decided]

**Context**: [Situation and driving data]

**Options**:
- Option 1: [Description] - [Pros/Cons]
- Option 2: [Description] - [Pros/Cons]
- Option 3: [Description] - [Pros/Cons]

**Rationale**: [Why selected option is superior]

**Impact**: [Anticipated consequences]

**Review**: [Reassessment conditions]

## Definition of Done (DoD)

### Development
- [ ] Code written and committed
- [ ] Code follows project style guide
- [ ] Code compiles without errors
- [ ] No console errors or warnings
- [ ] Self-review completed

### Testing
- [ ] Unit tests written and passing
- [ ] Integration tests written and passing
- [ ] Manual testing completed
- [ ] Edge cases identified and handled
- [ ] Test coverage meets project threshold (>80%)

### Documentation
- [ ] README updated if API changed
- [ ] API documentation updated
- [ ] Code comments added/updated
- [ ] User documentation updated if needed

### Code Review
- [ ] Pull request created
- [ ] At least one approval received
- [ ] All review comments addressed
- [ ] CI/CD pipeline passes
- [ ] Merged to appropriate branch

### Deployment
- [ ] Deployment tested in staging
- [ ] Smoke tests passed
- [ ] Performance validated
- [ ] Monitoring/alerting configured
- [ ] Rollback procedure documented

## Code Quality Checklist

### Functionality
- [ ] All acceptance criteria met
- [ ] Requirements from design document fulfilled
- [ ] Edge cases handled
- [ ] Error states handled gracefully

### Usability
- [ ] User-friendly error messages
- [ ] Clear feedback for actions
- [ ] Accessible (keyboard, screen reader)
- [ ] Responsive design verified

### Performance
- [ ] Meet performance requirements
- [ ] No memory leaks
- [ ] Efficient algorithms used
- [ ] Appropriate caching

### Security
- [ ] Input validation
- [ ] Output encoding (prevent XSS)
- [ ] Authentication/authorization implemented
- [ ] No sensitive data in logs
- [ ] Dependencies audited and up-to-date

### Maintainability
- [ ] Code is readable
- [ ] Good variable/function names
- [ ] Appropriate abstractions
- [ ] No code duplication
- [ ] Adequate comments

### Testing
- [ ] Unit tests for critical paths
- [ ] Integration tests for API
- [ ] E2E tests for user flows
- [ ] Tests are reliable and not flaky

## Development Phases

### Phase 1: Requirements & Planning
- Gather requirements from stakeholders
- Document in EARS notation
- Create technical design
- Identify risks and dependencies
- Estimate effort and timeline

### Phase 2: Development
- Set up feature branches
- Implement core functionality
- Write tests alongside code
- Code review and iteration

### Phase 3: Testing & QA
- Run automated tests
- Perform manual testing
- Conduct QA review
- Fix identified issues
- Performance testing

### Phase 4: Deployment
- Deploy to staging
- Execute smoke tests
- Get stakeholder approval
- Deploy to production
- Monitor for issues

### Phase 5: Post-Release
- Monitor metrics and logs
- Collect user feedback
- Address critical bugs
- Document lessons learned
- Update process improvements