## 📋 MESSAGE FOR FRONTEND DEVELOPER

### What changed in the backend:

1. **User data now has a new field: `profile_photo_url`** — This is the user's Telegram profile photo URL. It can be `null` if the user has no Telegram profile photo.

2. **New API endpoints available:**
   - `GET /api/me/profile` → Returns `{ username, profile_photo_url, student_type, balance, telegram_user_id }`
   - `GET /api/user/<username>/profile` → Returns `{ username, profile_photo_url, student_type }` (for other users, used in notifications/sharing)
   - `GET /me` (existing, updated) → Now also returns `profile_photo_url` field

3. **Notifications now include `from_profile_photo_url`** — When a user shares a board, the notification object sent to the recipient now has a `from_profile_photo_url` field (can be `null`).

4. **Dashboard template now receives `profile_photo_url` variable** — Passed from backend as a template variable.

5. **After signup → verification → success, user goes directly to dashboard** (no longer redirected to login page).

---

### Pages that need frontend updates:

#### 1. `templates/dashboard.html`
- **Display user's profile photo** next to their username/greeting area
- Backend passes `profile_photo_url` (can be `null`)
- **Fallback rule:** If `profile_photo_url` is `null` or empty, show a circle with the **first letter of `username`** (uppercase) as the avatar, with a colored background
- Example: User "ahmed" with no photo → show a circle with letter "A"
- The variable is available as `{{ profile_photo_url }}` in Jinja2 and `{{ username }}` for the fallback letter

#### 2. `templates/chat.html`
- **Display user's profile photo as their chat icon** next to their messages
- Fetch profile from `GET /me` endpoint (already called on page load) — it now returns `profile_photo_url`
- **Fallback rule:** Same as dashboard — if `null`, use first letter of username in a colored circle
- The AI/teacher messages keep their existing icon (no change)

#### 3. **Notifications display** (wherever notifications are rendered — likely in `dashboard.html` or a notifications panel)
- Each notification of type `board_share` now has `from_profile_photo_url` field
- Display the **sender's profile photo** next to the notification text
- **Fallback rule:** If `from_profile_photo_url` is `null`, use first letter of `from_username` in a colored circle
- The `from_username` field is already present in notifications

#### 4. **Board share UI** (in `templates/board.html` if there's a share dialog)
- When searching users via `GET /api/users/search`, the results include `username` and `student_type`
- To show profile photos in search results, make an additional call to `GET /api/user/<username>/profile` for each result, OR just use the first-letter fallback (simpler)

---

### Avatar fallback logic (use everywhere):

```javascript
// Helper function for all pages
function getAvatarHTML(profilePhotoUrl, username, size = 40) {
    if (profilePhotoUrl) {
        return `<img src="${profilePhotoUrl}" alt="${username}"
                style="width:${size}px; height:${size}px; border-radius:50%; object-fit:cover;"
                onerror="this.outerHTML=getLetterAvatarHTML('${username}', ${size})">`;
    }
    return getLetterAvatarHTML(username, size);
}

function getLetterAvatarHTML(username, size = 40) {
    const letter = (username && username.length > 0) ? username.charAt(0).toUpperCase() : '?';
    // Generate consistent color from username
    const colors = ['#7C3AED', '#0EA5E9', '#10B981', '#F59E0B', '#EF4444', '#EC4899', '#8B5CF6', '#06B6D4'];
    let hash = 0;
    for (let i = 0; i < username.length; i++) {
        hash = username.charCodeAt(i) + ((hash << 5) - hash);
    }
    const color = colors[Math.abs(hash) % colors.length];
    const fontSize = Math.round(size * 0.45);

    return `<div style="width:${size}px; height:${size}px; border-radius:50%;
            background:${color}; display:flex; align-items:center; justify-content:center;
            color:white; font-weight:700; font-size:${fontSize}px; font-family:'Cairo',sans-serif;
            flex-shrink:0;">${letter}</div>`;
}
```

### Jinja2 macro for templates (use in dashboard.html and anywhere server-rendered):

```html
{# Place this at the top of any template that needs avatars #}
{% macro avatar(photo_url, username, size=40) %}
{% if photo_url %}
<img src="{{ photo_url }}" alt="{{ username }}"
     style="width:{{ size }}px; height:{{ size }}px; border-radius:50%; object-fit:cover;"
     onerror="this.style.display='none'; this.nextElementSibling.style.display='flex';">
<div style="width:{{ size }}px; height:{{ size }}px; border-radius:50%;
     background:#7C3AED; display:none; align-items:center; justify-content:center;
     color:white; font-weight:700; font-size:{{ (size * 0.45)|int }}px; font-family:'Cairo',sans-serif;">
    {{ username[0]|upper if username else '?' }}
</div>
{% else %}
<div style="width:{{ size }}px; height:{{ size }}px; border-radius:50%;
     background:#7C3AED; display:flex; align-items:center; justify-content:center;
     color:white; font-weight:700; font-size:{{ (size * 0.45)|int }}px; font-family:'Cairo',sans-serif;">
    {{ username[0]|upper if username else '?' }}
</div>
{% endif %}
{% endmacro %}
```

### Summary of where to use avatars:

| Page | Where | Data source | Photo field | Username field |
|------|-------|-------------|-------------|----------------|
| `dashboard.html` | User greeting area (top) | Template variable | `{{ profile_photo_url }}` | `{{ username }}` |
| `chat.html` | Next to user's own messages | JS from `GET /me` response | `response.profile_photo_url` | `response.username` |
| `dashboard.html` or notification panel | Each notification item | Notification object | `notif.from_profile_photo_url` | `notif.from_username` |
| `board.html` | Share dialog user search results | Use first-letter fallback | N/A (not fetched) | `result.username` |

### Important notes:
- `profile_photo_url` CAN be `null` — always handle the fallback
- The `onerror` handler on `<img>` is important because even if a URL exists, it might be expired or broken (Telegram URLs can expire)
- The `GET /api/user/<username>/profile` endpoint exists if you ever need to fetch another user's photo on demand, but for notifications the `from_profile_photo_url` is already included in the notification data
- No changes needed to `verification.html` — it works correctly now
- No changes needed to `signup.html` or `login.html`