nick-doc/00 - Overview/Roles & Personas.md

---
title: Roles & Personas
tags: [overview, roles, personas, permissions, rbac]
created: 2026-05-23
---

# Roles & Personas

> [!info] Where roles live in code
> The hard role enum is defined in `backend/src/models/User.ts:94` as `"admin" | "buyer" | "seller"`. Support is implemented as an admin variant (a dedicated `support@amn.gg` user is created at bootstrap — see `backend/TODO.md`) rather than as its own enum value. Permission checks live in route middleware and in service guards.

Amn has four user personas. Three are first-class roles in the data model; the fourth (Support) is a special-cased admin with reduced privileges.

```mermaid
flowchart LR
    Visitor["Anonymous visitor<br/>(blog, public shops)"]
    Buyer["Buyer<br/>(User)"]
    Seller["Seller<br/>(Owner)"]
    Support["Support<br/>(admin variant)"]
    Admin["Admin"]

    Visitor -->|signs up| Buyer
    Buyer -->|requests seller mode<br/>+ admin approval| Seller
    Buyer & Seller -->|opens ticket| Support
    Support -->|escalates| Admin
```

---

## Buyer (User)

> [!example] Who they are
> Default new user. Anyone who signs up is a buyer until they request seller status. The persona name in the UI is **"User"** but the model role is `buyer`.

### Primary workflows

- **Browse and search** the public marketplace and request templates.
- **Create a [[Purchase Request]]** describing what they want — product type (physical / digital / service / consultation), budget, urgency, delivery info, attachments. See `backend/src/models/PurchaseRequest.ts`.
- **Review incoming [[Seller Offer]]s**, negotiate over chat, accept the best one.
- **Pay** via [[SHKeeper]] (custodial crypto invoice) or Web3 wallet ([[DePay]] + MetaMask through Wagmi).
- **Track the order** through `processing → delivery → delivered → confirming → completed` states.
- **Confirm receipt** (or let the SLA auto-confirm), leave a review, accrue points.
- **Open a [[Dispute]]** if delivery never lands, item is wrong, or quality is poor.
- **Refer friends** via their personal referral code; earn points per signup that converts.
- **Manage profile**: avatar, addresses, wallet address, passkeys, notification preferences, language.

### Key permissions

- Create, edit, cancel **own** purchase requests.
- Accept / reject offers on **own** requests.
- Initiate payments on **own** requests.
- Open disputes on **own** orders.
- Chat with sellers on **own** open requests and disputes.
- Read public sellers, public requests, public blog.
- **Cannot**: see other users' private data, moderate content, issue payouts, change another user's role.

### Dashboard sections (frontend routes)

The buyer dashboard lives under `/dashboard` (`frontend/src/app/dashboard/`). Notable areas:

- `/dashboard` — overview (recent requests, recent offers received, points balance)
- `/dashboard/request` — list, detail, and create flow for purchase requests
- `/dashboard/request-template` — saved templates and the catalogue of admin templates
- `/dashboard/chat` — all conversations
- `/dashboard/payment` — payment history (in + out) and active invoices
- `/dashboard/disputes` — open and resolved disputes
- `/dashboard/points` — points, levels, referrals
- `/dashboard/account` — profile, security (passkeys), addresses, language
- `/dashboard/post` — read-only blog reader (also public)

> [!tip] See also
> Full buyer playbook in [[User Guide]]. Auth specifics in [[Authentication Flow]].

---

## Seller (Owner)

> [!example] Who they are
> A buyer who has been promoted to `role: "seller"`. The UI sometimes calls them **"Owner"** because they own a shop. Sellers retain all buyer capabilities — they can still post requests of their own.

### Primary workflows

- **Configure shop**: shop name, banner, description, response time SLA, accepted payment methods, payout wallet address. See `backend/src/models/ShopSettings.ts` and `frontend/src/sections/shop-settings/`.
- **Discover requests** through the seller feed (filtered by category and preferred-seller status). Receive live notifications when a relevant request is posted via the `sellers` / `seller-<id>` Socket.IO rooms (`backend/src/app.ts:101-112`).
- **Submit offers** with price, currency (USDT default, USDC, USD, EUR, IRR supported), delivery time, optional attachments and notes.
- **Negotiate** in the per-request chat — bilateral with the buyer until an offer is accepted.
- **Fulfil** the order: ship physical goods (with optional tracking number), or upload/email digital deliverables.
- **Use the [[delivery code]]** for physical handoffs: a six-digit one-time code the buyer reads to the courier to confirm receipt.
- **Receive payout** automatically via SHKeeper to the configured wallet once the order is finalised (admin-triggered batch or per-order based on shop policy).
- **Manage [[Request Templates]]** scoped to their shop — publish "off-the-shelf" offerings buyers can purchase in one click.
- **Engage with reviews and disputes**: respond to reviews, contest disputes, provide evidence.

### Key permissions

- All buyer permissions.
- Create / edit / withdraw **own** seller offers.
- Read all public purchase requests + read-only access to requests where they have an active offer.
- Manage **own** shop settings, payout wallet, business hours.
- Publish [[Request Templates]] scoped to their shop.
- Mark orders as shipped, upload digital deliverables, request delivery codes.
- Respond in disputes they are a party to.
- **Cannot**: see another seller's analytics, edit another seller's shop, moderate the platform.

### Dashboard sections

Seller dashboard reuses the same `/dashboard` shell with extra modules:

- `/dashboard/shops` — public-facing shop browser (also visible to buyers)
- `/dashboard/shop-settings` — edit own shop, payout wallet, working hours
- `/dashboard/request-template` — create / edit shop-scoped templates
- `/dashboard/payment` — receivables, payout history, pending releases
- `/dashboard/disputes` — disputes where the seller is the respondent

> [!tip] See also
> [[Seller Guide]] walks through onboarding, first listing, and payout setup end-to-end. [[Payments Overview]] explains the escrow + payout state machine.

---

## Admin

> [!example] Who they are
> Platform operators with full read/write access. Admins are seeded at startup via `backend/src/infrastructure/database/init-admin.ts`. There is typically one root admin (`admin@amn.gg`) and additional admins promoted through database operations or a dedicated admin-creation endpoint.

### Primary workflows

- **Moderate users**: suspend / unsuspend accounts (`User.status: "active" | "suspended" | "deleted"`, see `backend/src/models/User.ts`), promote buyers to sellers, ban repeat offenders.
- **Moderate marketplace content**: categories (`Category` model), request templates (the canonical platform-wide ones), blog posts.
- **Resolve disputes**: get assigned to disputes, drive them to resolution, choose an outcome (`refund | replacement | compensation | warning_seller | ban_seller | no_action`). See `backend/src/services/dispute/DisputeService.ts` *(planned, not yet implemented)*.
- **Operate payments**: trigger payouts, fetch on-chain transactions, manually confirm stuck payments (the manual transaction-hash flow described in `backend/TODO.md`), audit the SHKeeper webhook history (`services/payment/shkeeper/webhookStats.ts`).
- **Configure the platform**: levels (`LevelConfig`), points multipliers, blog seed content, default templates.
- **Run data cleanup**: `/api/admin/cleanup` exposes destructive maintenance utilities (`services/admin/`).
- **Author blog posts** via the TipTap rich-text editor.
- **Monitor health**: SHKeeper status (background health monitor in `app.ts:433`), Redis, MongoDB.

### Key permissions

- **All** read and write across the platform — no row-level scoping.
- Promote users, change roles, suspend accounts.
- Approve / reject seller applications.
- Resolve any dispute, override any payment state.
- Trigger payouts and refunds.
- Edit / delete any blog post, template, or category.
- Run admin cleanup endpoints (irreversible — use with care).
- Access the full Sentry stream and webhook logs.

### Dashboard sections

Admins see the buyer/seller surfaces plus dedicated admin modules (typically under `/dashboard` with admin-only guards, growing into a dedicated `/admin` area in later versions):

- User management (search, suspend, role change)
- Dispute queue with assignment and resolution
- Payment console (manual confirmation, payout dispatch, webhook log)
- Category and template management
- Blog editor (publish / unpublish / featured)
- Platform analytics (TODO — see `backend/TODO.md`)
- Data cleanup utilities

> [!warning] Destructive operations
> `/api/admin/cleanup/*` and direct role mutations are not undoable. Admin actions should be logged to an audit trail. Audit logging is on the roadmap (`backend/TODO.md` → Security Enhancements → Audit Logging).

> [!tip] See also
> [[Admin Guide]] gives the step-by-step for moderation, dispute resolution, and payment operations.

---

## Support

> [!example] Who they are
> A dedicated support persona — the seeded `support@amn.gg` account — that exists to handle user tickets and triage disputes without granting full destructive access. Implemented as an `admin` role with a restricted permission profile applied in middleware (see `backend/TODO.md` → "Support user creation").

### Primary workflows

- **Join existing chats** to assist a buyer or seller in real time.
- **Triage disputes**: read incoming disputes, attach notes, assign to the right admin, set priority.
- **Answer user queries** about payments and orders without performing the payment action itself.
- **Escalate** anything that requires destructive action (refunds, bans, manual payouts) to a full admin.

### Key permissions

- Read access to all user accounts (no PII edits).
- Read access to all disputes and chats.
- Comment / reply in disputes and chats (write access scoped to messages, not resolution).
- **Cannot**: change roles, issue payouts, suspend users, delete content, resolve a dispute, edit settings.

### Dashboard sections

Support sees a stripped-down admin view focused on the inbox:

- Support chat queue
- Dispute triage list
- User lookup (read-only)
- Order lookup (read-only)

---

## Cross-cutting concerns

### Role transitions

| From | To | How | Audit |
|---|---|---|---|
| Anonymous | Buyer | Self-service signup | `User` created |
| Buyer | Seller | Application → admin approval | `User.role` change |
| Buyer / Seller | Admin | Manual DB / boot-time seed | High-risk, manual |
| Admin | Support | Permission profile applied at middleware | Role stays `admin` |

### Permission model

Permissions are enforced at three layers:

1. **Route middleware** (e.g. `requireAuth`, `requireRole('admin')`) — coarse gating on the HTTP layer.
2. **Service guards** — finer ownership checks (e.g. "you can only edit a request whose `buyerId` matches your `userId`").
3. **Frontend route guards** — `frontend/src/auth/guard/` hides UI from users who would be rejected anyway, preventing dead-ends.

### Identity sources

- **Email + password** — primary, with bcrypt hashing.
- **Passkey (WebAuthn)** — multi-device, stored in `User.passkeys[]`.
- **Google OAuth** — server-verified, links by email.

See [[Authentication Flow]] for the full sequence diagram.

### Internationalisation per persona

All four personas see the same six-language UI (en, fr, vi, cn, ar, fa) with the default fallback being Persian (`fa`) — see `frontend/src/locales/locales-config.ts:39`. Date formatting switches to the Jalali calendar in Persian.

---

## See also

- [[Introduction]] — project mission and target audience framing.
- [[System Overview]] — where each persona fits in the architecture.
- [[Authentication Flow]] — how identity becomes a role.
- [[Admin Guide]] — operational handbook for admins and support.
- [[User Guide]] — buyer journey end-to-end.
- [[Seller Guide]] — seller onboarding and shop ops.
- [[Glossary]] — definitions of every domain term referenced above.