nxtgauge-backend-rust/wir.md

Nxtgauge — Work Implementation Roadmap (wir.md)

Beeceptor Mock Payment Gateway

• Base URL: https://nxtgauge.free.beeceptor.com
• POST /payments/create-order → 200
• POST /payments/verify → 200
• GET /payments/:id/status → 200

---

Wave 1 — Foundation Fixes (Must do first)

W1-A: Fix AppState type alias in all profession services

Every admin.rs uses crate::AppState but main.rs never defines it. Add after use contracts::ProfessionState;:

type AppState = ProfessionState;

Files to modify:

• apps/photographers/src/main.rs
• apps/makeup_artists/src/main.rs
• apps/tutors/src/main.rs
• apps/developers/src/main.rs
• apps/video_editors/src/main.rs
• apps/graphic_designers/src/main.rs
• apps/social_media_managers/src/main.rs
• apps/fitness_trainers/src/main.rs
• apps/catering_services/src/main.rs

W1-B: Fix employee create endpoint mismatch

Admin UI POSTs to /api/admin/employees/provision but backend registers POST /.

• File: apps/employees/src/handlers/employees.rs
• Add: .route("/provision", post(create_employee)) alias

W1-C: Gateway routing for missing admin namespaces

File: apps/gateway/src/main.rs — add to resolve_upstream:

1. Add || path.starts_with("/api/admin/ugc-content-creators") to UGC branch
2. Route admin/tax, admin/ledger, admin/orders → payments service

---

Wave 2 — Backend Features (parallel after Wave 1)

W2-A: Suspend/activate for all 9 professions + UGC

Add PATCH /{id}/status to each profession admin.rs:

.route("/{id}/status", patch(set_status))

async fn set_status(
    State(state): State<AppState>,
    Path(id): Path<Uuid>,
    Json(body): Json<StatusPayload>,
) -> impl IntoResponse {
    // 1. Query user_id from profession table WHERE id = $1
    // 2. UPDATE users SET status = $1 WHERE id = $2
    // 3. Return 200 or error
}

#[derive(Deserialize)]
struct StatusPayload { status: String }  // "ACTIVE" | "INACTIVE" | "SUSPENDED"

Uses existing UserRepository::update_status.

W2-B: UGC full admin module (currently zero admin routes)

• Create: apps/ugc_content_creators/src/admin.rs (copy photographers pattern, adapt table name)
• Modify: apps/ugc_content_creators/src/main.rs — add mod admin; and .nest("/api/admin/ugc-content-creators", admin::router())
• Use Router<ProfessionState> directly (no crate::AppState alias needed)

W2-C: Backend endpoints for tax, ledger, orders

Add to apps/payments/src/main.rs (or new apps/payments/src/admin.rs):

• GET /api/admin/tax, POST /api/admin/tax, DELETE /api/admin/tax/{id} — CRUD against taxes table
• GET /api/admin/ledger — query tracecoin_ledger JOIN users, paginated
• GET /api/admin/orders — query payments/orders table

Also add GET /api/admin/credits/reconcile-report and POST /api/admin/credits/reconcile/{order_id} for W4-F.

---

Wave 3 — Frontend Dashboard Pages (parallel after Wave 1, biggest work)

Architecture

• Add all new page names to REAL_PAGES in dashboard.tsx
• Add <Match> cases in the <Switch> block
• Pass rolePrefix from ROLE_PREFIXES[role()]
• Add 'Accepted Leads' and 'Services' to ROLE_BASED_SIDEBAR for all 10 professional roles
• Update ICON_MAP in DashboardShell.tsx

W3-A: Professional pages (shared by all 10 professions via rolePrefix prop)

File: src/components/dashboard/LeadsMarketplacePage.tsx

• GET /api/{rolePrefix}/marketplace?page=N&limit=20
• Paginated requirement cards: title, budget, location, deadline, profession category
• "Send Request" → POST /api/{rolePrefix}/leads/request with { requirement_id }

File: src/components/dashboard/MyRequestsPage.tsx

• GET /api/{rolePrefix}/leads/requests/me
• Status badges: PENDING, ACCEPTED, REJECTED, CANCELLED
• 24h countdown from created_at for PENDING requests
• Cancel → DELETE /api/{rolePrefix}/leads/requests/{id}

File: src/components/dashboard/AcceptedLeadsPage.tsx

• GET /api/{rolePrefix}/leads/accepted/me
• Customer contact info revealed (phone, email)
• Detail → GET /api/{rolePrefix}/leads/accepted/{id}

File: src/components/dashboard/CreditsWalletPage.tsx

• GET /api/{rolePrefix}/wallet/me → balance summary (total, reserved, available)
• GET /api/{rolePrefix}/wallet/me/ledger?page=1&limit=20 → transaction history
• Buy TraceCoins flow (Beeceptor):
  1. Show package selection
  2. POST https://nxtgauge.free.beeceptor.com/payments/create-order
  3. POST https://nxtgauge.free.beeceptor.com/payments/verify
  4. Refresh wallet balance on success

File: src/components/dashboard/ServicesPage.tsx

• GET /api/{rolePrefix}/services/me — list services
• Add: POST /api/{rolePrefix}/services/me
• Edit: PATCH /api/{rolePrefix}/services/me/{id} (add to api.ts)
• Delete: DELETE /api/{rolePrefix}/services/me/{id}

Shared: src/components/dashboard/BuyTracecoinsModal.tsx

• Reusable modal used by CreditsWalletPage and CustomerRequirementsPage
• Calls Beeceptor: create-order → verify
• Props: { rolePrefix: string; onSuccess: () => void; onClose: () => void }

W3-B: Company pages

File: src/components/dashboard/CompanyJobsPage.tsx

• GET /api/companies/jobs — list with status badges (DRAFT, PENDING, APPROVED, CLOSED)
• Create form → POST /api/companies/jobs
• Submit for approval → POST /api/companies/jobs/{id}/submit

File: src/components/dashboard/CompanyApplicationsPage.tsx

• Job selector dropdown
• GET /api/companies/jobs/{id}/applications
• Status update → PATCH /api/companies/applications/{id}/status

W3-C: Job Seeker pages

File: src/components/dashboard/JobSeekerJobsPage.tsx

• GET /api/jobseeker/jobs?page=N&limit=20 with filters
• Apply modal → POST /api/jobseeker/jobs/{id}/apply

File: src/components/dashboard/JobSeekerApplicationsPage.tsx

• GET /api/jobseeker/applications
• Status badges, withdraw → DELETE /api/jobseeker/applications/{id}/withdraw (add to api.ts)

W3-D: Customer pages

File: src/components/dashboard/CustomerRequirementsPage.tsx

• GET /api/customers/requirements — list with expiry countdown
• Create form → POST /api/customers/requirements
• Submit → POST /api/customers/requirements/{id}/submit

File: src/components/dashboard/ReceivedResponsesPage.tsx

• Requirement selector at top
• GET /api/customers/requirements/{id}/requests
• Accept → POST /api/customers/requirements/{id}/requests/{lead_id}/approve
• Reject → POST /api/customers/requirements/{id}/requests/{lead_id}/reject

W3-E: Explore Nxtgauge + Switch Services

File: src/components/dashboard/ExploreNxtgaugePage.tsx

• Extract from DashboardDesignPreview (lines ~5920–5990)
• Props: { roleKey: string; rolePrefix: string; exploreRoles: Array<{key: string; name: string}> }
• Switch Services → same component or redirect to Explore Nxtgauge

---

Wave 4 — Admin Completions (parallel with Wave 3)

W4-A: Verification action wiring

File: src/routes/admin/verification.tsx Wire existing stub handlers:

• Approve: POST /api/gateway/api/admin/verifications/{id}/approve
• Reject: POST /api/gateway/api/admin/verifications/{id}/reject + { reason: string }
• Request Docs: POST /api/gateway/api/admin/verifications/{id}/request-documents + { message, documents[] }
• Refresh list after each action

W4-B: Employee create — resolve by email

File: src/routes/admin/employees/create.tsx Two-step flow:

1. Email lookup → GET /api/admin/users?email={email}
2. If found: pre-fill name, show confirmation
3. If not: allow new user creation
4. Submit with user_id from resolved user (or use POST /api/admin/employees/provision)

W4-C: Admin Ledger

File: src/routes/admin/ledger.tsx

• Needs W2-C backend first
• Add: user filter, date range filter, entry type filter, pagination

W4-D: Tax management

File: src/routes/admin/tax.tsx — UI already complete

• Just needs W1-C (gateway routing) + W2-C (backend endpoint)

W4-E: Order management

File: src/routes/admin/order.tsx — UI already complete

• Just needs W1-C + W2-C

W4-F: Credit reconciliation

File: src/routes/admin/financial/reconcile.tsx — currently a redirect stub

• Needs W2-C backend endpoint
• Build reconciliation view: orders vs. coins credited discrepancies
• "Reconcile" action → POST /api/admin/credits/reconcile/{order_id}

---

Wave 5 — Token Security (independent, any time)

W5-A: Move access token to in-memory

File: src/lib/auth.tsx

let _token: string | null = null;
export const setToken = (t: string | null) => { _token = t; };
export const getToken = (): string | null =>
  _token || sessionStorage.getItem('nxtgauge_access_token') || localStorage.getItem('nxtgauge_access_token') || null;

File: src/lib/api.ts

• Update getAuthHeaders() to use getToken() from auth.tsx

---

New Files to Create

Backend

• apps/ugc_content_creators/src/admin.rs

Frontend

• src/components/dashboard/LeadsMarketplacePage.tsx
• src/components/dashboard/MyRequestsPage.tsx
• src/components/dashboard/AcceptedLeadsPage.tsx
• src/components/dashboard/CreditsWalletPage.tsx
• src/components/dashboard/ServicesPage.tsx
• src/components/dashboard/BuyTracecoinsModal.tsx
• src/components/dashboard/CompanyJobsPage.tsx
• src/components/dashboard/CompanyApplicationsPage.tsx
• src/components/dashboard/JobSeekerJobsPage.tsx
• src/components/dashboard/JobSeekerApplicationsPage.tsx
• src/components/dashboard/CustomerRequirementsPage.tsx
• src/components/dashboard/ReceivedResponsesPage.tsx
• src/components/dashboard/ExploreNxtgaugePage.tsx

---

Files to Modify

Backend

• apps/gateway/src/main.rs — W1-C
• apps/employees/src/handlers/employees.rs — W1-B
• apps/photographers/src/main.rs + all 8 other profession main.rs — W1-A
• apps/ugc_content_creators/src/main.rs — W2-B
• All 9 profession admin.rs files — W2-A
• apps/payments/src/main.rs (or new payments/src/admin.rs) — W2-C

Frontend

• src/routes/dashboard.tsx — expand REAL_PAGES + add Match cases + update ROLE_BASED_SIDEBAR
• src/components/DashboardShell.tsx — update ICON_MAP
• src/lib/auth.tsx — W5-A
• src/lib/api.ts — add updateService, withdrawApplication helpers + W5-A

Admin

• src/routes/admin/verification.tsx — W4-A
• src/routes/admin/employees/create.tsx — W4-B
• src/routes/admin/ledger.tsx — W4-C
• src/routes/admin/financial/reconcile.tsx — W4-F