Code Explanation Prompt Templates

## High-Level Summary
This function fetches user data from 3 different APIs concurrently (at the same time) rather than one after another, making it roughly 3x faster.

## Step-by-Step Breakdown

```python
async def fetch_user_data(user_id: str) -> UserData:
```
**Line 1:** `async` declares this as a coroutine, a function that can pause and resume, allowing other code to run during waits.

```python
 async with aiohttp.ClientSession() as session:
```
**Line 2:** `async with` is like regular `with` but for async resources. The session is a connection pool, reusing connections is faster than creating new ones for each request.

```python
 tasks = [
 fetch_profile(session, user_id),
 fetch_orders(session, user_id),
 fetch_preferences(session, user_id),
 ]
```
**Lines 3-7:** Creates a list of coroutines (not executed yet, just prepared).

```python
 profile, orders, preferences = await asyncio.gather(*tasks)
```
**Line 8:** `gather()` runs all three requests concurrently. `await` pauses this function until ALL three complete. Without `await`, we'd get a coroutine object instead of results.

## Why This Approach?
- **Concurrent, not parallel:** Runs in one thread but switches between tasks during I/O waits
- **Session reuse:** One session for all requests shares TCP connections
- **Structured concurrency:** `async with` ensures cleanup even if errors occur

## Edge Cases to Watch
- If one API fails, `gather()` raises immediately, use `gather(return_exceptions=True)` to get partial results
- Session has default timeouts, add explicit timeout for long API calls

## What Problem It Solves
Finds whether a value exists in a sorted array, and if so, where.

## Core Idea (No Code)
Imagine finding a name in a phone book. You don't start at page 1, you open to the middle, see if your name comes before or after, then repeat with the correct half. Each step eliminates half the remaining pages.

## Step-by-Step Trace
Find `7` in `[1, 3, 5, 7, 9, 11, 13]`:

```
Step 1: Look at middle (index 3) → value is 7
 [1, 3, 5, 7, 9, 11, 13]
 ↑
 Found! Return index 3
```

Find `6` in `[1, 3, 5, 7, 9, 11, 13]`:

```
Step 1: Middle (index 3) → 7. Target 6 < 7, search left half
 [1, 3, 5, 7, 9, 11, 13]
 ←←←←
Step 2: Middle of [1,3,5] (index 1) → 3. Target 6 > 3, search right
 [1, 3, 5]
 →
Step 3: Only [5] left, 5 ≠ 6
 Not found, return -1
```

## Complexity
- **Time: O(log n)**, Each step halves the search space. For 1 million items: log₂(1,000,000) ≈ 20 steps max.
- **Space: O(1)**, Only stores a few index variables, regardless of array size.

## When to Use
✅ Use binary search when: Array is sorted, you search frequently, array is large
❌ Use linear search when: Array is unsorted, array is tiny (<20 items), you only search once

## Architecture Pattern: Layered Architecture

This follows a classic 3-tier pattern:

```
Controllers → Services → Repositories → Database
(HTTP layer) (Business) (Data access) (Storage)
```

## How Data Flows

1. **Request comes in:** `POST /orders` hits `OrderController`
2. **Controller:** Validates input, calls `OrderService.createOrder()`
3. **Service:** Contains business logic (calculate totals, apply discounts)
4. **Repository:** `OrderRepository.save()` handles database operations
5. **Response flows back** through the same layers

## Where to Add Gift Wrap

For a new 'gift wrap' option:

1. **Model:** Add `giftWrap: boolean` and `giftMessage: string` to `Order` model
2. **Migration:** Add columns to orders table
3. **Service:** Update `OrderService.createOrder()` to handle gift wrap pricing
4. **Controller:** Accept gift wrap fields in request validation
5. **Repository:** No changes needed (ORM handles new fields)

**Start here:** Look at an existing optional feature (like 'express shipping') to see the pattern.

## Key Conventions

- Controllers never access repositories directly, always go through services
- Validation happens in controllers via middleware
- Business rules live in services, not models
- Repositories return domain objects, not raw database rows

## What It Matches
Passwords that are at least 8 characters and contain: one uppercase letter, one lowercase letter, one digit, and one special character from @$!%*?&.

## Component Breakdown

| Component | Meaning |
|-----------|--------|
| `^` | Start of string |
| `(?=.*[A-Z])` | Lookahead: must contain an uppercase letter somewhere |
| `(?=.*[a-z])` | Lookahead: must contain a lowercase letter somewhere |
| `(?=.*\d)` | Lookahead: must contain a digit somewhere |
| `(?=.*[@$!%*?&])` | Lookahead: must contain one of these special chars |
| `[A-Za-z\d@$!%*?&]{8,}` | The actual match: 8+ chars from the allowed set |
| `$` | End of string |

**Lookaheads (`?=`)** check conditions without consuming characters, they all check from position 0.

## Examples

✅ **Matches:**
- `Password1!`, has upper, lower, digit, special, 10 chars
- `Aa1@aaaa`, minimum valid, 8 chars

❌ **Doesn't match:**
- `password1!`, no uppercase
- `PASSWORD1!`, no lowercase 
- `Password!!`, no digit
- `Password1`, no special character
- `Pass1!`, only 6 chars
- `Password1#`, # not in allowed special chars

## Gotchas
- **Limited special chars:** Only `@$!%*?&` allowed, users might expect `#^()` to work
- **No max length:** Could accept very long passwords (might want to add `{8,128}`)
- **No spaces allowed:** The character class doesn't include space