🗺️ Platform Architecture Overview — How Everything Fits Together

[LarytheLord]

Purpose

This discussion is the single best starting point for any contributor — human or AI agent. It maps every part of the platform, how data flows between them, and why things are built the way they are.

Read this before picking up any issue.

---

What Adventurers Guild Is

A gamified developer marketplace with a dual purpose:

1. External marketplace — Companies post coding quests. Adventurers (developers) apply, complete them, earn XP + payment, and climb ranks F→S.
2. Open Paws delivery backbone — The platform powers the Open Paws Bootcamp and Internship Programme. Bootcamp students and interns complete real client work through the same quest infrastructure.

The key insight: rank is a trust signal. A D-rank adventurer has shipped production code across multiple reviewed quests. Clients get skill-vetting built into the pipeline.

---

Three User Roles

┌─────────────────┬────────────────────────────────────────────────────────┐
│ Role            │ What they do                                           │
├─────────────────┼────────────────────────────────────────────────────────┤
│ adventurer      │ Browse quests, apply, submit work, earn XP + payment  │
│ company         │ Post quests, review submissions, pay on approval       │
│ admin           │ Mediate everything. Full access to all routes.         │
│                 │ Open Paws team IS the admin.                           │
└─────────────────┴────────────────────────────────────────────────────────┘

Critical admin note: admin has no CompanyProfile. Any code that updates companyProfile must check role !== admin first or it will crash.

---

Two Delivery Tracks

QuestTrack enum:
  OPEN      → public marketplace (any adventurer)
  INTERN    → 20 paid interns (May–Jul 2026), D+ rank, squads of 3–5
  BOOTCAMP  → 20–50 bootcamp students, F/E rank only, solo or pairs

Track is a hard boundary enforced at the API level:

• Bootcamp users cannot see or apply to INTERN or OPEN quests (server-enforced, not just UI)
• Ineligible bootcamp users (tutorials incomplete) only see Tutorial quests
• INTERN track requires rank D or above

---

Quest Lifecycle

draft → available → in_progress → review → completed
                              ↘
                               cancelled

Key: lib/quest-lifecycle.ts syncs quest status with its assignments. Multi-participant quests stay available until all slots are filled.

Assignment Lifecycle

assigned → started → in_progress → submitted → [pending_admin_review] → review → completed
                                                                      ↘
                                                                       needs_rework

pending_admin_review is a Phase 2 addition (issue #105). It sits between submitted and review for BOOTCAMP and INTERN track quests. OPEN track goes direct to review.

---

Auth Architecture

• NextAuth v4, credentials provider, JWT strategy, 30-day sessions
• lib/auth.ts — config + JWT/session callbacks
• lib/api-auth.ts — requireAuth(...roles) helper used in ALL API routes
• middleware.ts — RBAC route protection with longest-prefix-match
• JWT carries: id, role, rank, xp

Session shape:

{
  user: {
    id: string
    role: adventurer | company | admin
    rank: F | E | D | C | B | A | S
    xp: number
    name: string
    email: string
  }
}

---

Database: Key Models

User
  ├── AdventurerProfile  (rank, xp, skills, streak, completion rate)
  ├── CompanyProfile     (companyName, questsPosted, totalSpent)
  ├── BootcampLink       (studentId, cohort, tutorial flags, eligibility)
  ├── Assignments[]      (one per quest application)
  └── Party[]            (squad memberships — Phase 2)

Quest
  ├── track: QuestTrack  (OPEN / INTERN / BOOTCAMP)
  ├── difficulty: UserRank (F–S — maps to required adventurer rank)
  ├── parentQuestId      (optional — sub-quest relationship)
  ├── revisionCount      (increments on needs_rework)
  ├── maxRevisions       (default 2 — cap before escalation)
  ├── Assignments[]      (applications and active work)
  └── Party?             (squad assigned to this quest — Phase 2)

Assignment
  ├── status: AssignmentStatus
  └── QuestSubmission[]  (work submitted for review)

Full schema: prisma/schema.prisma — always read this before touching models.

---

API Surface

Public (no auth):
  GET  /api/public/stats          Landing page stats
  GET  /api/public/quests         Landing page quest showcase

Auth:
  POST /api/auth/register         Create account
  POST /api/auth/[...nextauth]    NextAuth handler
  POST /api/onboard               Bootcamp webhook (secret-validated)

Quests:
  GET  /api/quests                Browse (with track/status/difficulty filters)
  POST /api/quests                Create quest (company/admin)
  GET  /api/quests/[id]           Quest detail with assignments + party
  PUT  /api/quests/[id]           Update quest
  POST /api/quests/assignments    Apply / accept assignment
  GET  /api/quests/[id]/assignments  Applicant list (company)
  PUT  /api/quests/[id]/assignments  Review assignment (company)

Admin:
  GET/POST /api/admin/quests      Admin quest management
  PUT      /api/admin/quests      Status change, add notes
  GET/POST /api/admin/users       User management
  PATCH    /api/admin/qa-queue/[id]  QA approve/reject (Phase 2)

Payments:
  POST /api/payments              Record transaction
  POST /api/payments/webhooks/stripe    Stripe webhook
  POST /api/payments/webhooks/razorpay  Razorpay webhook

---

Frontend: Layout Rules

• app/layout.tsx renders <Navigation /> + <SiteFooter /> for ALL pages
• Navigation returns null on /dashboard/** and /admin routes
• Dashboard has its own sidebar in app/dashboard/layout.tsx
• Never add <Navigation /> or <SiteFooter /> inside a page component

---

XP and Ranking

Ranks: F → E → D → C → B → A → S

XP is granted in lib/xp-utils.ts when a submission is approved. Rank updates automatically. Adventurers only access quests at or below their rank (enforced by the quest difficulty field).

For bootcamp students: XP is earned but no payment in Phase 2.

---

Payment Architecture (Phase 2)

lib/payment-provider.ts routes to:

• Stripe Connect — international payments
• Razorpay — India (INR)

Platform fee: 15% of quest reward.

BOOTCAMP track: XP-only. No payment until Phase 3.

---

Design System Rules

• Primary color: orange-500 only. No other accent colors.
• Rank colors: quarantined to <RankBadge> component only
• Dark backgrounds: bg-slate-950 / bg-slate-900
• New components: use shadcn/ui as base primitives

---

Useful File Map

Purpose	File
NextAuth config	lib/auth.ts
DB client + retry	lib/db.ts
API auth helper	lib/api-auth.ts
RBAC middleware	middleware.ts
Quest lifecycle sync	lib/quest-lifecycle.ts
XP/rank logic	lib/xp-utils.ts
Payment routing	lib/payment-provider.ts
DB schema	prisma/schema.prisma
Session types	types/next-auth.d.ts