nick-doc/06 - Usage/Admin Guide.md

---
title: Admin Guide
tags: [usage, role/admin]
audience: Admin
created: 2026-05-23
---

# Admin Guide

Operational usage for **Admin** users — moderation, dispute mediation, payment ops, blog management, system oversight.

> [!info]
> Looking for a different role? See [[User Guide]] (Buyer), [[Seller Guide]] (Owner), [[Support Guide]].

---

## 1. Default admin credentials

In a freshly-seeded environment (dev or first prod boot with `AUTO_SEED_ON_START=true`):

| Email | Password | Role |
|---|---|---|
| `admin@marketplace.com` | `Moji6364` | admin |

> [!warning]
> Change this password immediately in production. The default values are committed to the seed scripts.

Sign in at `/auth/jwt/sign-in` like any other user. The dashboard sidebar will surface admin-only sections.

---

## 2. Admin dashboard overview

**Dashboard → Overview** for admin shows aggregated platform KPIs:

| Tile | Metric | Source |
|---|---|---|
| Active users (30d) | Distinct logins | Users collection |
| New registrations (today / 7d / 30d) | Signups | TempVerification + User |
| Open requests | Status = open | PurchaseRequest |
| In-flight payments | Status = pending or processing | Payment |
| Open disputes | Status = open | Dispute |
| Revenue (fees) | Platform commission ledger | Payment + ShopSettings |
| Pending approvals | New seller verifications, blog drafts | various |

> [!tip]
> Click any KPI tile to drill into the filtered list.

---

## 3. User management

### 3.1 List users

**Dashboard → User → List**:

- DataGrid with: email, name, role, status, joined date, last activity, points balance, kyc state.
- Filters: role, status (active/banned/pending verification), country, signup-date range.
- Search: email, name, phone.
- Export to CSV (admin-only action).

### 3.2 Edit a user

Click a user row → **Edit**:

- Change role (e.g., promote to seller, demote to buyer, grant admin).
- Manually verify email.
- Reset password (sends a reset code to their email).
- Adjust points balance (audited).
- Ban / unban.
- View linked addresses, payment methods, devices.

> [!warning]
> Role escalation is logged in the audit trail. Granting admin rights should be limited and reversible — use `support` for less-privileged staff (see [[Support Guide]]).

### 3.3 Create a user (admin-only)

**User → New** lets you provision an account without email verification (useful for migrating staff or VIP onboarding).

### 3.4 Ban a user

1. Open user row → **Ban**.
2. Provide a reason (logged + emailed to user).
3. Optional: auto-resolve all their open requests/offers (recommended for fraud cases).

A banned user:
- Cannot sign in.
- Their open offers are withdrawn.
- Their open requests are cancelled.
- Their funds in escrow are NOT auto-released — handle through disputes.

---

## 4. Listing & content moderation

### 4.1 Purchase Request review

Public requests are typically auto-published, but admin can review:

**Marketplace → Requests → Filter status: Open**. Look for:

- Suspicious wording (drugs, weapons, prohibited items — block list TBD)
- Unrealistic prices (likely scams)
- Foreign language abuse

Action: **Hide** (sets visibility off without deleting), or **Force-cancel** with reason.

### 4.2 Seller Template review

**Marketplace → Templates** — sellers' shareable templates. Same scrutiny as requests. Reject with reason; the seller is notified.

### 4.3 Blog post review

Admin owns blog content:

**Dashboard → Post → List**:

- Drafts, published, archived
- New: `Post → New` → TipTap editor → fill title, slug, category, cover image, body, SEO meta → **Publish**.
- Edit existing: same flow.
- Comments moderation (if comments enabled): approve / reject / spam.

---

## 5. Dispute mediation

The most critical admin function.

### 5.1 Dispute queue

**Dashboard → Disputes** lists every dispute with:

- Reason
- Status (open / awaiting evidence / under review / resolved)
- Buyer & seller links
- Amount in escrow
- Days open
- Last action

Sort by **Days open desc** to handle aging cases first.

### 5.2 Picking up a dispute

Click a dispute → **Assign to me** (or it's auto-assigned on first open).

You'll see:
- Buyer's claim + evidence
- Seller's response + evidence
- Full chat history between buyer/seller
- Order timeline (payment, shipment, confirmation actions)
- Payment & escrow status

### 5.3 Communicating

A 3-way chat exists in the dispute view:
- Send a message visible to both parties ("Please clarify…").
- Send a message visible to one party only (rare).
- Request additional evidence.

### 5.4 Resolving

When you have enough information, click **Resolve**:

| Resolution | What happens |
|---|---|
| **Refund buyer (100%)** | Escrow returned to buyer; seller marked at-fault |
| **Refund buyer (partial)** | Specify split; e.g., 70% buyer, 30% seller |
| **Release to seller** | Buyer's claim denied; full payout to seller |
| **Mutual cancel** | Buyer & seller agreed to refund |

You MUST write a resolution narrative explaining your reasoning. Both parties see this.

> [!warning]
> Resolutions are **irreversible** in the system. Triple-check the split before confirming.

See [[Dispute Flow]] and the [[Dispute]] model.

### 5.5 Pattern detection

If you see repeat disputes against the same seller (or repeat frivolous disputes from the same buyer), check:
- **Dashboard → User → [profile] → History** for past disputes.
- Consider banning persistent bad actors after review.

---

## 6. Payment operations

### 6.1 Payment monitoring

**Dashboard → Payment → List** shows all payments with filters by status, provider, network, time range.

Watch for:
- **Stuck payments** (pending > 1h) — Request Network webhook/reconciliation may not have completed; check webhook logs and derived-destination balances.
- **Failed webhooks** — Request Network signature verification or payload validation failed; see [[Payment API]] and [[Request Network Integration Constraints]].
- **Missing tx hashes** on completed payments — use the payment console or reconciliation job to fetch and verify the on-chain transaction before any release.

### 6.2 Manual payout

For sellers who can't access self-service or for one-off ops:

1. **Payment → Payout → New**.
2. Fields: recipient address, amount, token (USDT…), network (BSC…), reference, description.
3. Submit → ts-node script also exists at `backend/manual-payout-test.ts` for local testing.

Behind the scenes this should create a release/refund instruction and ledger entry, then route signing through the configured custody signer. See [[Payout Flow]] and [[PRD - Decentralized Custody and Smart-Contract Escrow Roadmap]].

### 6.3 Fix missing transaction hashes

Some completed payments may lack the on-chain tx hash (webhook race, callback delay, or partial reconciliation). Prefer the admin payment console or Request Network reconciliation tooling. For older SHKeeper records only, use the historical repair script:

```bash
cd /Users/mojtabaheidari/code/backend
node fix-transaction-hashes.js
```

The legacy script polls SHKeeper for each affected historical invoice and patches `transactionHash` + `blockchain.transactionHash` in MongoDB. Do not use it for new Request Network payments.

See [[Scripts]] for the full inventory.

### 6.4 Refunds

Issued automatically when a dispute resolves to "refund buyer". For manual refunds (e.g., goodwill):

1. **Payment → [payment] → Refund**.
2. Specify amount (full or partial).
3. Confirm. The refund triggers a payout-style return to the buyer's address.

---

## 7. Loyalty / Points system

### 7.1 Levels

**Dashboard → Points → Levels** (admin view):

- View all `LevelConfig` tiers.
- Edit thresholds (points required).
- Edit benefits (discount %, perks).
- Add / archive levels.

See [[LevelConfig]] model.

### 7.2 Award bonus points

For promotions, contests, makegoods:

1. **Points → Award bonus**.
2. Pick a user (by email).
3. Amount + reason (logged in audit).
4. Submit → user is notified.

Recorded as a `PointTransaction` with `source: 'admin'`.

### 7.3 Audit point transactions

**Points → Transactions** with admin filter shows every earn / spend / expire / admin-adjust event for any user.

---

## 8. Category management

**Marketplace → Categories** (or a dedicated admin area):

- Add new category (Persian name + English name + icon + parent for sub-categories).
- Edit / archive.
- Reorder (drag-drop).
- Seed initial set via `npm run seed:categories`.

See [[Category]] model.

---

## 9. System health & ops

### 9.1 Healthcheck

```bash
curl https://amn.gg/health
# → { "status": "ok", "uptime": 12345, "db": "connected", "redis": "connected" }
```

(Confirm exact shape from `backend/src/app.ts`.)

Healthcheck is also wired into Docker (`HEALTHCHECK` in `backend/Dockerfile.prod`), so a failing healthcheck restarts the container automatically.

### 9.2 Container status

On the host:

```bash
docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Image}}'
# nickapp-backend   Up 2h (healthy)   git.manko.yoga/manawenuz/escrow-backend:latest
# nickapp-frontend  Up 2h (healthy)   …/frontend:latest
# nickapp-nginx     Up 2h             nginx:alpine
# nickapp-mongodb   Up 2h (healthy)   mongo:8.0
# nickapp-redis     Up 2h (healthy)   redis:8-alpine
```

### 9.3 Logs

```bash
docker logs -f --tail 200 nickapp-backend
docker logs -f --tail 200 nickapp-frontend
docker logs -f --tail 200 nickapp-nginx
```

Sentry collects unhandled errors with full context. See [[Monitoring]].

### 9.4 Restart

```bash
docker compose -f /path/to/docker-compose.production.yml restart nickapp-backend
```

Or roll a new image: push to registry → Watchtower auto-restarts within 5 min.

### 9.5 Database access

```bash
docker exec -it nickapp-mongodb mongosh \
  --username "$MONGO_USERNAME" --password "$MONGO_PASSWORD"
use nickapp
db.users.find({ role: 'admin' })
```

> [!warning]
> Direct DB writes bypass all validation, hooks, and audit logging. Use the admin UI whenever possible.

See [[Database Operations]] for the runbook.

---

## 10. Reports & analytics

### 10.1 Built-in admin reports

(If implemented — verify in `backend/src/services/admin/`.)

- **Revenue by month / category / seller**
- **Top sellers by GMV / completion rate**
- **Top buyers by spend**
- **Dispute rate by category / seller**
- **Funnel: signup → first request → first payment**

Export to CSV for offline analysis.

### 10.2 Ad-hoc queries

For complex investigations, use `mongosh` directly (see §9.5).

---

## 11. Communications

### 11.1 System announcement

(If admin has a broadcast UI — check `Notification` model.)

1. Compose message (title, body, link).
2. Audience: all users / specific role / specific list.
3. Send → appears in users' notification drawer and (optionally) emails.

Backed by `notification:received` socket event broadcast to all relevant rooms. See [[Notification Flow]].

### 11.2 Maintenance window

For planned downtime:

1. Post an in-app announcement 24h ahead.
2. At T-15 min, broadcast `system:maintenance` socket event.
3. UI shows a yellow banner: "Maintenance in 15 min — please save your work."
4. Take the system offline (compose stop, deploy, compose start).

See [[Incident Response]] for unplanned ops.

---

## 12. Support escalations

Support agents (see [[Support Guide]]) handle Tier-1 issues. Items that escalate to admin:

- Refund > $X
- Role changes
- Account un-ban
- Suspected fraud / chargeback dispute
- Manual payout exceptions
- Data correction (anything bypassing the UI)

Admins should reply to escalations within 1 business day SLA.

---

## 13. Common admin tasks (quick reference)

| Task | Where |
|---|---|
| Reset a user's password | User → [profile] → Reset password |
| Manually verify a user | User → [profile] → Verify email |
| Promote user to seller | User → [profile] → Edit → role |
| Award points | Points → Award |
| Approve a refund | Payment → [payment] → Refund |
| Resolve a dispute | Disputes → [case] → Resolve |
| Hide a request | Marketplace → [request] → Hide |
| Publish a blog post | Post → [post] → Publish |
| Add a category | Marketplace → Categories → New |
| Check system health | `curl /health` |

---

## 14. Audit & accountability

Every admin action SHOULD be logged. Today the system logs role changes, refunds, point-adjustments, and dispute resolutions in the `Notification` and `PointTransaction` collections with `metadata.actor`. Stronger audit trail (append-only collection with diffs) is on the roadmap.

> [!warning]
> Do NOT use admin powers to read private chats unless required for dispute investigation. Document the case ID and reason for each access.

---

## 15. Operations runbooks (pointers)

When something breaks, see:

- [[Incident Response]] — what to do when the site is down
- [[Backup & Recovery]] — restore from backup
- [[Monitoring]] — what to watch
- [[Database Operations]] — direct DB ops

---

## 16. Related

- [[User Guide]] · [[Seller Guide]] · [[Support Guide]]
- Flows: [[Dispute Flow]] · [[Payout Flow]] · [[Notification Flow]]
- Models: [[User]] · [[Dispute]] · [[Payment]] · [[LevelConfig]] · [[PointTransaction]] · [[Category]] · [[BlogPost]]
- [[Admin API]] · [[Glossary]]