Invoicing App

🎯 Key Features

• 👥
  Customer Management - Create, read, update, delete customers with EU VAT ID validation
• 📄
  Invoice Generation - Dynamic invoice creation with line items, tax calculations, and automatic numbering
• 📊
  Data Persistence - JSON-based file storage with concurrent access handling via SemaphoreSlim
• 🖨️
  PDF Export - Professional invoice PDFs generated server-side using QuestPDF library
• 🔐
  Validation & Error Handling - Comprehensive input validation and graceful error responses
• 🤖
  MCP Server - Model Context Protocol integration for AI-driven operations and complete LLM tool support

🏗️ Architecture

Project Structure

Built with three core projects in a single .NET Aspire solution:

Data Model

• Customer - Company/individual information with EU VAT ID
• Invoice - Header with customer reference, dates, and totals
• InvoiceLine - Line items with project reference, category, date range, amount, and tax rate
• SenderInfo - Configurable company details for invoice header (logo, address, bank info)

API Endpoints

• GET/POST /api/customers - Customer CRUD operations
• GET/POST /api/invoices - Invoice CRUD operations
• GET /api/invoices/{id}/pdf - Generate and download invoice PDF
• GET /api/config/sender-info - Retrieve sender configuration

💡 Technology Stack

🚀 Implementation Highlights

Cloud-Native with .NET Aspire

• Service discovery for seamless API-to-Web communication
• Modern distributed application patterns
• Ready for Azure Container Apps deployment
• Built-in observability and monitoring hooks

Data Persistence Strategy

• JSON files as single source of truth
• Organized structure: db/customers.json and db/invoices/
• Concurrent access protection using SemaphoreSlim
• Automatic backup-friendly file format
• No external database dependencies

PDF Generation

• QuestPDF library for professional invoice layouts
• Server-side rendering ensures consistency
• Configurable sender information in JSON
• Logo and branding integration support
• Real-time PDF generation on demand

AI Integration via MCP

• Complete Model Context Protocol server implementation
• Enable Claude, ChatGPT, and other LLMs to manage invoices
• Natural language commands for business operations
• Example: "Create invoice for Acme Corp with 3 line items totaling €1500"
• Seamless tool integration in AI conversations

Interactive Blazor UI

• Responsive design for mobile and desktop
• Real-time form validation
• Interactive Server render mode for optimal performance
• Customer and Invoice CRUD interfaces
• One-click PDF export functionality

🔄 Development Process

This project demonstrates a complete, real-world development workflow:

💼 Use Cases

Freelancer/Small Business

• Manage client list with EU tax compliance
• Generate professional invoices quickly
• Export PDFs for email or printing
• JSON files for easy backup/archiving

AI-Powered Assistant

• Delegate invoicing to Claude via MCP
• Natural language commands: "Generate monthly invoices for all active customers"
• Automate routine tasks without manual UI interaction
• Keep conversations in context with LLM

Enterprise Integration

• REST API for third-party integration
• Deploy on Azure Container Apps with Aspire
• Scale microservices as needed
• Integrate with larger business systems

Learning & Demonstration

• Complete example of .NET 10 & Aspire best practices
• Blazor interactive component patterns
• JSON persistence strategy implementation
• MCP server development reference

📚 Project Status

This is a complete, production-ready application that has been architected, implemented, and refined. The codebase serves as an excellent reference for:

• How to structure a .NET 10 Aspire application
• Building MCP servers for LLM integration
• Creating professional business applications
• Implementing JSON-based persistence patterns
• Building interactive Blazor interfaces