# Customer Admin

Customer admin is the tenant-facing management surface at `/admin`. It is part
of the current webmail edition work and should stay white-labeled and
customer-facing.

## Scope

Customer admin is for postmaster users inside an organization.

Current supported workflows:

- Postmaster sign in with optional 2FA challenge.
- Session restore after browser refresh.
- Account search, filtering, pagination, and mailbox management.
- Mailbox create, password reset, delete, postmaster role toggle, and 2FA
  disable support.
- Distribution list create, delete, member add, member list, and member remove.
- Tenant branding update for logo, brand name, and tagline.
- Runtime help text next to search.
- Mobile and tablet sidebar drawer.

SaaS-only platform operator, billing, and superadmin flows should not be added
to this UI unless the Zimphony Webmail SaaS deployment track explicitly starts.

## Access

- Public route: `/admin`
- Login route: `/admin/login`
- Frontend service on this machine: `zimphony-admin-frontend.service`
- Backend service on this machine: `zimphony-admin-backend.service`
- Public admin API prefix through nginx: `/api/admin`

The admin user must be a mailbox that the backend recognizes as a postmaster.
If that mailbox has 2FA enabled, the login flow requires the verification code.

## Branding

The brand editor in `/admin` updates tenant-scoped branding.

Editable fields:

- Logo
- Brand name
- Tagline

Uploaded logo files are stored by the backend under:

```text
backend/data/branding/
```

The public logo endpoint is:

```text
/api/branding/logo
```

When a domain is known, frontend components request:

```text
/api/branding/logo?domain=<domain>&v=<version>
```

The `v` parameter is derived from file or manifest mtime and is used to avoid
stale browser cache after an upload.

Branding is used by:

- `/admin/login`
- `/admin` sidebar
- brand editor preview
- webmail login
- webmail workspace sidebar
- favicon, unless a separate favicon URL is configured

Branding may not change in places that are using only default site config or an
explicit environment override.

## Help Text

The help text beside search is runtime configuration from the backend.

Preferred environment variable:

```text
NEXT_PUBLIC_ADMIN_HELP_TEXT
```

The backend also accepts:

```text
ADMIN_HELP_TEXT
```

On this machine the backend reads `.env` and `frontend/.env.local` for this
value, then exposes it through:

```text
GET /api/admin/config
```

After changing the value, restart the admin backend and frontend if the running
process does not pick up the new environment.

## Distribution Lists

Distribution lists are managed through the mail server admin API.

Supported actions:

- Create distribution list.
- Delete distribution list.
- Add member.
- Show members.
- Remove member.

Create behavior:

- The UI asks only for local part and display name.
- The domain comes from the selected tenant domain.
- Duplicate list creation returns `Email address already exists`.

Delete behavior:

- The table `Delete` button opens a confirmation modal.
- The API delete uses the distribution list id resolved from the mail server.
- The successful response is `{"ok": true}`.
- Provider or proxy gateway errors are mapped to a short UI-safe message instead
  of raw HTML.

Member count behavior:

- Member count comes from the member list returned by the mail server snapshot.
- New lists with no members show zero members.

## Mobile and Tablet

On screens below the desktop breakpoint, the `/admin` sidebar is hidden as an
off-canvas drawer, matching the webmail interaction model.

Behavior:

- The header menu button opens the drawer.
- The overlay closes the drawer.
- Selecting `Accounts`, `Distribution lists`, or `Logout` closes the drawer.
- Desktop `xl` and wider keeps the persistent left sidebar.

When changing this UI, verify both:

- Mobile width with drawer open and closed.
- Tablet width with drawer open and closed.

## Validation Checklist

Use this checklist before handing off a customer admin build.

- Login as postmaster without 2FA.
- Login as postmaster with 2FA.
- Refresh `/admin` after login and confirm the session remains active.
- Switch between `Accounts` and `Distribution lists`.
- Search accounts and distribution lists.
- Create mailbox.
- Reset mailbox password.
- Disable mailbox 2FA from the `Enabled` pill.
- Delete mailbox only after confirm modal.
- Create distribution list.
- Create duplicate distribution list and confirm the message is
  `Email address already exists`.
- Add distribution list member.
- Show distribution list members.
- Remove distribution list member.
- Delete distribution list only after confirm modal.
- Change brand name, tagline, and logo.
- Confirm branding updates on `/admin/login`, `/admin`, webmail login, and
  webmail workspace.
- Confirm help text matches `NEXT_PUBLIC_ADMIN_HELP_TEXT`.
- Verify mobile and tablet sidebar drawer behavior.

## Production Validation

After frontend changes:

```bash
sudo systemctl restart zimphony-admin-frontend.service
```

After backend changes:

```bash
sudo systemctl restart zimphony-admin-backend.service
```

On this machine, validate through nginx:

```bash
curl -k -I -H 'Host: mail.mailmali.com' https://127.0.0.1/admin
curl -k -H 'Host: mail.mailmali.com' https://127.0.0.1/api/admin/config
```

Expected result:

- `/admin` returns `HTTP/2 200`.
- `/api/admin/config` returns branding, product capabilities, and
  `admin_help_text`.

## Notes

- Keep visible copy vendor-neutral. Do not expose provider names in the main UI.
- Keep customer admin focused on mail operations.
- Do not add billing, platform operator, or SaaS-only controls here.
- If a UI change affects mobile or tablet, verify the compact layout separately.
