# HawkExDashboard
A drop-in Phoenix LiveView admin dashboard for [HawkEx](https://github.com/Null-logic-0/hawk_ex) —
the Elixir toolkit for SaaS billing infrastructure. HawkEx owns your plans,
subscriptions, entitlements, audit logs, and CSV exports; HawkExDashboard
gives you a UI to see all of it without writing a single admin screen
yourself.
Mount it at a route, protect it with your own auth pipeline, and you get a
read-only operations view into your billing data: active subscriptions,
plan entitlements, audit history, background export jobs, and a live feed
of business events — all wired up out of the box.
## Features
* **Overview** — recent account activity at a glance.
* **Billing** — plans and active subscriptions, with a detail drawer per subscription.
* **Audit Logs** — searchable, sortable, paginated audit trail.
* **CSV Exports** — export job status and one-click downloads.
* **Entitlements** — a full plan × feature matrix.
* **Usage** — per-account plan limits and feature access.
* **Events** — a live-updating feed of HawkEx business events (subscriptions, exports, audit) over PubSub, with pause/resume and type filtering.
* **Configuration** — a read-only snapshot of how HawkEx is currently configured, useful for verifying a deployment.
* **Command palette** — press `⌘K` / `Ctrl+K` anywhere in the dashboard to jump to a subscription, audit event, or export.
The dashboard ships its own JS and CSS (served through its own asset
route), so there's no esbuild/Tailwind wiring required in the host
application — just mount the router macro and go.
## Installation
Add `hawk_ex_dashboard` to your dependencies. It requires
[`hawk_ex`](https://github.com/Null-logic-0/hawk_ex) to already be installed
and configured in your application, since the dashboard reads its data
through HawkEx's context modules.
```elixir
def deps do
[
{:hawk_ex, "~> 0.1.0"},
{:hawk_ex_dashboard, "~> 0.1.0"}
]
end
```
Mount the dashboard in your router:
```elixir
defmodule MyAppWeb.Router do
use Phoenix.Router
import HawkExDashboard.Router
scope "/" do
# Protect this with your own authentication/authorization pipeline —
# see "Security" below.
pipe_through [:browser, :require_admin]
hawk_ex_dashboard "/hawk_ex"
end
end
```
This mounts the following routes under the given path:
```
/hawk_ex Overview
/hawk_ex/billing Billing
/hawk_ex/audit Audit Logs
/hawk_ex/csv CSV Exports
/hawk_ex/configuration Configuration
/hawk_ex/entitlements Entitlements
/hawk_ex/usage Usage
/hawk_ex/events Events
```
## Configuration
HawkExDashboard has no configuration of its own — it reads through
whatever you've already configured for `hawk_ex`:
```elixir
config :hawk_ex,
repo: MyApp.Repo,
account_schema: MyApp.Accounts.Organization,
pubsub: MyApp.PubSub # required for the live Events feed
```
See the [HawkEx README](https://github.com/Null-logic-0/hawk_ex#configuration)
for the full list of options (Oban, CSV storage adapters, etc).
## Security
The dashboard exposes internal billing and account data. It ships with no
authentication of its own — always mount it behind an authentication and
authorization pipeline in production, for example:
```elixir
scope "/" do
pipe_through [:browser, :require_admin]
hawk_ex_dashboard "/hawk_ex"
end
```
## Local development
This repository includes a small harness application under `dev/` for
running the dashboard standalone against a local Postgres database.
```sh
mix deps.get
mix dev.setup # creates and migrates the dev database
mix dev # starts the harness app at http://localhost:4000/hawk_ex
```
## Testing
```sh
mix test
```
## Documentation
Generate local documentation with:
```sh
mix docs
```
Published package documentation will be available on
[HexDocs](https://hexdocs.pm/hawk_ex_dashboard) after release.
## Contributing
Contributions are welcome. Please keep changes focused, include tests for
new or changed behavior, and run the checks before opening a pull request:
```sh
mix format
mix test
mix docs
```
For larger changes, open an issue or discussion first so the design can be
aligned before implementation.
## License
HawkExDashboard is released under the MIT License. See [LICENSE](LICENSE)
for details.