littleshop/PROJECT_README.md

# LittleShop E-Commerce Platform

A complete e-commerce platform built with ASP.NET Core 9.0, featuring multi-cryptocurrency payment support and a privacy-focused design.

## 🎯 Features

### Core Functionality
- **Product Management**: Categories, products with photos, weight-based pricing
- **Order Management**: Complete order workflow from creation to delivery
- **Multi-Cryptocurrency Payments**: Bitcoin, Monero, USDT, Litecoin, Ethereum, Zcash, Dash, Dogecoin
- **Shipping Management**: Weight-based shipping rates with Royal Mail integration
- **Admin Panel**: Full administrative interface for managing the store
- **API**: RESTful API with JWT authentication for client applications

### Security & Privacy
- **No KYC Requirements**: Privacy-focused design with minimal data collection
- **Dual Authentication**: Cookie-based for admin panel, JWT for API
- **Self-Hosted Payments**: BTCPay Server integration for cryptocurrency processing
- **Secure Password Storage**: PBKDF2 with 100,000 iterations

## 🚀 Quick Start

### Prerequisites
- .NET 9.0 SDK
- SQLite (included)
- BTCPay Server instance (for payments)

### Installation

1. Clone the repository:
```bash
git clone https://github.com/yourusername/littleshop.git
cd littleshop
```

2. Restore dependencies:
```bash
dotnet restore
```

3. Run the application:
```bash
dotnet run --project LittleShop/LittleShop.csproj
```

4. Access the application:
   - Admin Panel: https://localhost:5001/Admin
   - API Documentation: https://localhost:5001/swagger
   - Default credentials: `admin` / `admin`

## 📁 Project Structure

```
LittleShop/
├── LittleShop/                 # Main web application
│   ├── Areas/Admin/           # Admin panel MVC
│   ├── Controllers/           # API controllers
│   ├── Services/              # Business logic
│   ├── Models/                # Database entities
│   ├── DTOs/                  # Data transfer objects
│   └── Data/                  # Entity Framework context
├── LittleShop.Client/         # .NET client SDK
│   ├── Services/              # API client services
│   ├── Models/                # Client models
│   └── Http/                  # HTTP handlers
└── LittleShop.Tests/          # Test suite
    ├── Unit/                  # Unit tests
    ├── Integration/           # API integration tests
    ├── Security/              # Security tests
    └── UI/                    # UI automation tests
```

## 💻 Using the Client SDK

### Installation
```bash
dotnet add reference LittleShop.Client/LittleShop.Client.csproj
```

### Basic Usage
```csharp
using LittleShop.Client.Extensions;

// Configure services
services.AddLittleShopClient(options =>
{
    options.BaseUrl = "https://localhost:5001";
    options.TimeoutSeconds = 30;
    options.MaxRetryAttempts = 3;
});

// Use the client
var client = serviceProvider.GetRequiredService<ILittleShopClient>();

// Authenticate
await client.Authentication.LoginAsync("admin", "admin");

// Get products
var products = await client.Catalog.GetProductsAsync();

// Create order
var order = await client.Orders.CreateOrderAsync(new CreateOrderRequest
{
    IdentityReference = "CUST001",
    ShippingName = "John Doe",
    ShippingAddress = "123 Main St",
    ShippingCity = "London",
    ShippingPostCode = "SW1A 1AA",
    ShippingCountry = "United Kingdom",
    Items = new[] { new CreateOrderItem { ProductId = productId, Quantity = 1 } }
});
```

## 🔌 API Endpoints

### Authentication
- `POST /api/auth/login` - Login with username/password
- `POST /api/auth/refresh` - Refresh JWT token

### Catalog (Requires Authentication)
- `GET /api/catalog/categories` - Get all categories
- `GET /api/catalog/categories/{id}` - Get category by ID
- `GET /api/catalog/products` - Get products with filtering
- `GET /api/catalog/products/{id}` - Get product by ID

### Orders (Requires Authentication)
- `POST /api/orders` - Create new order
- `GET /api/orders/by-identity/{id}` - Get orders by customer identity
- `GET /api/orders/{id}` - Get order by ID
- `POST /api/orders/{id}/payments` - Create crypto payment
- `POST /api/orders/payments/webhook` - BTCPay webhook endpoint

## 🗄️ Database Schema

### Core Tables
- **Users**: Staff/admin accounts only
- **Categories**: Product categories
- **Products**: Product catalog with pricing and weight
- **ProductPhotos**: Product images with sorting
- **Orders**: Customer orders with shipping details
- **OrderItems**: Individual items in orders
- **CryptoPayments**: Cryptocurrency payment records
- **ShippingRates**: Weight-based shipping calculations

## 🧪 Testing

Run all tests:
```bash
dotnet test
```

Run specific test categories:
```bash
# Unit tests only
dotnet test --filter Category=Unit

# Integration tests
dotnet test --filter Category=Integration

# Security tests
dotnet test --filter Category=Security
```

### Test Coverage
- ✅ Unit tests for all services
- ✅ Integration tests for all API endpoints
- ✅ Security tests for authentication enforcement
- ✅ UI automation tests with Playwright

## 🔧 Configuration

### appsettings.json
```json
{
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=littleshop.db"
  },
  "Jwt": {
    "Key": "YourSuperSecretKeyThatIsAtLeast32CharactersLong!",
    "Issuer": "LittleShop",
    "Audience": "LittleShop",
    "ExpiryMinutes": 60
  },
  "BTCPayServer": {
    "Url": "https://your-btcpay.com",
    "StoreId": "your-store-id",
    "ApiKey": "your-api-key"
  }
}
```

## 🚢 Deployment

### Production Checklist
1. Update connection strings
2. Configure BTCPay Server
3. Set strong JWT secret key
4. Enable HTTPS only
5. Configure CORS for your domain
6. Set up SSL certificates
7. Configure logging
8. Set up database backups

### Docker Support
```dockerfile
FROM mcr.microsoft.com/dotnet/aspnet:9.0 AS base
WORKDIR /app
EXPOSE 80 443

FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build
WORKDIR /src
COPY . .
RUN dotnet restore
RUN dotnet build -c Release
RUN dotnet publish -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "LittleShop.dll"]
```

## 📊 Sample Data

The application includes sample data seeder that creates:
- 3 Categories (Electronics, Clothing, Books)
- 5 Products with various prices
- 5 Shipping rates (Royal Mail options)
- 5 Sample orders in different statuses
- 3 Crypto payments demonstrating payment flow

## 🛡️ Security Considerations

- **Authentication Required**: All API endpoints require JWT authentication
- **No Public Endpoints**: Client applications must authenticate first
- **Password Security**: PBKDF2 with salt and 100,000 iterations
- **Input Validation**: FluentValidation on all inputs
- **SQL Injection Protection**: Entity Framework Core with parameterized queries
- **XSS Protection**: Razor view encoding and validation
- **CORS**: Configured for specific domains in production

## 📝 License

This project is proprietary software. All rights reserved.

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

## 📞 Support

For issues, questions, or suggestions:
- Open an issue on GitHub
- Contact: support@littleshop.com

## 🏗️ Built With

- **ASP.NET Core 9.0** - Web framework
- **Entity Framework Core** - ORM
- **SQLite** - Database
- **Bootstrap 5** - UI framework
- **JWT** - API authentication
- **BTCPay Server** - Cryptocurrency payments
- **xUnit** - Testing framework
- **Playwright** - UI automation
- **Serilog** - Logging

## 📈 Version History

- **v1.0.0** - Initial release with core e-commerce functionality
  - Product catalog management
  - Order processing workflow
  - Multi-cryptocurrency payments
  - Admin panel and API
  - Client SDK library
  - Comprehensive test coverage