> ## Documentation Index
> Fetch the complete documentation index at: https://safia.maximusolution.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SAFIA Admin Dashboard: Usage Metrics and Navigation

> Monitor daily usage, track 30-day activity trends, and navigate to user management, access control, and knowledge base tools from one place.

The SAFIA admin dashboard is a lightweight web interface that runs locally alongside your bot. It gives you a real-time view into usage activity, lets you control which Telegram users can access SAFIA, and provides tools for uploading knowledge base documents — all from your browser without touching the command line.

<Warning>
  Always set `ADMIN_PASSWORD` in your `.env` before exposing the dashboard. If `ADMIN_PASSWORD` is left blank, the dashboard runs with **no authentication** — anyone with network access to port 5454 can view metrics, manage users, and modify your configuration.
</Warning>

## Starting the dashboard

The dashboard starts automatically alongside the bot when you run `safia start`. You do not need to launch it separately.

```bash theme={null}
safia start
```

To start only the dashboard manually (for example, during development):

```bash theme={null}
uv run python admin_dashboard.py
```

Once running, open your browser and navigate to:

```text theme={null}
http://127.0.0.1:5454
```

## Setting up authentication

The dashboard uses HTTP Basic Auth. Set your credentials in `.env` before starting:

```env theme={null}
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your-strong-password
FLASK_SECRET_KEY=random-string
```

Your browser will prompt for a username and password the first time you visit. `ADMIN_USERNAME` defaults to `admin` if not set — only `ADMIN_PASSWORD` is required to enable authentication.

<Tip>
  Generate a strong `FLASK_SECRET_KEY` with `python -c "import secrets; print(secrets.token_hex(32))"` and paste the result into your `.env`.
</Tip>

## Dashboard metrics

When you open the dashboard at `/`, you see four summary cards reflecting activity for the current day:

<CardGroup cols={2}>
  <Card title="Total Users" icon="users">
    The total number of registered Telegram accounts, plus how many were active in the last 24 hours and the average message count per user.
  </Card>

  <Card title="Messages Today" icon="message">
    The number of messages SAFIA has processed since midnight UTC.
  </Card>

  <Card title="Tokens Today" icon="bolt">
    The total LLM tokens consumed today across all user conversations.
  </Card>

  <Card title="New Today" icon="user-plus">
    New user registrations recorded on the most recent day.
  </Card>
</CardGroup>

Below the summary cards, two 30-day charts give you a historical view:

* **Active vs New Users** — a line chart comparing daily active users against new registrations over the past 30 days.
* **Daily Token Usage** — a bar chart showing token consumption per day over the past 30 days.

Both charts update automatically each time you reload the page.

## Navigation

The sidebar links to all four sections of the admin dashboard:

| Section   | Path         | Purpose                                      |
| --------- | ------------ | -------------------------------------------- |
| Overview  | `/`          | Usage metrics and 30-day activity charts     |
| Users     | `/users`     | View all registered users and their activity |
| Settings  | `/settings`  | Access control, allowlist, and `.env` editor |
| Knowledge | `/knowledge` | Upload and manage knowledge base documents   |

<Note>
  All dashboard sections share the same HTTP Basic Auth session. You authenticate once per browser session and stay logged in until you close the browser or clear credentials.
</Note>