metatron-open-seo/docs/CHANGELOG_2026_10_17.md

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.