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
```bash
# Restore dependencies
dotnet restore

# Build solution
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
```

### Testing
```bash
# 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:
```csharp
// 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
```json
{
  "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
```csharp
var page = await _userPageService.GetPageByIdAsync(id);
await _userPageService.UpdatePageAsync(page);
```

### Service Layer Pattern
Business logic resides in services, not controllers:
```csharp
public class UserPageService : IUserPageService
{
    private readonly IUserPageRepository _repository;
    // Implementation with business rules
}
```

### Status-Based Logic
Always check page status before operations:
```csharp
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.