# Gold Mine Bitcoin A wolf-themed Bitcoin mining dashboard for managing virtual plans, wallet requests, referrals, raffles, and admin-reviewed account activity. ## Masterplan - Deliver a premium, mobile-friendly “Mine • Earn • Refer • Grow” experience centered on animated wolf-branded mining machines. - Let authenticated users activate 30-day mining plans from wallet balance, monitor earnings, and submit deposit/withdrawal requests. - Support referral incentives, special machine offers, raffle eligibility, transaction history, and account settings in one dashboard. - Provide an in-app admin console for reviewing users, deposits, withdrawals, raffle configuration, and financial activity. - Current implementation is a client-side prototype backed by GenMB Auth and GenMB KV storage; it does **not** connect to real payment processors or blockchain mining. ## Tech Stack & Architecture - **React + TypeScript** application, mounted in `src/main.tsx`. - **React Router DOM** uses `HashRouter`; routes are hash-based (for example, `#/dashboard`) rather than server-routed URLs. - **Tailwind CSS v4** is imported through `@import "tailwindcss"` in `src/styles/main.css`, with custom semantic theme tokens and component CSS. - **Lucide React** provides all UI icons. - **GenMB Auth** is injected by `index.html` and exposed as `window.genmb.auth`. - Supports Google sign-in, email/password registration with OTP verification, magic links, and password reset. - **GenMB KV** is injected by `index.html` and exposed as `window.genmb.kv`. - It is the app’s persistence layer; there is no dedicated REST API or server code in this repository. - App-wide state is currently held in `src/App.tsx` with React `useState`: - authenticated `user` - persisted user `profile` - transaction `records` - persisted raffle configuration - loading/error/toast/sidebar state - `App.tsx` owns routing, auth lifecycle, KV reads/writes, page rendering, dialogs, validation, and admin actions. There is intentionally no separate store, service layer, or page-directory abstraction yet. - Reusable presentation components are limited to: - `src/components/MinerMachine.tsx` for themed animated miner cards. - `src/components/WolfMark.tsx` for the CSS-built brand mark. - `src/components/ui.tsx` for buttons, dialogs, and toasts. ### Persistence Keys KV records are namespaced with `gm:`: - `gm:profile:` — user profile and wallet/account totals. - `gm:record::` — deposit, withdrawal, plan, and raffle records. - `gm:deletedUser:` — marker preventing a deleted account from being recreated on future sign-in. - `gm:raffle:config` — globally shared raffle configuration. **Important:** KV access and admin behavior run in the browser. Do not treat this implementation as secure financial infrastructure. Any real-money launch requires a protected backend, server-side authorization, payment verification, audit logs, rate limiting, and immutable financial ledger logic. ## File Structure ```text index.html # HTML shell, metadata, and injected GenMB Auth/KV SDK. src/ ├── main.tsx # React entry point; wraps App in StrictMode and HashRouter. ├── App.tsx # Main application: auth, routes, KV persistence, pages, dialogs, admin UI. ├── components/ │ ├── MinerMachine.tsx # Animated plan-specific mining machine using CSS custom accent color. │ ├── WolfMark.tsx # Reusable CSS wolf logo and GOLD MINE BITCOIN wordmark. │ └── ui.tsx # Shared Button, accessible Dialog, and toast notification renderer. ├── data/ │ └── plans.ts # Canonical investment plans, special offers, and referral-bonus calculation. ├── lib/ │ └── utils.ts # `cn`, USD formatter, and short date formatter. ├── styles/ │ └── main.css # Tailwind theme tokens, wolf/machine visuals, animation, layout utilities. └── types/ └── genmb.d.ts # Global TypeScript declarations for injected `window.genmb` SDK. ``` ## Key Features ### Authentication and Account Provisioning - Authentication UI in `src/App.tsx` supports: - Google sign-in - email/password sign-in - sign-up followed by OTP verification - email magic-link sign-in - password reset and confirmation - On first authenticated load, `ensureProfile()` creates a `Profile` in KV. - Deactivated accounts do not load their dashboard data. - Deleted users are blocked through `gm:deletedUser:`. - `Profile` fields include wallet and summary totals, active status, optional active plan, and creation timestamp. ### Mining Plans and Machines - Canonical plans live in `src/data/plans.ts`. - All standard plans are 30-day virtual mining plans, from Micro ($5 / $0.55 daily) through Ultimate ($10,000 / $1,500 daily). - Plan data includes: ```ts type Plan = { id: string name: string investment: number daily: number accent: string machine: string } ``` - Plan activation creates/stores an `ActivePlan` on the user profile and records a `plan` transaction. - A user’s displayed miner uses `MinerMachine` with the plan’s `accent` color and name. - `MinerMachine` is a stylized CSS 3D illustration, not WebGL/Three.js: - fan icons continuously rotate - LEDs and cooling indicators pulse - every machine includes the compact `WolfMark` - inactive machines render as `STANDBY`; active machines render as `HASHING` - Special offers are display data in `specialOffers`; they are not represented as purchasable `Plan` objects. ### Wallet, Deposits, and Withdrawals - Wallet views show available balance and profile totals for deposits, withdrawals, earnings, and referral earnings. - Deposit requests support JazzCash, Easypaisa, and Binance using the hard-coded payment details in `App.tsx`. - Deposit workflow captures method, USD amount, transaction ID, and an uploaded screenshot reference, then creates a `pending` `deposit` record. - Deposit rate is presented as **312 PKR = $1 USD**. - Withdrawal workflow creates a `pending` `withdrawal` record with selected method and payment details. - Withdrawals are only allowed when `isWithdrawalOpen()` returns true: Friday, Saturday, or Sunday according to the browser’s local time. - Withdrawal rate is presented as **270 PKR = $1 USD**. - Admin approval/rejection updates record status and adjusts profile totals/wallet as implemented in `App.tsx`. ### Referrals and Bonuses - Referral views expose a user-specific referral link and referral statistics. - `referralBonus(investment)` in `src/data/plans.ts` encodes the exception rules: - $5 plan → $0.55 - $10 plan → $2.00 - all other plans → 10% of investment - Keep referral payout rules centralized in this function; do not duplicate the calculation in page UI. ### Raffle Bonus - The raffle page displays the current raffle title, reward, eligible plans, and closing date. - Default configuration is `defaultRaffle` in `src/App.tsx`. - Admin can update shared raffle settings persisted at `gm:raffle:config`. - Raffle activity uses `RecordItem` entries with `type: 'raffle'`, making it visible in account transaction history. ### Transactions and Admin - `RecordItem` is the shared transaction/activity model: ```ts type RecordItem = { id: string userId: string type: 'deposit' | 'withdrawal' | 'plan' | 'raffle' amount: number status: 'pending' | 'approved' | 'rejected' | 'completed' method?: string transactionId?: string screenshot?: string createdAt: string details?: string } ``` - User transaction history is loaded with `window.genmb.kv.list('gm:record::')` and sorted newest first. - The admin route provides operational views for user/account and payment request review, activity, raffle administration, and summary reporting. - Admin actions must preserve record status semantics: - requests begin as `pending` - admin decisions resolve to `approved` or `rejected` - finalized informational activity may use `completed` ## Design Guidelines - Visual direction: dark premium operations console with black/navy surfaces, metallic gold highlights, and neon-blue technical glow. - Core theme values are defined in `src/styles/main.css`: - background: `#070a10` - cards: `#101620` - gold primary: `#efb937` - neon-blue focus ring: `#2dc8ff` - muted slate text: `#94a3b8` - destructive red: `#f05252` - Use Tailwind semantic utilities (`bg-card`, `text-muted-foreground`, `border-border`, `bg-primary`) instead of introducing arbitrary repeated colors. - Typography: - UI text: Inter/system sans stack. - Premium display headings and brand lockup: Georgia / Times New Roman through `.font-display`. - The wolf mark is CSS-drawn in `.wolf-mark`; reuse `WolfMark` rather than replacing it with emoji or a new logo asset. - Mining machine accents must come from the plan’s `accent` value via the `--machine-accent` custom property. - Maintain the existing visual effects: grid noise, restrained radial glows, gold shadows, blue LEDs, and animated fans. - Responsive behavior: - minimum viewport width is 320px. - sidebar navigation is controlled by `sidebarOpen` for compact layouts. - dialogs constrain content to `max-h-[75vh]` and scroll internally. - do not assume hover-only interactions; all actions must remain reachable on touch devices. ## App Flow 1. Visitor opens the app and completes one of the authentication flows. 2. The app waits for `window.genmb.auth.ready()`, observes auth changes, and creates/loads the user profile. 3. Authenticated users land in the dashboard and can navigate to: - Dashboard - Mining Plans - Wallet - Referrals - Raffle Bonus - Transactions - Settings - Admin Console, when available 4. A user deposits funds by selecting a method, entering payment information, and submitting a pending request. 5. After an approved deposit increases wallet funds, the user can activate a plan; its machine is shown as running until plan expiry. 6. Users may submit withdrawals only on Fri–Sun. Attempts outside the window must show a clear rejection message rather than create a record. 7. Users can copy/share their referral link and review earnings/activity. 8. Admin reviews pending requests and raffle configuration; affected user data must be reloaded or updated after a decision. 9. Sign-out clears app session state and returns to authentication. ### Edge Cases - Never assume a KV value has the expected shape; cast carefully and preserve existing data when editing profiles or records. - A deleted/deactivated user must not receive a new active profile automatically. - `Date.getDay()` is local-device time; withdrawal eligibility may differ by timezone. Use a backend-defined timezone before production. - Hash routes are required because `src/main.tsx` uses `HashRouter`; do not switch to path routing without deployment rewrite support. - Screenshot handling is prototype-level KV data, not secure file storage. ## Conventions - Use TypeScript function components and named local types near their owner when a model is only used by `App.tsx`. - Keep reusable cross-view data in `src/data/`; `plans.ts` is the single source of truth for plan pricing, returns, machine labels, colors, and referral math. - Use `money()` and `shortDate()` from `src/lib/utils.ts` for consistent formatting. - Combine Tailwind classes with `cn()` from `src/lib/utils.ts`; it resolves conflicting Tailwind utilities via `tailwind-merge`. - Use the shared `Button` component for primary actions so loading, disabled, focus, and motion behavior stay consistent. - Use `Dialog` for modal flows. It already handles Escape, backdrop close, focus restoration, focus cycling, and body-scroll locking. - Use `notify()` / `Toaster` patterns in `App.tsx` for mutation feedback; errors should describe what the user can do next. - KV writes should follow the established naming convention: `gm:::` for user-owned entities and `gm::` for global config. ### Adding a New Page or Feature 1. Add the route/page identifier to the `Page` union in `src/App.tsx`. 2. Add its title and description in `pageMeta()`. 3. Add a navigation item and a matching `Route` in `App.tsx`. 4. Define persistent models and KV key conventions before implementing UI. 5. Put static catalog/configuration data in `src/data/`, not inline in multiple components. 6. Reuse `WolfMark`, `MinerMachine`, `Button`, `Dialog`, and semantic theme classes where applicable. 7. Ensure mobile navigation closes after route selection and every async mutation has loading and error feedback. ## Platform (GenMB) This app is built and hosted on GenMB. **Runtime:** Browser sandbox (iframe) or Cloud Run. No Node.js server — all code runs client-side unless `backend/` exists. **Dependencies:** CDN-only (esm.sh, cdn.tailwindcss.com, unpkg). Use ES module imports with full CDN URLs. No `npm install` at runtime. **Entry point:** `index.html` must include all CDN script tags. Tailwind via CDN with inline config. **Built-in services (relative API paths only, never hardcode domains):** - `/api/ai/completion` — AI proxy | `/api/data/{appId}/*` — PostgreSQL (DataConnect SDK) - `/api/storage/{appId}/*` — File uploads (GCS) | `/api/auth/google/*` — Google OAuth - `/api/contact/submit` — Contact form | SDKs: `window.genmb.db`, `.storage`, `.auth` **File structure:** `index.html` (entry), `src/` (source), `styles/` (CSS), `backend/` (optional FastAPI), `CLAUDE.md` (this file). **Cannot:** Install npm packages at runtime, access filesystem, make direct server-side calls from frontend, modify infra.