114 lines
8.0 KiB
Markdown
114 lines
8.0 KiB
Markdown
# Comprehensive Project Changes Documentation (October 17, 2026)
|
|
|
|
This document details all modules, architecture updates, file changes, and bug fixes implemented today in the **CrawlerX (MetatronCube)** project.
|
|
|
|
---
|
|
|
|
## 1. Executive Summary of Work Done
|
|
|
|
Today's work centered on three major functional modules while strictly preserving all previous SEO tools, crawlers, ranking engines, and core business logic:
|
|
|
|
1. **Authentication & Password Management System**: Full branded auth suite (Sign-in, Sign-up, Forgot Password, Reset Password, and In-App Change Password) with secure session handling via BetterAuth.
|
|
2. **Direct Stripe Subscription & Billing Module**: Complete multi-tier pricing architecture (Free, Starter, Pro, Agency in INR & USD), Public Pricing Page (`/pricing`), In-App Subscription Hub (`/subscribe`), Stripe Checkout session generator, Webhook listener, and SQLite/Postgres synchronization.
|
|
3. **Active Plan Status, Expiry Countdown & Renewal System**: Real-time days and hours remaining countdown timer, target renewal/expiry date calculation, 1-Click Renew Plan interactive dialog with Monthly/Annual toggles, and Stripe Customer Portal integration.
|
|
4. **Dashboard Stability & Runtime Environment Fixes**: Resolved the `["dashboardActivation"] data is undefined` error by decoupling Autumn SaaS dependencies from self-hosted direct Stripe mode, and resolved the `DataForSEO setup` warning banner by enabling universal runtime environment variable resolution across Vite dev and Cloudflare runtimes.
|
|
|
|
---
|
|
|
|
## 2. Module 1: Authentication & User Management
|
|
|
|
### Key Capabilities
|
|
* **Full Brand Aesthetics**: 3D cube illustration background, fluid wave accents, and theme colors (`#0f1d34`, `#3779b9`).
|
|
* **Route Coverage**:
|
|
* `/sign-in`: Secure email and password login with session persistence.
|
|
* `/sign-up`: Account registration with validation.
|
|
* `/forgot-password`: Password reset request with secure email token dispatch.
|
|
* `/reset-password`: Token-based credential recovery.
|
|
* `/change-password`: Direct credential update from navigation and within the Settings dashboard.
|
|
* **Security & Session Handling**: Integrated with `BetterAuth` using HTTP-only cookies and Bearer tokens for Cloudflare Workers / Node.js runtime compatibility.
|
|
|
|
### Modified & Created Files
|
|
* `src/lib/auth.ts`: BetterAuth server configuration, password reset plugin, and email sender.
|
|
* `src/client/features/auth/AuthPage.tsx`: Split-screen layout shell with responsive mobile view and brand assets.
|
|
* `src/client/features/settings/ChangePasswordSection.tsx`: In-app password change form for the Settings page.
|
|
* `src/routes/_auth.sign-in.tsx`, `_auth.sign-up.tsx`, `_auth.tsx`: Authentication page routes.
|
|
* `src/routes/forgot-password.tsx`, `reset-password.tsx`, `change-password.tsx`: Password recovery workflows.
|
|
|
|
---
|
|
|
|
## 3. Module 2: Stripe Subscription & Billing Engine
|
|
|
|
### Pricing Architecture
|
|
Implemented 4 clearly differentiated tiers defined in `src/client/features/billing/PricingData.ts`:
|
|
|
|
| Tier | Price (Monthly / Annual) | Capacity & Key Limits | Key Feature Highlights |
|
|
| :--- | :--- | :--- | :--- |
|
|
| **Free** | ₹0 / $0 | 1 Site, 100 pages/audit | Basic crawl audit, 10 tracked keywords |
|
|
| **Starter** | ₹999/mo (₹829/mo annual) / $29 | 3 Sites, 1,000 pages/audit | 100 tracked keywords, AI Fix Engine (titles/metas), 40 AI visibility checks |
|
|
| **Pro** | ₹2,499/mo (₹2,099/mo annual) / $79 | 10 Sites, 3,000 pages/audit | 300 tracked keywords, 1-Click CMS sync (WordPress & Shopify), White-label PDF reports |
|
|
| **Agency** | ₹7,499/mo (₹6,249/mo annual) / $249 | 30 Sites, 5,000 pages/audit | 1,000 tracked keywords, Public API & MCP Server access (Claude/ChatGPT), Scheduled WhatsApp & Email reports |
|
|
|
|
### Key Capabilities
|
|
* **Dual Currency Support**: Instant client-side switching between **INR (₹)** and **USD ($)**.
|
|
* **Billing Intervals**: Monthly and Annual (with 17% discount applied).
|
|
* **7-Day Free Trial**: Annual checkout sessions automatically attach a 7-day trial with card authorization.
|
|
* **Public Pricing Page (`/pricing`)**: Dedicated marketing landing page for prospective customers.
|
|
* **In-App Subscription (`/subscribe`)**: Unified subscriber experience with workspace capacity indicators.
|
|
* **Direct Stripe Integration**:
|
|
* `createStripeCheckoutSession`: Generates Stripe Checkout sessions with line items, metadata, and auto-redirects.
|
|
* `verifyStripeCheckoutSession`: Verifies session completion upon redirect, syncing status to the database.
|
|
* `src/routes/api/stripe/webhook.ts`: Handles Stripe webhook events (`checkout.session.completed`, `customer.subscription.updated`, `customer.subscription.deleted`).
|
|
* `src/server/billing/stripe-sync.ts`: Persists subscription status into `billing_customer_status`.
|
|
|
|
---
|
|
|
|
## 4. Module 3: Active Plan Countdown & Renewal System
|
|
|
|
### Key Capabilities
|
|
* **Real-Time Days & Hours Countdown**:
|
|
* Extracts Stripe subscription period (`sub.items.data[0].current_period_end` or `sub.current_period_end`).
|
|
* Calculates remaining time down to the exact days and hours (e.g., `6 days, 22 hours remaining`).
|
|
* Shows exact calendar renewal or trial expiration date (e.g., `Trial ends: Oct 24, 2026`).
|
|
* Displays a visual progress bar indicating elapsed vs remaining time in the current cycle.
|
|
* **Interactive Plan Renewal Dialog**:
|
|
* Clicking **"Renew Plan"** opens a dedicated modal with the user's active plan details.
|
|
* Select between **Monthly Renewal** (`₹999/mo`) and **Annual Renewal** (`₹829/mo` with 17% discount).
|
|
* **Proceed to Renew** instantly initiates a Stripe Checkout session to extend the subscription.
|
|
* **Stripe Customer Portal**:
|
|
* **"Manage Billing & Invoices"** button allows users to download receipts, view tax invoices, and manage payment methods.
|
|
* **Clean Code Structure**:
|
|
* Extracted `src/client/features/billing/ActivePlanStatusBanner.tsx` (371 lines).
|
|
* Extracted `src/client/features/billing/SubscribeAccountMenu.tsx` (51 lines).
|
|
* Kept `src/routes/_authenticated.subscribe.tsx` strictly under 400 lines (387 lines).
|
|
|
|
---
|
|
|
|
## 5. Module 4: Bug Fixes & Architectural Bridges
|
|
|
|
### 1. Dashboard Red Error: `["dashboardActivation"] data is undefined`
|
|
* **Root Cause**: The legacy codebase assumed `AUTH_MODE=hosted` always used the third-party Autumn SaaS metering service. Without `AUTUMN_SECRET_KEY`, `getDashboardActivation` crashed.
|
|
* **Resolution**: Added a graceful compatibility bridge in `src/server/billing/subscription.ts` and `src/server/lib/dataforseo/client.ts`. When `AUTUMN_SECRET_KEY` is not provided, the application falls back safely to Direct Stripe status stored in `billing_customer_status`.
|
|
|
|
### 2. Blue Setup Banner: `We could not verify your DataForSEO setup`
|
|
* **Root Cause**: `getSeoApiKeyStatus` was inspecting `env.DATAFORSEO_API_KEY` directly from `cloudflare:workers`, which is undefined in Node.js/Vite development mode.
|
|
* **Resolution**: Replaced with `await getOptionalEnvValue("DATAFORSEO_API_KEY")`, which works seamlessly across local Vite and deployed Cloudflare Workers.
|
|
|
|
---
|
|
|
|
## 6. Commit History Summary (October 17, 2026)
|
|
|
|
| Commit Hash | Commit Message | Files Changed | Summary of Impact |
|
|
| :--- | :--- | :--- | :--- |
|
|
| `5ae39eb` | `add authentication routes, components, and styling for CrawlerX app` | 17 files | Full auth suite: sign-in, sign-up, reset password, change password, BetterAuth config. |
|
|
| `df5f593` | `add billing and subscription management system with Stripe integration` | 21 files | Stripe checkout, webhooks, `/pricing`, `/subscribe`, PRD docs, and Autumn bridge fallback. |
|
|
| `5d5484c` | `add subscription billing flow and Stripe integration components` | 5 files | Active plan days/hours countdown banner, renewal dialog, and portal session integration. |
|
|
|
|
---
|
|
|
|
## 7. Compliance & Quality Assurance Checks
|
|
|
|
* **Pre-existing Core Logic**: Zero modification to SEO audit engines, crawler algorithms, or database schemas.
|
|
* **400-Line Limit**: Every single created and modified file is strictly under 400 lines.
|
|
* **Linter**: `pnpm exec oxlint` completed with **0 warnings and 0 errors**.
|
|
* **Browser Validation**: Fully tested on `http://localhost:3001` with visual screenshots verifying clean rendering.
|