audit: 2026-05-30 full-codebase audit — report, issues, docs, runbooks
Full-codebase-audit 2026-05-30 outputs: - Audit report: 09 - Audits/Full Codebase Audit - 2026-05-30.md - 81 issue files ISSUE-055..135 (decisions + 1 skipped no-brainer). - Scanner docs from scratch (was zero): architecture, data model, API ref, payment flow, operations runbook + repo README. - Doc-sync updates across API reference, data models, flows, design system. - Secret Rotation Runbook (08 - Operations) for the exposed credentials. - Reusable workflow guide (07 - Development) + .claude/workflows/full-codebase-audit.js. Issues remain status:open intentionally — the code fixes are uncommitted-then-committed working-tree changes per repo and aren't "resolved" until merged/deployed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Siavash Sameni
@@ -7,9 +7,9 @@ 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.
|
||||
> The hard role enum is defined in `backend/src/models/User.ts:94` as `"admin" | "buyer" | "seller" | "resolver"`. The `resolver` role was added to the backend in commit `fce8a19` and is now a first-class enum value in `User.ts`, `UserRole` enum in `shared/types/index.ts`, and the dispute routes. 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.
|
||||
Amn has five user personas. Four are first-class roles in the data model; the fifth (Support) is a special-cased admin with reduced privileges.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
@@ -18,11 +18,13 @@ flowchart LR
|
||||
Seller["Seller<br/>(Owner)"]
|
||||
Support["Support<br/>(admin variant)"]
|
||||
Admin["Admin"]
|
||||
Resolver["Resolver<br/>(dispute specialist)"]
|
||||
|
||||
Visitor -->|signs up| Buyer
|
||||
Buyer -->|requests seller mode<br/>+ admin approval| Seller
|
||||
Buyer & Seller -->|opens ticket| Support
|
||||
Support -->|escalates| Admin
|
||||
Admin -->|assigns role| Resolver
|
||||
```
|
||||
|
||||
---
|
||||
@@ -82,7 +84,7 @@ The buyer dashboard lives under `/dashboard` (`frontend/src/app/dashboard/`). No
|
||||
|
||||
- **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.
|
||||
- **Submit offers** with price in **USDT** (the only supported currency for the escrow MVP — USD/EUR/IRR removed in commit 3aaa2fe), 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.
|
||||
@@ -110,6 +112,7 @@ Seller dashboard reuses the same `/dashboard` shell with extra modules:
|
||||
- `/dashboard/request-template` — create / edit shop-scoped templates
|
||||
- `/dashboard/payment` — receivables, payout history, pending releases
|
||||
- `/dashboard/disputes` — disputes where the seller is the respondent
|
||||
- `/dashboard/seller/marketplace/offers` — **Offer Management** (tabbed view of all own offers filtered by status: pending / accepted / rejected / withdrawn; inline withdraw action; commit 9cf1686)
|
||||
|
||||
> [!tip] See also
|
||||
> [[Seller Guide]] walks through onboarding, first listing, and payout setup end-to-end. [[Payments Overview]] explains the escrow + payout state machine.
|
||||
@@ -193,6 +196,30 @@ Support sees a stripped-down admin view focused on the inbox:
|
||||
|
||||
---
|
||||
|
||||
## Resolver
|
||||
|
||||
> [!example] Who they are
|
||||
> A platform-employed dispute resolver (`role: "resolver"`). Added to the backend as a first-class role in commit `fce8a19`. Resolvers have targeted authority to mediate and formally resolve disputes — they can assign disputes, update status, issue final resolutions (including `ban_seller` or `refund`), view statistics, and bypass chat membership checks (commit `766a9a2`) to read/send in any chat.
|
||||
|
||||
### Primary workflows
|
||||
|
||||
- **Review dispute details**: read buyer and seller evidence, chat history, delivery confirmations.
|
||||
- **Communicate** directly through any chat — bypasses participant membership guard.
|
||||
- **Assign, update status, and resolve disputes** with the same actions as admins (`refund | replacement | compensation | warning_seller | ban_seller | no_action`).
|
||||
- **Monitor dispute health** via `GET /api/disputes/statistics`.
|
||||
|
||||
### Key permissions
|
||||
|
||||
- Full triage on disputes: `POST /:id/assign`, `PATCH /:id/status`, `POST /:id/resolve`, `GET /statistics`.
|
||||
- Read and write messages in any chat (bypass membership check in `ChatService`).
|
||||
- Read any dispute and its evidence.
|
||||
- **Cannot**: change roles, issue payouts, suspend users, delete content, access non-dispute admin endpoints.
|
||||
|
||||
> [!note] Implementation
|
||||
> The `resolver` role was added as a first-class backend enum in commit `fce8a19` (`User.ts`, `UserRole` in `shared/types/index.ts`, dispute routes). Chat bypass was added in commit `766a9a2`.
|
||||
|
||||
---
|
||||
|
||||
## Cross-cutting concerns
|
||||
|
||||
### Role transitions
|
||||
@@ -202,6 +229,7 @@ Support sees a stripped-down admin view focused on the inbox:
|
||||
| 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 |
|
||||
| Buyer / Seller | Resolver | Admin role assignment | `User.role` change |
|
||||
| Admin | Support | Permission profile applied at middleware | Role stays `admin` |
|
||||
|
||||
### Permission model
|
||||
|
||||
Reference in New Issue
Block a user