# Route Spec

## Route ID
`users-profile-get`

## Endpoint
`GET /api/v1/users/by-username/{username}`

## Human Description
Returns the public profile page data for a user, including profile visuals, social counts, activity stats, admin hubs, and profile relationship state for the current viewer. This endpoint never returns the user's phone number.

## Authentication
- Required: `no` (optional bearer enriches viewer relationship fields)
- Auth type: `none|bearer token`

## Request
### Headers
- `Authorization: Bearer <token>` (optional)

### Path Parameters
- `username` (`string`, required): case-insensitive unique username.

## Responses
### Success: `200 OK`
```json
{
  "success": true,
  "message": "Profile loaded",
  "data": {
    "user": {
      "id": "usr_123",
      "fullName": "Sara Ahmed",
      "username": "sara",
      "profilePhotoUrl": "https://cdn.example.com/u/123/profile.jpg",
      "coverPhotoUrl": null,
      "bio": null
    },
    "social": {
      "followersCount": 1260,
      "followingCount": 311,
      "viewerFollows": true,
      "viewerBlocked": false
    },
    "stats": {
      "postsCount": 202,
      "hubsCount": 3,
      "votesCastCount": 4811,
      "adminHubs": [
        {"id": "hub_1", "name": "Cairo Tech", "role": "super_admin"}
      ]
    }
  }
}
```

### Error: `404 Not Found`
```json
{
  "success": false,
  "error": {"code": "USER_NOT_FOUND", "message": "User does not exist.", "details": {}}
}
```

## Data & Caching Dependencies
- **Spanner Tables:** `users, user_social_counters, hub_memberships (Read)`
- **Redis Cache:** `None`
- **GCS Storage:** `None`
- **Edge Cache (CDN):** `Yes (short TTL for public)`

## Side Effects
- None (read-only endpoint).

## Privacy Notes
- Public profiles never expose phone numbers.
- Phone numbers are visible only in hub member contexts where the viewer is an approved member of that hub.