Questboard

DON'T JUST COMPLETE JOBS. CONQUER QUESTS.

Comment

📜 Project Story: QuestBoard

Invisible gamification: feels like a serious platform, rewards like a game.

Inspiration Behind QuestBoard

Modern freelancing often feels tedious, mechanical, and laden with transactional friction. On one hand, traditional freelance platforms impose high, static commissions without rewarding user loyalty. On the other hand, relationships between clients and service providers are frequently bogged down in rigid corporate bureaucracy.

We were inspired to deconstruct the traditional client and freelancer dynamics into a fantasy adventure: Patrons and Adventurers.

By blending bold Neo-Brutalist aesthetics (thick borders, high-contrast colors, solid shadows without blur) with RPG mechanics, we designed QuestBoard. The platform implements an invisible gamification model. On the surface, it operates as a secure, high-grade SaaS platform for professional contracts. Under the hood, it drives retention and satisfaction through immersive game loops resembling a classic fantasy RPG.

How We Built the Project

QuestBoard was developed as a modern, high-performance, full-stack application. We utilized the following stack:

  1. Frontend Layer:

    • React 19 & Vite 6: Provided a fast and highly reactive Single Page Application layout.
    • React Router v6: Handled clean multi-page navigation and protected role-based routing (Patron vs Adventurer) post-login.
    • Tailwind CSS v4: We leveraged the CSS-first setup to declare custom tokens (burnt orange, as well as sans-serif, mono-spaced, and decorative font families) in the styling configuration without any configuration files.
    • Framer Motion (motion v12): Created smooth animations for page transitions, brutalist hover states, and dynamic experience point pools.
    • Three.js (React Three Fiber): Added premium 3D decorations, including the interactive sword in the stone scene on the landing page and the data-driven 3D progress ring on the dashboard.

  2. Backend & Database Layer:

    • Vercel Serverless Functions: All backend handlers are consolidated into a single entry API router.
    • AWS Aurora Serverless v2 PostgreSQL: Serves as the high-scale relational database for platform records.
    • Drizzle ORM: Used for mapping database tables and managing schema migrations.
    • Clerk Authentication: Manages secure authentication and user sessions, integrated with onboarding fields for role classification.

Gamification Math & Escrow Model

The business logic of QuestBoard is governed by precise mathematical formulas implemented inside the core gamification engine.

A. Dynamic Split Fee Model

Patrons pay a flat $5\%$ booking fee to secure funding in the escrow account. Adventurers start with a $12\%$ platform fee, which reduces dynamically as they level up ($L$) from level 1 to level 5.

The Adventurer fee percentage ($F_{adventurer}$) as a function of Level ($L$) is calculated as follows:

$$ F_{adventurer}(L) = \max\left(0.04, \ 0.12 - (L - 1) \times 0.02\right) $$

If the quest is collaborated under a guild (Guild Quests), the leader receives a $2\%$ ($0.02$) discount as a collaboration incentive:

$$ F_{adventurer, \ guild}(L) = \max\left(0.02, \ F_{adventurer}(L) - 0.02\right) $$

Escrow Ledger Formulas ($B$ = Milestone Budget):

  • Total Patron Payment ($P_{patron}$):

$$ P_{patron} = B + (B \times 0.05) = B \times 1.05 $$

  • Adventurer Net Receives ($A_{receives}$):

$$ A_{receives} = B - (B \times F_{adventurer}) $$

  • Total Platform Revenue ($R_{platform}$):

$$ R_{platform} = (B \times 0.05) + (B \times F_{adventurer}) $$

B. Experience Points (XP) Distribution

Each quest awards a base XP amount ($XP_{base}$) based on its rarity tier:

  • RARE: $300\text{ XP}$
  • EPIC: $650\text{ XP}$
  • LEGENDARY: $1000\text{ XP}$

XP is distributed across the total milestones ($M$) of a quest:

$$ XP_{milestone} = \left\lfloor \frac{XP_{base}}{M} \right\rfloor $$

For the final milestone completed on time, the Adventurer receives a completion bonus of $10\%$ of the base quest XP:

$$ XP_{last} = \left\lfloor \frac{XP_{base}}{M} \right\rfloor + \left\lfloor XP_{base} \times 0.10 \right\rfloor $$

For Guild Quests, the base milestone XP is distributed to members at a flat $50\%$ to incentivize cooperation while preventing XP farming:

$$ XP_{guild_member} = \left\lfloor XP_{milestone} \times 0.50 \right\rfloor $$

Challenges Faced

  1. Accurately Handling Monetary Values: Floating-point arithmetic in JavaScript can introduce precision errors (for example, 0.12 - 0.04 resulting in 0.08000000000000002).

    • Solution: We introduced a rounding utility using standard mathematical functions to round all financial balances to 2 decimal places.

  2. Data Model Drift: Early visual mockups had inconsistent field names for badges and quest statuses.

    • Solution: We structured our state machine into three distinct enums: a quest status for the project, an application status for the proposal, and a milestone status for the milestones, and enforced unified type definitions.

  3. SSL Connectivity with AWS Aurora: Serverless handlers running locally initially rejected local handshakes with the cloud database due to missing local SSL certificates.

    • Solution: We adjusted the database connection pool settings to permit secure local testing.

What We Learned

  • Incentive Alignment is Key: Gamification works best when game loops align with financial benefits. Linking XP to lower platform cuts provides a strong incentive for quality work.
  • Consolidated Logic Rules: Housing math operations in a centralized utility avoids code duplication and prevents state mismatch.
  • Tailwind v4 is Highly Efficient: The CSS-first setup simplifies maintenance of styling tokens and brutalist aesthetic components.
Share this project:

Updates