BCards/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

BCards is a professional LinkTree clone built in ASP.NET Core MVC, targeting Brazilian and Spanish markets. It provides hierarchical URLs organized by business categories (/page/{category}/{slug}), integrated Stripe payments, and a sophisticated moderation system with preview tokens.

Development Commands

Build & Run

# Quick clean build (RECOMMENDED after VS 2022 updates)
./clean-build.sh

# Manual process:
dotnet restore
dotnet build

# Run development server
cd src/BCards.Web
dotnet run
# Access: https://localhost:49178

# Run with Docker
docker-compose up -d
# Access: http://localhost:8080

🚨 Known Issues After VS 2022 Updates

Problem: After VS 2022 updates, build cache gets corrupted causing:

• OAuth login failures (especially Google in Edge browser)
• Need for constant clean/rebuild cycles
• NuGet package resolution errors

Solution: Use the automated cleanup script:

./clean-build.sh

Google OAuth Edge Issue: If Google login shows "browser not secure" error:

1. Clear browser data for localhost:49178 and accounts.google.com
2. Test in incognito/private mode
3. Use Vivaldi or Chrome (Edge has known compatibility issues)

Testing

# Run all tests
dotnet test

# Run tests with coverage
dotnet test --collect:"XPlat Code Coverage"

# Run specific test
dotnet test --filter "TestClassName"

Architecture Overview

Technology Stack

• Framework: ASP.NET Core MVC (.NET 8)
• Database: MongoDB 7.0 with MongoDB.Driver 2.25.0
• Authentication: OAuth 2.0 (Google + Microsoft)
• Payments: Stripe.NET 44.7.0
• Frontend: Bootstrap 5.3.2, jQuery 3.7.1, vanilla JavaScript
• Email: SendGrid 9.29.3
• Containerization: Docker + Docker Compose

Core Architecture Patterns

• MVC Pattern: Controllers handle HTTP requests, Views render UI, Models represent data
• Repository Pattern: Data access abstraction via IUserPageRepository, ICategoryRepository, etc.
• Service Layer: Business logic encapsulation (IUserPageService, IModerationService, etc.)
• Dependency Injection: Built-in ASP.NET Core DI container
• Domain-Driven Design: Rich domain models with business logic

Key Business Logic

Page Status System

Pages follow this lifecycle with explicit numeric enum values:

• Creating = 6: Development phase, requires preview tokens
• PendingModeration = 4: Submitted for approval, requires preview tokens
• Rejected = 5: Failed moderation, requires preview tokens
• Active = 0: Live and publicly accessible
• Inactive = 3: Paused by user
• Expired = 1: Trial expired, redirects to pricing
• PendingPayment = 2: Payment overdue, shows warning

Moderation System

• Content approval workflow with attempts tracking
• Preview tokens with 4-hour expiration for non-Active pages
• Email notifications for status changes
• Automatic status transitions based on user actions

Pricing Strategy

Three-tier system with psychological pricing (decoy effect):

• Basic (R$ 9.90/mês): 5 links, basic themes
• Professional (R$ 24.90/mês): 15 links, all themes - DECOY
• Premium (R$ 29.90/mês): Unlimited links, custom themes

Project Structure

src/BCards.Web/
├── Controllers/           # MVC Controllers (9 total)
│   ├── AdminController    # User dashboard and page management
│   ├── AuthController     # OAuth authentication
│   ├── HomeController     # Public pages and landing
│   ├── PaymentController  # Stripe integration
│   ├── ModerationController # Content approval system
│   └── UserPageController # Public page display
├── Models/               # Domain entities (12 total)
│   ├── User              # Authentication and subscriptions
│   ├── UserPage          # Main business card entity
│   ├── LinkItem          # Individual links with analytics
│   └── Category          # Business categories
├── Services/             # Business logic (20 services)
│   ├── IUserPageService  # Core page operations
│   ├── IModerationService # Content approval
│   ├── IAuthService      # Authentication
│   └── IPaymentService   # Stripe integration
├── Repositories/         # Data access (8 repositories)
├── ViewModels/          # View-specific models
├── Middleware/          # Custom middleware (4 pieces)
│   ├── PageStatusMiddleware    # Handles page access by status
│   ├── ModerationAuthMiddleware # Admin access control
│   └── PreviewTokenMiddleware  # Preview token validation
└── Views/               # Razor templates with Bootstrap 5

Database Design (MongoDB)

Core Collections

• users: Authentication, subscription status, Stripe customer data
• userpages: Business cards with status, links, themes, moderation history
• categories: Business categories with SEO metadata
• subscriptions: Stripe subscription tracking

Important Indexes

• Compound: {category: 1, slug: 1} for page lookups
• User pages: {userId: 1, status: 1} for dashboard filtering
• Active pages: {status: 1, category: 1} for public listings

Key Features Implementation

Preview Token System

Non-Active pages require preview tokens for access:

// Generate fresh token (4-hour expiry)
POST /Admin/GeneratePreviewToken/{id}

// Access page with token
GET /page/{category}/{slug}?preview={token}

OAuth Integration

Supports Google and Microsoft OAuth with automatic user creation and session management.

Stripe Payment Flow

Complete subscription lifecycle:

1. Checkout session creation
2. Webhook handling for events
3. Subscription status updates
4. Plan limitation enforcement

Dynamic Theming

CSS generation system with customizable colors, backgrounds, and layouts based on user's plan limitations.

Configuration

Required Environment Variables

{
  "MongoDb": {
    "ConnectionString": "mongodb://localhost:27017",
    "DatabaseName": "BCardsDB"
  },
  "Stripe": {
    "PublishableKey": "pk_test_...",
    "SecretKey": "sk_test_...",
    "WebhookSecret": "whsec_..."
  },
  "Authentication": {
    "Google": { "ClientId": "...", "ClientSecret": "..." },
    "Microsoft": { "ClientId": "...", "ClientSecret": "..." }
  }
}

Development Setup

1. Install .NET 8 SDK, MongoDB 4.4+
2. Configure OAuth credentials (Google Cloud Console, Azure Portal)
3. Set up Stripe account with test keys
4. Configure webhook endpoints for /webhook/stripe

Important Implementation Notes

Page Status Middleware

PageStatusMiddleware intercepts all /page/{category}/{slug} requests and enforces access rules based on page status. Non-Active pages require valid preview tokens.

Moderation Workflow

1. Pages start as Creating status
2. Users click "Submit for Moderation" → PendingModeration
3. Moderators approve/reject → Active or Rejected
4. Rejected pages can be edited and resubmitted

Preview Token Security

• Tokens expire after 4 hours
• Generated on-demand via AJAX calls
• Required for Creating, PendingModeration, and Rejected pages
• Validated by middleware before page access

Plan Limitations

Enforced throughout the application:

• Link count limits per plan
• Theme availability restrictions
• Analytics access control
• Page creation limits

Common Development Patterns

Repository Usage

var page = await _userPageService.GetPageByIdAsync(id);
await _userPageService.UpdatePageAsync(page);

Service Layer Pattern

Business logic resides in services, not controllers:

public class UserPageService : IUserPageService
{
    private readonly IUserPageRepository _repository;
    // Implementation with business rules
}

Status-Based Logic

Always check page status before operations:

if (page.Status == PageStatus.Creating || page.Status == PageStatus.Rejected)
{
    // Allow editing
}

This architecture supports a production-ready SaaS application with complex business rules, payment integration, and content moderation workflows.