verdant-vercel

byEmmanuel Mutugi

yeah creTE THIS FOR VERCEL

landing pagedashboardLogin
landing page

Comments (0)

No comments yet. Be the first!

System Requirements

System Requirements Document for verdant-vercel

1. Introduction

Page 1 of 66

1.1 PROJECT: LOOTLY — COMPLETE FULL-STACK REWARDS PLATFORM

You are a senior full-stack software architect, UI/UX designer, Node.js engineer, database engineer and security engineer.

Your task is to BUILD a complete, production-ready rewards platform called LOOTLY.

Do not simply generate a landing page or a frontend prototype. Build the complete functional application, including frontend, backend, database integration, authentication, administrative dashboard, financial system, offerwall integration and deployment configuration.

The final product must be deployable directly to Vercel.

==================================================

  1. BRAND IDENTITY

Brand: LOOTLY

Tagline: Turn your time into rewards.

Description:

LOOTLY is a Get Paid To (GPT) rewards platform where eligible users discover surveys, sponsored offers and online tasks, earn rewards and request withdrawals.

FINAL GOAL:

LOOTLY must be a real, modern, secure, fully functional rewards platform.

Page 2 of 66

2. System Overview

LOOTLY is a Get Paid To (GPT) rewards platform — "Turn your time into rewards." Eligible users discover surveys, sponsored offers and online tasks, earn rewards, and request withdrawals. The deliverable is not a landing page or frontend prototype: it is a complete, production-ready full-stack application — frontend, serverless backend, Neon PostgreSQL schema and migrations, Google authentication, user dashboard, admin dashboard, Offerwall.me integration, reward engine, withdrawal management and immutable financial ledger — deployable directly to Vercel under the project name verdant-vercel.

2.1 Actors

  • User — signs in with Google, holds a stable internal UUID, earns in KES, and requests withdrawals.
  • Super administrator — exactly two default super administrators, with identical full administrative permissions. They reach /admin automatically and manage platform settings, users, withdrawals and Offerwall.me. No other role has initial admin access.
  • Offerwall.me (supporting system) — supplies opportunities and postbacks; not a human role.

2.2 End-to-End Journey

  1. Create an account via Continue with Google.
  2. Discover available opportunities in the Earning Hub.
  3. Complete eligible activities.
  4. Receive verified rewards (provider postback validated, deduplicated, converted to KES, written to the ledger).
  5. Request a withdrawal (funds reserved in the ledger).
  6. Receive a manually processed payment.
Page 3 of 66

2.3 Capability Coverage

Public landing page — hero "Your time has value. Make it count." with supporting text "Discover surveys, explore sponsored offers and complete online tasks to earn rewards," primary CTA Continue with Google, secondary CTA How it works; sections for how LOOTLY works, exploring earning opportunities, surveys and offers, rewards and withdrawals, why LOOTLY, FAQ and footer.

User dashboard — profile image, username, greeting, available KES balance, pending rewards, lifetime earnings, completed tasks, successful withdrawals, an earnings overview chart, recent activity and main navigation.

Earning Hub — categories for surveys, sponsored offers, tasks, partner offerwalls and other admin-enabled opportunities; each with icon, description, available opportunities, estimated reward when supplied by a provider, and eligibility information.

Reward engine and ledger — all user-facing balances in KES. The immutable ledger records every financial event: reward credit, pending reward, reward reversal, withdrawal reservation, withdrawal release.

Page 4 of 66

Admin application — separate premium app at /admin with desktop sidebar and mobile navigation. Financial reporting distinguishes gross provider revenue, user rewards, outstanding reward liabilities, paid withdrawals and platform revenue; platform profit is never computed from total user earnings as revenue. Charts cover daily registrations, daily rewards, provider revenue, withdrawals and top earning users, with date filters. User management shows profile image, username, Google email, registration date, account status, available balance, pending rewards, lifetime earnings, completed activities and withdrawals. Also covered: Google OAuth settings, announcements and in-app notifications, settings autosave, referral tracking, and an administrator-only system health page with connection testing, database health checks and migration status, plus authentication, provider callback and deployment diagnostics.

Data and platform — PostgreSQL tables include users, user_sessions, admin_roles, platform_settings, encrypted_settings, offerwall_settings, reward_transactions, provider_conversions, withdrawals, payout_records, referrals, referral_rewards, announcements, notifications, audit_logs and deployment_logs, with UUID primary keys. The initial DATABASE_URL comes from Vercel environment variables, and the application must initialize without a pre-existing database-settings record.

Page 5 of 66

2.4 Boundaries

This is a serverless application: no fake server restart is implemented. A new Vercel deployment replaces the deployed application version but does not erase the Neon database, and the application continues on the same production domain. Withdrawals are paid manually, not automatically. The two super administrators are the only initial admin users; broader role and page catalogs are not established here.

<!-- planning-notes:v1:start -->

Planning notes

Planning resolved these page and owner names itself instead of stopping. Review them before building.

Added during planning

  • user dashboard: Named in your document but missing from the generated catalog
  • landing: Named in your document but missing from the generated catalog
  • system health: Named in your document but missing from the generated catalog
<!-- planning-notes:v1:end -->

3. Functional Requirements

Page 6 of 66

3.1 PROJECT: LOOTLY — COMPLETE FULL-STACK REWARDS PLATFORM

  • Server-side financial calculations.

  • Transactional financial operations.

Authentication:

  • Google OAuth exclusively.
  1. GOOGLE SIGN-IN ONLY

Google authentication must be the only login method.

Enable Google OAuth integration.

Users should:

  • Click Continue with Google.

  • Authenticate using their Google account.

  • Automatically create a LOOTLY account on first login.

  • Return to their existing account on subsequent logins.

  • Have a persistent user profile.

  • Sign out securely.

Use verified Google identity information.

Require:

  • Valid OAuth state.

  • Correct redirect URI.

Page 7 of 66
  • Verified Google identity.

  • Secure server-side session handling.

  • HTTP-only cookies.

==================================================

  1. DEFAULT SUPER ADMINISTRATORS

These two accounts are the permanent initial SUPER ADMINS.

  1. itsmanuh2040@gmail.com

  2. smontana025@gmail.com

MANDATORY BEHAVIOUR:

After either account successfully signs in using Google, automatically grant SUPER_ADMIN privileges.

Both accounts must:

  • Have identical full administrative permissions.

  • Access /admin automatically.

  • Manage all platform settings.

  • Manage users.

  • Manage withdrawals.

  • Manage Offerwall.me.

  • Manage database settings.

  • Manage deployment settings.

Page 8 of 66
  • View platform financial statistics.

  • View audit logs.

  • Manage other administrative settings.

  1. PUBLIC LANDING PAGE

Create an exceptional landing page.

The first screen must immediately communicate what LOOTLY does.

Hero:

"Your time has value. Make it count."

Supporting text:

"Discover surveys, explore sponsored offers and complete online tasks to earn rewards."

Primary CTA:

Continue with Google.

Secondary CTA:

How it works.

Sections:

  1. Hero section.

  2. How LOOTLY works.

  3. Explore earning opportunities.

  4. Surveys and offers.

  5. Rewards and withdrawals.

Page 9 of 66
  1. Why LOOTLY.

  2. Frequently asked questions.

  3. Footer.

Explain the process:

  • Create your account.

  • Discover available opportunities.

  • Complete eligible activities.

  • Receive verified rewards.

  • Request withdrawal.

  • Receive manually processed payment.

  1. USER DASHBOARD

Create a beautiful authenticated dashboard.

Display:

  • Profile image.

  • Username.

  • Greeting.

  • Available KES balance.

  • Pending rewards.

  • Lifetime earnings.

  • Completed tasks.

Page 10 of 66
  • Successful withdrawals.

Create a clear earnings overview chart.

Include recent activity.

Main navigation:

  • Dashboard.

  • Earn.

  • Surveys.

  • Offers.

  • Tasks.

  • History.

  • Withdraw.

  • Referrals.

  • Profile.

  1. EARNING HUB

Build an attractive central earning section.

Categories:

  • Surveys.

  • Sponsored offers.

  • Tasks.

  • Partner offerwalls.

Page 11 of 66
  • Other admin-enabled opportunities.

Each category should have:

  • Icon.

  • Description.

  • Available opportunities.

  • Estimated reward when supplied by a provider.

  • Eligibility information.

  • Clear action button.

If a provider has not been configured, display an honest configuration notice.

Do not generate fake offers.

  1. OFFERWALL.ME INTEGRATION

Integrate Offerwall.me properly.

Use the official current Offerwall.me documentation.

The administrator must be able to configure:

  • Placement ID.

  • Public API key.

  • Private signing secret.

  • Bearer token.

  • Postback URL.

Page 12 of 66
  • Placement enabled/disabled status.

  • Reward conversion rate.

Do not invent API endpoints, signature formats, query parameters or response fields.

Implement the provider's documented signed-user-ID integration.

Each LOOTLY user must have a stable internal UUID.

Generate signed user identities server-side.

POSTBACK SYSTEM:

Create a secure endpoint for Offerwall.me reward notifications.

The endpoint must:

  1. Receive provider notifications.

  2. Validate the documented authentication/signature mechanism.

  3. Validate the user identity.

  4. Validate the provider transaction ID.

  5. Verify the reward amount and currency.

  6. Check for duplicate transactions.

  7. Convert the reward to KES using configured conversion rules.

  8. Credit the user using an atomic database transaction.

  9. Record the provider conversion.

  10. Record the user's reward ledger entry.

Page 13 of 66
  1. Return the exact response required by the provider's documentation.

Implement idempotency.

A repeated callback must never credit a user twice.

Provide a test mode that is clearly separated from production.

Do not credit users through frontend success callbacks.

  1. KENYAN SHILLINGS REWARD ENGINE

All user-facing balances must be in KES.

Examples:

KSh 50

KSh 100

KSh 200

KSh 500

KSh 1,000

Build an admin-configurable reward conversion system.

Admin controls:

  • Point conversion rate.

  • Provider currency conversion.

  • Minimum withdrawal.

  • Maximum withdrawal.

  • Withdrawal fee.

Page 14 of 66
  • Referral rewards.

  • Manual adjustments.

Suggested initial withdrawal threshold:

  1. FINANCIAL LEDGER

Build a proper immutable financial ledger.

Every financial event must be recorded.

Supported event types:

  • Reward credit.

  • Pending reward.

  • Reward reversal.

  • Withdrawal reservation.

  • Withdrawal release.

  • Withdrawal payment.

  • Administrative adjustment.

  • Referral reward.

Each ledger record must contain:

  • Unique ID.

  • User ID.

  • Transaction type.

  • Amount.

Page 15 of 66
  • Currency.

  • Reference ID.

  • Description.

  • Timestamp.

  • Status.

  • Related provider or withdrawal reference.

Ensure users cannot spend reserved or pending funds.

Ensure concurrent withdrawal requests cannot result in negative balances.

  1. WITHDRAWAL SYSTEM — MANUAL CRYPTO PAYMENTS

IMPORTANT:

LOOTLY does not automatically transfer money to users.

The platform owner personally processes withdrawals and pays users externally using cryptocurrency.

Do not integrate an automatic crypto payment gateway.

Do not request private keys or seed phrases.

USER WITHDRAWAL EXPERIENCE:

Users can:

  • View available balance.

  • View minimum withdrawal.

  • Select an enabled payout method.

Page 16 of 66
  • Enter requested amount.

  • Enter payout address.

  • Select the appropriate blockchain network.

  • Submit withdrawal request.

  • Track request status.

  • View payment history.

Initial payout method:

Cryptocurrency, configured by the administrator.

The admin controls supported currencies and networks.

WITHDRAWAL PROCESS:

  1. User submits request.

  2. Validate the balance and withdrawal limits.

  3. Reserve the requested amount atomically.

  4. Create withdrawal record.

  5. Display submitted status.

  6. Admin reviews request.

  7. Admin approves, rejects or marks processing.

  8. Admin sends the actual payment externally.

  9. Admin records transaction hash/reference.

  10. Admin marks the request paid.

Page 17 of 66
  1. User sees the paid status.

USER-FACING STATUS:

  • Submitted.

  • Processing.

  • Paid.

  • Declined.

USER-FACING STATUS:

  • Submitted.

  • Processing.

  • Paid.

  • Declined.

Do not expose internal administrative notes.

A withdrawal must never appear as paid before actual payment confirmation.

If declined:

  • Release reserved funds.

  • Return funds to available balance.

  • Record the reason.

  • Preserve audit history.

Display a clear message:

"Withdrawals are manually processed. Processing times may vary."

Page 18 of 66

Do not promise instant payments.

  1. ADMIN DASHBOARD

Build a separate premium admin application.

Route:

/admin

Only the two default super administrators can access it initially.

Admin dashboard should have a desktop sidebar and mobile navigation.

ADMIN OVERVIEW:

Display live database-backed statistics:

  • Total users.

  • Active users.

  • New registrations.

  • Gross provider revenue.

  • Total user rewards generated.

  • Pending rewards.

  • Total user liabilities.

  • Total withdrawals requested.

  • Total withdrawals paid.

  • Pending withdrawal count.

  • Platform gross margin.

Page 19 of 66

Clearly distinguish:

Gross provider revenue

User rewards

Outstanding reward liabilities

Paid withdrawals

Platform revenue

Do not calculate platform profit using total user earnings as revenue.

Include charts:

  • Daily registrations.

  • Daily rewards.

  • Provider revenue.

  • Withdrawals.

  • Top earning users.

Allow date filters.

  1. USER MANAGEMENT

Create a comprehensive user management page.

Display:

  • Profile image.

  • Username.

  • Google email.

Page 20 of 66
  • Registration date.

  • Account status.

  • Available balance.

  • Pending rewards.

  • Lifetime earnings.

  • Completed activities.

  • Withdrawals.

Features:

  • Search.

  • Filtering.

  • Sorting.

  • User profile details.

  • Account suspension.

  • Account reactivation.

  • Financial transaction history.

  • Withdrawal history.

Admin can manually adjust a user's balance.

Every adjustment must:

  • Require an amount.

  • Require a reason.

Page 21 of 66
  • Be recorded in the ledger.

  • Be recorded in audit logs.

  • Be executed server-side.

Never allow silent balance modification.

  1. TOP EARNERS

Build a real leaderboard.

Display:

  • Rank.

  • User avatar.

  • Username.

  • Total earnings.

  • Completed activities.

  • Successful withdrawals.

Filters:

  • Today.

  • This week.

  • This month.

  • All time.

Allow users to opt out of public leaderboard visibility.

  1. WITHDRAWAL ADMINISTRATION
Page 22 of 66

Create a complete withdrawal management interface.

Admin can:

  • View all requests.

  • Search by user.

  • Filter by status.

  • View payout address.

  • View requested amount.

  • View date.

  • View payment history.

  • Approve.

  • Reject with a reason.

  • Mark processing.

  • Mark paid.

  • Add transaction hash.

  1. OFFERWALL ADMINISTRATION

Create a dedicated Offerwall.me settings page.

Admin can:

  • Enter placement ID.

  • Enter public API key.

  • Enter private secret.

Page 23 of 66
  • Enter bearer token.

  • Enable/disable provider.

  • Configure reward conversion.

  • View postback URL.

  • View recent conversions.

  • View failed callbacks.

  • View duplicate callbacks.

  • View integration status.

Provide a test connection feature if supported by the official API.

Never claim the provider is connected without a successful real validation.

  1. DATABASE SETTINGS

Create an administrator-only database configuration page.

  • Connection testing.

  • Database health checks.

  • Migration status.

Admin interface:

  • Database connection URL input.

  • Test connection button.

  • Connection status.

  • Save configuration.

Page 24 of 66
  • Diagnostic error messages.

The application must be able to initialize without a previously configured database-settings record.

Changing the database must follow a safe process:

  1. Validate the new connection.

  2. Check schema compatibility.

  3. Require explicit confirmation.

  4. Preserve old database data.

  5. Run migrations only after confirmation.

  6. Switch connections safely.

  7. Provide rollback instructions.

  8. GOOGLE OAUTH ADMIN SETTINGS

Create a Google authentication configuration page.

Provide:

  • OAuth configuration status.

  • Client ID status.

  • Redirect URI.

  • Setup instructions.

  • Authentication test.

Do not display client secrets.

Page 25 of 66

Initial Google credentials are supplied through Vercel environment variables.

Do not pretend that editing a database record automatically updates Vercel environment variables.

If an OAuth configuration change requires a deployment, explain and handle it through the deployment workflow where possible.

  1. DEPLOYMENT MANAGEMENT

Create a secure deployment management page.

The administrator can trigger a new deployment through a protected Vercel deployment hook or Vercel API.

Display:

  • Last deployment time.

  • Deployment status.

  • Deployment URL.

  • Deployment result.

  • Recent deployment history.

Require confirmation before deployment.

  1. AUTOSAVE

Implement autosave for administrative configuration forms.

Requirements:

  • Debounced saving approximately every three seconds after changes.

  • Saving indicator.

Page 26 of 66
  • Saved indicator.

  • Error indicator.

  • Automatic recovery after refreshing.

  • Handle network interruptions.

  • Prevent conflicting updates.

Financial actions must NOT use delayed autosave.

Withdrawal requests, payment confirmations, reward credits and balance adjustments must be committed immediately with transactional database operations.

  1. REFERRAL SYSTEM

Build a referral system.

Every user receives a unique referral code.

Features:

  • Personal referral link.

  • Referral statistics.

  • Registered referrals.

  • Configurable referral commission.

  • Referral reward history.

Admin controls referral settings.

Prevent:

  • Self-referrals.
Page 27 of 66
  • Duplicate rewards.

  • Referral abuse.

  • Multiple accounts exploiting the same referral.

Only issue referral rewards according to explicitly configured eligibility rules.

  1. ANNOUNCEMENTS AND NOTIFICATIONS

Build an in-app notification system.

Users can receive notifications for:

  • Verified reward credits.

  • Withdrawal submitted.

  • Withdrawal processing.

  • Withdrawal paid.

  • Withdrawal declined.

  • Referral rewards.

  • Platform announcements.

Admin can create, edit and publish announcements.

  1. USER PROFILE

User profile must display:

  • Google profile picture.

  • Username.

Page 28 of 66
  • Google email.

  • Registration date.

  • Referral code.

  • Leaderboard privacy setting.

  • Preferred payout method.

  • Saved payout address.

Users can update supported profile fields.

Do not let users change their verified Google identity through a normal profile form.

  1. FAQ AND TRANSPARENCY

Create a complete FAQ page.

Explain:

  • How LOOTLY works.

  • How users earn rewards.

  • How provider conversions work.

  • Why some surveys may be unavailable.

  • How withdrawals work.

  • What the KSh 200 minimum means.

  • How long processing may take.

  • Why withdrawals are manually processed.

Page 29 of 66
  • Protected administrative endpoints.

Implement:

  • Centralized API error handling.

  • User-friendly error messages.

Do not expose stack traces or secrets to normal users.

Implement:

  • Structured server logs.

Implement:

  • Database health endpoint.

Implement:

  • Authentication diagnostics.

Implement:

  • Provider callback diagnostics.

Implement:

  • Deployment diagnostics.

Add an administrator-only system health page.

  1. FINAL TESTING

Before declaring the project complete, test:

  1. Landing page.

  2. Google authentication.

Page 30 of 66
  1. New user registration.

  2. Existing user login.

  3. Both default super administrators.

  4. Normal user authorization.

  5. Unauthorized admin access.

  6. Database migrations.

  7. User dashboard.

  8. Offerwall configuration.

  9. Signed user identities.

  10. Provider postback validation.

  11. Duplicate postback rejection.

  12. Reward conversion.

  13. Reward ledger.

  14. Withdrawal requests.

  15. Withdrawal reservations.

  16. Withdrawal approval.

  17. Withdrawal rejection.

  18. Balance restoration.

  19. Manual payment recording.

Page 31 of 66
  1. Admin user management.

  2. Top earners.

  3. Referral tracking.

  4. Notifications.

  5. Settings autosave.

  6. Database health checks.

  7. Deployment management.

  • Reward engine.

  • Withdrawal management.

  • Financial ledger.

  • Referral system.

  • Settings.

If credentials are missing, build the complete integration and configuration interface, explain exactly what credentials are needed, and never substitute fake functionality.

Users sign in using Google, complete eligible activities, receive verified KES rewards and request withdrawals.

The platform owner controls users, integrations, financial records, reward rates, manual crypto payouts and deployments.

Both must have automatic full administrator access after successful Google authentication.

Page 32 of 66

4. User Personas

4.1 PROJECT: LOOTLY — COMPLETE FULL-STACK REWARDS PLATFORM

Target audience:

  • Students.

  • Young adults.

  • Job seekers.

  • People looking for additional online earning opportunities.

5. Core User Flows

Page 33 of 66

5.1 Sign in with Google

Actors: Visitor or returning user; Google identity provider; LOOTLY server (supporting).

Trigger: The user selects Continue with Google on the landing page or sign-in screen.

  1. The user is redirected to Google and authenticates with their Google account.
  2. LOOTLY validates the OAuth state, the redirect URI and the verified Google identity.
  3. On first login, LOOTLY automatically creates the user's account and persistent profile; on subsequent logins it returns the user to their existing account.
  4. A secure server-side session is established using HTTP-only cookies; the two default super administrators receive full administrator access automatically after successful Google authentication.
  5. The user lands on the authenticated dashboard.

Failure/recovery: If state, redirect URI or identity verification fails, no session is created and the user may retry. Sign-out clears the session securely.

Page 34 of 66

5.2 Explore the landing page and learn how LOOTLY works

Actors: Visitor.

Trigger: The visitor opens the public landing page.

  1. The hero immediately communicates the proposition — "Your time has value. Make it count." — with supporting text about surveys, sponsored offers and online tasks.
  2. The visitor may take the primary CTA (Continue with Google, flow 1) or the secondary CTA (How it works).
  3. How it works explains the process: create your account, discover available opportunities, complete eligible activities, receive verified rewards, request withdrawal, receive manually processed payment.

5.3 Review earnings on the dashboard

Actors: Authenticated user.

Trigger: The user opens the dashboard.

  1. The dashboard displays profile image, username, greeting, available KES balance, pending rewards, lifetime earnings, completed tasks and successful withdrawals.
  2. The user reviews the earnings overview chart and recent activity.
  3. The user navigates via Dashboard, Earn, Surveys, Offers, Tasks, History, Withdraw, Referrals and Profile; on mobile these actions remain accessible.
Page 35 of 66

5.4 Discover and complete earning opportunities

Actors: Authenticated user; activity providers (supporting).

Trigger: The user opens the Earn hub or a specific category.

  1. The user browses categories — surveys, sponsored offers, tasks, partner offerwalls and other admin-enabled opportunities — each showing an icon, description, available opportunities, estimated reward when supplied by a provider, and eligibility information.
  2. The user selects an eligible opportunity and completes it with the provider.
  3. For Offerwall.me, the provider sends a postback; LOOTLY validates the signature mechanism, user identity, provider transaction ID, reward amount and currency, and checks for duplicates (idempotent rejection of repeat postbacks).
  4. The reward is converted to KES using configured conversion rules and credited in an atomic database transaction, with the provider conversion and the user's reward ledger entry recorded.
  5. The credited reward appears in the user's balance and history, and the user receives a verified-reward-credit notification.

Failure/recovery: Invalid, duplicate or failed callbacks are not credited and are surfaced to the administrator in the Offerwall.me settings view (recent conversions, failed callbacks, duplicate callbacks).

Page 36 of 66

5.5 Request a withdrawal

Actors: Authenticated user; administrator (payout).

Trigger: The user opens Withdraw.

  1. The user views available balance and minimum withdrawal, selects an enabled payout method (initially cryptocurrency, with admin-controlled currencies and networks), enters the requested amount, payout address and blockchain network, and submits.
  2. LOOTLY validates balance and withdrawal limits, reserves the amount atomically, creates the withdrawal record and shows Submitted; the user is notified that the withdrawal was submitted.
  3. The administrator reviews the request and approves, rejects or marks it processing; the user is notified of processing.
  4. The administrator sends payment externally, records the transaction hash/reference and marks the request paid; the user is notified of payment.
  5. The user tracks status (Submitted, Processing, Paid, Declined) and views payment history.

Failure/recovery: If declined, reserved funds are released back to the available balance, the reason is recorded, the user is notified, and audit history is preserved. LOOTLY never transfers money automatically and never requests private keys or seed phrases.

Page 37 of 66

5.6 Appear on the Top Earners leaderboard

Actors: Authenticated user; other users (supporting).

Trigger: The user views Top Earners or manages profile visibility.

  1. The leaderboard shows rank, avatar, username, total earnings and completed activities, filterable by today, this week, this month and all time.
  2. The user may opt out of public leaderboard visibility from their profile.

5.7 Refer new users

Actors: Authenticated user; referred visitor (supporting).

Trigger: The user opens Referrals.

  1. The user views their unique referral code, personal referral link, referral statistics, registered referrals and referral reward history.
  2. The user shares the link; a referred visitor registers through it and is recorded as a registered referral.
  3. When a referral qualifies, the configured referral commission is credited and the user receives a referral-reward notification.
Page 38 of 66

5.8 Manage profile and notifications

Actors: Authenticated user; administrator (announcements).

Trigger: The user opens Profile or the notification area.

  1. The user updates supported profile fields; changes save with debounced saving approximately every three seconds after changes, showing saving, saved and error indicators, recovering automatically after refresh, handling network interruptions and preventing conflicting updates.
  2. The user reviews notifications for verified reward credits, withdrawal submitted, processing, paid and declined, referral rewards and platform announcements.
  3. The administrator creates, edits and publishes announcements, which appear to users as notifications.

5.9 Administer the platform

Actors: Super administrator.

Trigger: The administrator opens /admin.

Page 39 of 66
  1. The administrator signs in via Google (flow 1) and accesses the separate premium admin application with desktop sidebar and mobile navigation; only the two default super administrators can access it initially.
  2. The administrator reviews platform statistics — daily registrations, daily rewards, provider revenue, withdrawals and top earning users — with date filters, plus financial statistics and audit logs.
  3. In user management, the administrator searches, filters, sorts, views profile details and financial/withdrawal history, suspends or reactivates accounts, and makes manual balance adjustments (each recorded).
  4. In withdrawal administration, the administrator views all requests, searches by user, filters by status, inspects payout address, amount, date and payment history, and approves, rejects with a reason, marks processing, marks paid or adds a transaction hash.
  5. In Offerwall.me settings, the administrator configures placement ID, public API key, private secret, bearer token, postback URL, enabled status and reward conversion, and reviews recent conversions, failed and duplicate callbacks and integration status; a test connection is offered only if supported by the official API, and the provider is never shown as connected without a successful real validation.
  6. In database settings, the administrator enters the connection URL, tests the connection, views status and diagnostic errors, and saves configuration; a database change follows a safe process — validate the new connection, check schema compatibility, require explicit confirmation, preserve old data, run migrations only after confirmation, switch connections safely and provide rollback instructions.
  7. On the deployment management page, the administrator triggers a new deployment through a protected Vercel deployment hook or Vercel API after confirmation, and views last deployment time, status, URL, result and recent deployment history.
  8. The administrator reviews the administrator-only system health page.
Page 40 of 66

Failure/recovery: Diagnostic error messages guide correction of failed database connections; failed provider validations leave integration status unconfirmed.

6. Visuals Colors and Theme

[Design proposal; unspecified choices are defaults.]

Page 41 of 66

6.1 Visuals, Colours and Theme

LOOTLY is a premium dark interface: deep charcoal ground, neon lime signal, glass-like cards, subtle gradients, modern typography, clean layouts, beautiful charts, large readable icons and clear navigation. It is mobile-first and responsive, and must stay fast and legible on low-end Android devices. Explicitly excluded: Matrix animations, excessive neon effects, generic Bootstrap templates, cluttered dashboards, blue/indigo-on-white primaries, and gradient blobs behind centred hero text.

Palette (dark mode, by role)

RoleToken
Background (≈70% of page)#0B0D0B
Surface / glass#141814 at 60% opacity, 1px #C6FF3D22 border
Text#F2F5EE
Primary (one action per screen, key KES figures)#C6FF3D
Accent (positive ledger rows only)#7BE0A0
Muted#8D968A

Lime is a signal, not a toy: it marks exactly one action per screen and the key KES figures. Mint marks credits only.

Typography — Headings Space Grotesk Semi-bold 600, tracking −0.02em; uppercase micro-labels 11px at 0.16em tracking; tabular numerals for all KES values. Body Manrope. Modular scale 1.25: 40/32/24/18/15/13. Hero headline clamp(38px, 7vw, 84px).

Page 42 of 66

Shape and spacing — Glass panels with 20px radii and 1px light borders; soft capsule buttons; sharp 4px corners on ledger rows; one blurred lime glow behind the hero card only.

Layout — Mobile-first single column with a floating glass balance card above the fold and an attractive bottom navigation with four large lime line icons plus a raised centre balance chip, keeping the main balance easy to see and actions accessible. Desktop: 12-column grid, 7/5 split, side rail at 1280px.

Imagery — No stock photos; the interface is the image: a tilted glass balance card, a KES earnings chart, and offer category tiles with large lime line icons. The LOOTLY wordmark uses a lime loot-bag glyph with a cut notch; the same glyph is the favicon.

Readability rule — Headlines, wordmarks, labels, numbers, card text and controls stay whole inside the viewport and their container at 375px, 768px and 1280px, wrapping or scaling to fit; nothing covers them. Decoration may crop, bleed, rotate or overlap freely. Scrolling rows may cross the edge by design provided every item becomes fully readable as it passes, with a usable static arrangement under reduced motion.

Defaults (labelled) — Chart series colours beyond lime/mint, icon stroke weight and glow blur radius are unspecified; use lime for the primary series, mint for positive deltas, muted for baselines, and a 2px line-icon stroke.

Page 43 of 66

6.2 PROJECT: LOOTLY — COMPLETE FULL-STACK REWARDS PLATFORM

Visual identity:

  • Premium dark interface.

  • Deep black/charcoal backgrounds.

  • Neon lime-green accent color.

  • Modern typography.

  • Glass-like cards.

  • Subtle gradients.

  • Clean layouts.

  • Beautiful charts.

  • Smooth but lightweight animations.

  • Large readable icons.

  • Clear and attractive navigation.

The design must be mobile-first and responsive.

Do not use Matrix animations, excessive neon effects, generic Bootstrap templates or cluttered dashboards.

Create a distinctive LOOTLY logo and favicon.

On mobile:

  • Use an attractive bottom navigation.

On mobile:

Page 44 of 66
  • Make the main balance easy to see.

Make the leaderboard visually attractive.

Page 45 of 66

7. Signature Design Concept

[Design proposal; unspecified choices are defaults.]

Muse: Michal Malewicz. Layered translucency with a lime signal: the requested glass cards, subtle gradients and floating layers get a real method, so lime on charcoal reads as a confident signal rather than a neon toy. The mood is dark, calm and premium — fast and trustworthy on a low-end Android phone, never loud or casino-like.

Public entry (landing page). A charcoal field with an oversized lime headline on the left, set in two lines at clamp(38px, 7vw, 84px): “Your time has value. Make it count.” Under it, the subline “Discover surveys, explore sponsored offers and complete online tasks to earn rewards.”, then a solid lime capsule “Continue with Google” with charcoal text and a 1px inner light edge, and a secondary “How it works” control. A tilted glass balance card overlaps the headline block from the lower right, showing a KES figure with a 7-bar chart; a soft lime glow sits behind that card only. The first screen immediately communicates what LOOTLY does.

Signature moves

  • Tilted glass balance card overlapping the hero headline, carrying a live KES figure and 7-bar chart.
  • Solid lime capsule primary button, charcoal text, 1px inner light edge.
  • Lime loot-bag glyph with a cut notch as wordmark mark and favicon.
  • Ledger and activity rows with tabular numerals and a mint left rule for credits, muted rule for debits.
  • Mobile bottom navigation: four large lime line icons and a raised centre balance chip.
Page 46 of 66

Section rhythm — Hero, How LOOTLY works, Explore earning opportunities, Surveys and offers, Rewards and withdrawals, Why LOOTLY, FAQ, Footer. The leaderboard is made visually attractive. Withdrawal copy states “Withdrawals are manually processed. Processing times may vary.”; no guaranteed income and no promised instant payments anywhere in the visual language.

Page 47 of 66

8. Interaction Model & Motion Direction

[Design proposal; unspecified choices are defaults.]

Interaction Model: Animated Motion Tempo: restrained Hero Dimensionality: layered_2d

Landing Hero Motion Brief

  • Focal subject: the tilted glass balance card with its KES figure and 7-bar chart, overlapping the lime headline block.
  • Thesis: the visitor reads the headline and the live-looking balance card (input) → the card settles into its tilt with its bars drawing in and the lime glow drifting slowly behind it (transformation) → the eye lands on the solid lime “Continue with Google” capsule as the single action (outcome). Only accepted content, states and controls are recomposed.
  • Motion vocabulary: 160ms ease-out fades with 4px rises on card entry; one slow lime glow drift behind the hero card; no Matrix rain, scanlines or particle fields.
  • Composed first frame: charcoal field, two-line lime headline left, glass card already tilted at lower right with bars at rest, glow soft behind the card, lime capsule under the headline.
  • Reduced motion: all motion stops under prefers-reduced-motion — card, bars and glow render in their final static arrangement; scrolling rows wrap or scroll so every item can be brought fully into view.

Animations stay lightweight and API calls minimal to protect fast initial loading, small bundles and low-end Android performance; pages are lazy-loaded.

Page 48 of 66

8.1 PROJECT: LOOTLY — COMPLETE FULL-STACK REWARDS PLATFORM

On mobile:

  • Keep actions accessible.

9. Non-Functional Requirements

Page 49 of 66

9.1 PROJECT: LOOTLY — COMPLETE FULL-STACK REWARDS PLATFORM

Use Vercel-compatible TypeScript serverless functions and ensure the final build works with Vercel's deployment system.

  • Secure cookies in production.

  • Appropriate SameSite protection.

  • CSRF protection where applicable.

Never trust a frontend-supplied user ID or role.

IMPLEMENTATION:

  • Compare normalized Google email addresses.

  • Require email_verified=true.

  • Perform authorization server-side.

  • Never rely on frontend role information.

  • Seed default administrators safely.

  • Preserve both administrators during database migrations.

  • Never allow normal users to promote themselves.

  • Never allow these two default accounts to be accidentally removed or demoted.

If an unauthorized user accesses /admin, redirect them to the user dashboard or show an access-denied page.

The admin interface must not have a publicly visible admin button.

On mobile:

Page 50 of 66
  • Avoid horizontal overflow.

All figures must come from real database records.

Never display fabricated user balances or earnings.

Private secrets must never appear in:

  • Browser JavaScript.

  • Public API responses.

  • HTML source.

  • Frontend environment variables.

  • Client-side logs.

Use precise monetary calculations.

Prefer integer minor units or a proper PostgreSQL NUMERIC representation.

Never use JavaScript floating-point arithmetic for financial balances.

Do not silently edit or delete historical financial transactions.

Use atomic database transactions.

Never expose sensitive user information publicly.

Show pending requests prominently.

Require confirmation for sensitive financial actions.

Prevent duplicate payment marking.

Record every action in audit logs.

==================================================

Page 51 of 66

Secrets must be encrypted at rest using an application master key.

Do not return secret values to the frontend after they have been saved.

SECURITY:

Never expose database credentials to frontend JavaScript.

Never return the full connection URL after saving.

Encrypt credentials if stored in application settings.

Use a separate ENCRYPTION_KEY.

Do not silently switch production databases.

Do not display client secrets.

Do not pretend that editing a database record automatically updates Vercel environment variables.

Notifications must persist in Neon.

Use immutable ledger records.

Prevent accidental financial record deletion.

  1. SECURITY REQUIREMENTS

Security is mandatory.

Implement:

  • Server-side authorization.

  • Google OAuth verification.

  • Secure session handling.

  • HTTP-only cookies.

Page 52 of 66
  • CSRF protection.

  • Rate limiting.

  • Input validation.

  • SQL injection protection.

  • XSS prevention.

  • Secure response headers.

  • Offerwall callback verification.

  • Idempotency.

  • Atomic withdrawal reservation.

  • Audit logging.

  • Secrets encryption.

  1. ERROR HANDLING AND MONITORING

  2. PERFORMANCE

Optimize for:

  • Mobile devices.

  • Slow networks.

  • Low-end Android devices.

  • Fast initial loading.

  • Minimal bundle size.

  • Lazy-loaded pages.

Page 53 of 66
  • Efficient PostgreSQL queries.

  • Pagination.

  • Caching where appropriate.

Keep animations lightweight.

Avoid excessive API calls.

  1. Mobile responsiveness.

  2. Production build.

  3. Vercel serverless compatibility.

  • Security implementation.

10. Tech Stack

Page 54 of 66

10.1 PROJECT: LOOTLY — COMPLETE FULL-STACK REWARDS PLATFORM

  1. REQUIRED TECHNOLOGY STACK

Frontend:

  • React.

  • Vite.

  • TypeScript.

  • Tailwind CSS.

  • Lucide React icons.

  • Reusable components.

  1. REQUIRED TECHNOLOGY STACK

Backend:

  • Node.js.

  • Vercel serverless functions.

  • TypeScript.

  • Secure REST API endpoints.

  • Server-side authentication and authorization.

Database:

  • Neon PostgreSQL.

  • Drizzle ORM or an equally maintainable PostgreSQL ORM.

Page 55 of 66
  • Database migrations.

  • Proper foreign keys and indexes.

Deployment:

  • Vercel.

  • GitHub.

  • One repository.

  • Serverless API functions within the same application.

The application must have actual server-side code under /api. A frontend-only application is not acceptable.

Use Vercel-compatible TypeScript serverless functions and ensure the final build works with Vercel's deployment system.

IMPORTANT:

Use npm for dependency installation and scripts.

==================================================

  1. PROJECT ARCHITECTURE

Organize the application clearly.

Suggested structure:

lootly/

api/

auth/

admin/
Page 56 of 66
users/

offerwall/

rewards/

withdrawals/

settings/

referrals/

health.ts

src/

components/

layouts/

pages/

admin/

hooks/

services/

contexts/

types/

public/

db/

schema.ts

migrations/

index.html

Page 57 of 66

package.json

tsconfig.json

vite.config.ts

vercel.json

.env.example

README.md

The frontend and API must use the same Vercel domain.

Use clean URL routing and configure SPA fallback without interfering with /api routes.

Store credentials in environment variables.

GOOGLE_CLIENT_ID=

GOOGLE_CLIENT_SECRET=

Google OAuth credentials will be entered when the application is being deployed and configured.

The initial database is configured using:

DATABASE_URL=

Support PostgreSQL connection strings including:

postgresql://user:password@host/database?sslmode=require

Support Neon PostgreSQL.

Support:

  • SSL.
Page 58 of 66
  • sslmode=require.

  • Pooled Neon connections.

  • Direct Neon connections where appropriate.

  1. DATABASE SCHEMA

Create a proper PostgreSQL relational schema.

Required tables:

users

user_sessions

admin_roles

platform_settings

encrypted_settings

offerwall_settings

reward_transactions

provider_conversions

withdrawals

payout_records

referrals

referral_rewards

announcements

notifications

audit_logs

Page 59 of 66

deployment_logs

Include:

  • UUID primary keys.

  • Foreign keys.

  • Unique constraints.

  • Proper indexes.

  • Created and updated timestamps.

  • Numeric financial columns.

  • Transactional operations.

  • Migration files.

GOOGLE_CLIENT_SECRET=

GOOGLE_CALLBACK_URL=

SESSION_SECRET=

ENCRYPTION_KEY=

OFFERWALL_PUBLIC_KEY=

OFFERWALL_PRIVATE_SECRET=

OFFERWALL_BEARER_TOKEN=

VERCEL_DEPLOY_HOOK=

APP_URL=

Document each variable.

Page 60 of 66
  1. Neon connection.

Provide:

  • Complete source code.

  • Frontend.

  • Serverless backend.

  • Neon database schema.

  • Migrations.

  • Google authentication.

  • Admin dashboard.

  • User dashboard.

  • Offerwall.me integration.

  • Vercel configuration.

  • .env.example.

  • README.

  • Deployment instructions.

Build LOOTLY as a complete Vercel-ready full-stack application using Neon PostgreSQL and serverless Node.js functions.

11. Assumptions and Constraints

Page 61 of 66

11.1 PROJECT: LOOTLY — COMPLETE FULL-STACK REWARDS PLATFORM

Primary currency: Kenyan Shillings (KES).

  • No email/password registration.

  • No password login.

  • No password-reset functionality.

  • One production domain.

Do not create a separate permanently running Express server.

GOOGLE OAUTH CONFIGURATION:

Provide clear documentation for:

  • Creating a Google Cloud project.

  • Enabling Google Identity/OAuth.

  • Creating OAuth credentials.

  • Adding the authorized JavaScript origin.

  • Adding the authorized redirect URI.

  • Configuring production and development callback URLs.

Do not hardcode secrets.

Never advertise guaranteed income.

Explain that available offers and earnings depend on location, eligibility and provider availability.

Page 62 of 66

Include appropriate age restrictions based on provider requirements and applicable laws.

KSh 200.

This is a configurable platform policy, not a guaranteed income promise.

IMPORTANT ARCHITECTURE:

The initial DATABASE_URL must come from Vercel environment variables.

If a Vercel environment variable must change, explain that a new deployment is necessary.

Never expose deployment tokens.

Never claim deployment succeeded before Vercel confirms it.

IMPORTANT:

This is a serverless application.

Do not implement a fake server restart.

A new Vercel deployment replaces the deployed application version. It does not erase the Neon database.

The application must continue using the same production domain.

==================================================

Do not require an email service.

Clearly communicate that earnings are not guaranteed and depend on eligible activities and provider availability.

All private credentials must be server-side only.

Never use VITE_ prefixes for private secrets.

Page 63 of 66

Never trust frontend financial values.

Never trust frontend admin roles.

Never expose:

  • Database URLs.

  • Google client secrets.

  • Offerwall private secrets.

  • Bearer tokens.

  • Encryption keys.

  • Vercel deployment tokens.

  1. ENVIRONMENT VARIABLES

Create a comprehensive .env.example.

Include:

DATABASE_URL=

GOOGLE_CLIENT_ID=

OFFERWALL_PUBLIC_KEY=

OFFERWALL_PRIVATE_SECRET=

OFFERWALL_BEARER_TOKEN=

The initial Offerwall.me credentials are configured after placement approval.

VERCEL_DEPLOY_HOOK=

The deployment hook is optional until deployment management is configured.

Page 64 of 66

Never include real secrets in GitHub.

Use test fixtures and clearly separated development/test data. Never create fake production earnings.

  1. DELIVERY REQUIREMENTS

Deliver the complete working project.

Do not stop after designing the landing page.

Do not leave critical features as non-functional buttons.

Do not substitute hardcoded statistics for database-backed data.

Do not claim integrations are connected when credentials have not been configured.

First inspect the project environment and establish the architecture. Then implement the complete application in logical stages, preserving a working build throughout development.

The two default super administrators are:

itsmanuh2040@gmail.com

smontana025@gmail.com

  • The product is to be created for deployment on Vercel.
  • Project name: verdant-vercel.

12. Glossary

Page 65 of 66

12.1 PROJECT: LOOTLY — COMPLETE FULL-STACK REWARDS PLATFORM

  • What happens when a reward is reversed.

  • How referrals work.

Page 66 of 66
Live
landing page design preview
visitor explores process
visitor chooses primary CTA
visitor proceeds to sign in
redirected to Google
state, redirect URI or identity verification fails
user retries sign in
session established
user reviews earnings overview
user navigates to Earn
user selects surveys category
user selects offers category
user selects tasks category
provider postback validated and credited
provider postback validated and credited
provider postback validated and credited
balance meets minimum withdrawal
request submitted and funds reserved
administrator declines request
reserved funds released to available balance
user opens Referrals
referred user qualifies
user opens Profile
user manages leaderboard visibility
user seeks transparency
landing page: Read hero proposition
landing: Review how it works
landing: Continue with Google
Login: 1. Authenticate with Google
Login: 2. Retry after failed verification
dashboard: Review balances and activity
user dashboard: Check earnings chart
earn: Browse earning categories
surveys: Start eligible survey
offers: Complete sponsored offer
tasks: Complete available task
History: Confirm verified reward credit
Withdraw: 1. Submit withdrawal request
Withdraw: 2. Track withdrawal status
Withdraw: 3. View declined reason
referrals: Share referral link
referrals: Review referral rewards
profile: Update profile fields
profile: Set leaderboard privacy
FAQ: Read withdrawal policy
Live
landing page design preview
visitor explores process
visitor chooses primary CTA
visitor proceeds to sign in
redirected to Google
state, redirect URI or identity verification fails
user retries sign in
session established
user reviews earnings overview
user navigates to Earn
user selects surveys category
user selects offers category
user selects tasks category
provider postback validated and credited
provider postback validated and credited
provider postback validated and credited
balance meets minimum withdrawal
request submitted and funds reserved
administrator declines request
reserved funds released to available balance
user opens Referrals
referred user qualifies
user opens Profile
user manages leaderboard visibility
user seeks transparency
landing page: Read hero proposition
landing: Review how it works
landing: Continue with Google
Login: 1. Authenticate with Google
Login: 2. Retry after failed verification
dashboard: Review balances and activity
user dashboard: Check earnings chart
earn: Browse earning categories
surveys: Start eligible survey
offers: Complete sponsored offer
tasks: Complete available task
History: Confirm verified reward credit
Withdraw: 1. Submit withdrawal request
Withdraw: 2. Track withdrawal status
Withdraw: 3. View declined reason
referrals: Share referral link
referrals: Review referral rewards
profile: Update profile fields
profile: Set leaderboard privacy
FAQ: Read withdrawal policy