littleshop/README.md

LittleShop API

A basic online sales system backend built with ASP.NET Core 9.0, featuring multi-cryptocurrency payment support via BTCPay Server.

Features

Admin Panel

• Authentication: JWT-based authentication for admin users
• Categories: Full CRUD operations for product categories
• Products: Complete product management with image upload support
• Users: Staff user management (username/password only)
• Orders: Order management with status tracking
• Accounting: Dashboard and financial overview

Public API

• Catalog: Public product and category browsing
• Orders: Order creation and management by client identity reference
• Payments: Multi-cryptocurrency payment processing
• Tracking: Order status and tracking

Cryptocurrency Support

• BTC (Bitcoin) + Lightning Network
• XMR (Monero) - Privacy coin
• USDT (Tether) - Stablecoin
• LTC (Litecoin)
• ETH (Ethereum)
• ZEC (Zcash) - Privacy coin
• DASH (Dash)
• DOGE (Dogecoin)

Getting Started

Prerequisites

• .NET 9.0 SDK
• SQLite (included)
• BTCPay Server instance (for production)

Configuration

Update appsettings.json with your settings:

{
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=littleshop.db"
  },
  "Jwt": {
    "Key": "YourSuperSecretKeyThatIsAtLeast32CharactersLong!",
    "Issuer": "LittleShop",
    "Audience": "LittleShop",
    "ExpiryInHours": 24
  },
  "BTCPayServer": {
    "BaseUrl": "https://your-btcpay-server.com",
    "ApiKey": "your-api-key",
    "StoreId": "your-store-id",
    "WebhookSecret": "your-webhook-secret"
  }
}

Running the Application

1. Clone and build:

   dotnet restore
   dotnet build
   

2. Run:

   dotnet run
   

3. Access:

   • API: https://localhost:5001
   • Swagger UI: https://localhost:5001/swagger

Default Admin User

• Username: admin
• Password: admin

API Endpoints

Authentication

• POST /api/auth/login - Login (get JWT token)
• GET /api/auth/users - List users (admin)
• POST /api/auth/users - Create user (admin)

Categories

• GET /api/categories - List categories
• POST /api/categories - Create category (admin)
• PUT /api/categories/{id} - Update category (admin)
• DELETE /api/categories/{id} - Delete category (admin)

Products

• GET /api/products - List products
• GET /api/products?categoryId={id} - Products by category
• POST /api/products - Create product (admin)
• POST /api/products/{id}/photos - Upload product photo (admin)

Public Catalog

• GET /api/catalog/categories - Public category list
• GET /api/catalog/products - Public product list

Orders

• POST /api/orders - Create order
• GET /api/orders/by-identity/{identity} - Get orders by identity
• POST /api/orders/{id}/payments - Create crypto payment
• GET /api/orders/{id}/payments - Get order payments
• POST /api/orders/{id}/cancel - Cancel order

Admin Order Management

• GET /api/orders - List all orders (admin)
• PUT /api/orders/{id}/status - Update order status (admin)

Product Weight Units

• Unit (0) - Generic unit
• Micrograms (1)
• Grams (2)
• Ounces (3)
• Pounds (4)
• Millilitres (5)
• Litres (6)

Order Statuses

• PendingPayment (0) - Awaiting payment
• PaymentReceived (1) - Payment confirmed
• Processing (2) - Being processed
• PickingAndPacking (3) - Preparing for shipment
• Shipped (4) - Shipped with tracking
• Delivered (5) - Delivered
• Cancelled (6) - Cancelled
• Refunded (7) - Refunded

Payment Workflow

1. Customer creates order via API
2. Order receives unique ID and pending status
3. Customer requests payment in preferred cryptocurrency
4. System generates unique wallet address and amount
5. Customer sends payment to provided address
6. BTCPay Server detects payment and triggers webhook
7. Order status updates to PaymentReceived
8. Admin processes order through picking & packing
9. Shipping label generated via Royal Mail API
10. Customer receives tracking information

Security Features

• JWT authentication for admin endpoints
• Password hashing with PBKDF2
• No customer personal data stored (identity reference only)
• Self-hosted payment processing (no third-party data sharing)
• CORS configuration for web clients

Logging

• Structured logging with Serilog
• Console and file output
• Request/response logging
• Payment processing audit trail

Development

The API is built with:

• ASP.NET Core 9.0 - Web framework
• Entity Framework Core - Database ORM
• SQLite - Database
• JWT - Authentication
• AutoMapper - Object mapping
• FluentValidation - Input validation
• Serilog - Logging
• Swagger - API documentation
• BTCPay Server Client - Crypto payments

Privacy & Compliance

• No KYC requirements
• No customer personal data retention
• Privacy-focused cryptocurrencies supported (XMR, ZEC)
• Self-hosted payment processing
• GDPR-friendly design (minimal data collection)

Development Roadmap

See ROADMAP.md for detailed development plans, including:

• 🚨 Critical security fixes (immediate priority)
• 📋 Production readiness improvements
• 🚀 Feature enhancements (shipping, notifications, analytics)
• 🏗️ Long-term scalability and optimization plans

Recent Updates

• Security vulnerabilities identified and documented (Sep 19, 2025)
• BTCPay Server integration fixed with production credentials (Sep 19, 2025)
• Product variations and mobile workflow implemented (Sep 18, 2025)