--- 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) — SHKeeper webhook may have failed; check logs. - **Failed webhooks** — SHKeeper retried but signature didn't verify; see [[Payment API]]. - **Missing tx hashes** on completed payments — run the repair script (see §6.3). ### 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 calls SHKeeper's payout endpoint. See [[Payout Flow]]. ### 6.3 Fix missing transaction hashes Some completed payments may lack the on-chain tx hash (webhook race, partial confirmation). Run: ```bash cd /Users/mojtabaheidari/code/backend node fix-transaction-hashes.js ``` The script polls SHKeeper for each affected invoice and patches `transactionHash` + `blockchain.transactionHash` in MongoDB. 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]]