The Billing Service manages cashiers, invoices, and payment processing within the broader platform. It provides both REST and gRPC APIs for managing billing operations and integrates with other services through event-driven messaging.
This codebase is designed as an app template that mirrors real-world billing department operations*, making it intuitive for junior engineers and non-technical product people to understand - each folder under Billing represents a sub-department with its main activities and processes, categorized as commands or queries. The design focuses on minimal ceremony code, avoiding almost all common tech abstractions, treats infrastructure like office utilities, uses digital representations of what would be "paper" records that can't change themselves but can be modified by external actors, Front office/desk operations are exposed as public sync APIs, and back office operations are supported by async event handlers. The aim was for it to be extremely simple to use and very developer-friendly, however, as a positive, unexpected side effect, the simplicity and real-world mirroring approach also make the codebase naturally LLM-friendly, modern models can easily understand code that follows familiar real-world patterns.
This codebase is intentionally structured to mirror the real-world operations and organizational structure of a billing department. Each part of the code corresponds or should correspond directly to a real-world role or operation, ensuring that the code remains 100% product-oriented and easy to understand. The idea is that main operations/actions would be recognizable by a non-technical product person.
For instance, if the billing department handles creating invoices, the code includes a clear and direct set of actions to handle invoice creation. Smaller tasks, or sub-actions, needed to complete a main action are also represented in a similar manner. If a sub-action is only used within one main action, it remains nested inside that operation. If it needs to be reused by multiple operations, it is extracted and made reusable, but still mirroring the real-world scenario.
This design philosophy avoids unnecessary abstractions. There are no additional layers like repositories or services unless they represent something that exists in the real department. Infrastructure elements like logging or authorization are present as they support the system’s functionality, same as water pipes and electricity support a billing department office. Even the database is viewed as a digital parallel to a real-world archive or filing system.
A key principle is the absence of smart objects. This means that an invoice, for example, is not an object that can change itself. Instead, it is simply treated as a digital record, and all modifications are performed by "external" actors (something is changing the invoice, the invoice does not change itself). This ensures that the code reflects digital representations of real-world entities and processes, rather than trying to replicate objects with their own behaviors.
The codebase also distinguishes between synchronous and asynchronous operations. The API represents the front office of the billing department, handling synchronous operations where immediate responses are expected. In contrast, the back office is represented by asynchronous operations that do not require immediate responses, allowing for efficient, behind-the-scenes processing.
The Billing Service is part of a .NET 9 microservices system built using Domain-Driven Design principles. It provides a complete billing solution with modern web UI and comprehensive testing. It handles:
- Cashier Management: Create and manage cashiers with multi-currency support
- Invoice Processing: Handle invoice lifecycle with Orleans-based stateful processing
- Payment Integration: Process payments and emit integration events
- Cross-Service Integration: React to business events from other services like Accounting
- Modern Web UI: SvelteKit-based responsive web application
- Comprehensive Testing: Unit, integration, and end-to-end testing with real browsers
The solution follows a microservices architecture with shared platform libraries:
.
├── docs/ # DocFX documentation system
├── infra/ # Infrastructure and database
│ └── Billing.Database/ # Liquibase Database project
├── src/ # Source code projects
│ ├── Billing/ # Domain logic
│ ├── Billing.Api/ # REST/gRPC endpoints
│ ├── Billing.AppHost/ # .NET Aspire orchestration
│ ├── Billing.BackOffice/ # Background processing
│ ├── Billing.BackOffice.Orleans/ # Orleans stateful processing
│ └── Billing.Contracts/ # Integration events and models
├── tests/ # Testing projects
│ └── Billing.Tests/ # Unit, Integration, and Architecture tests
└── libs/ # Shared libraries
└── Operations/ # Operations libs
├── src/ # Platform source code
│ ├── Operations.Extensions.*
│ ├── Operations.ServiceDefaults.*
│ └── ...
└── tests/ # Platform tests
The Billing service uses the following ports:
- Aspire Dashboard: 18100 (HTTP) / 18110 (HTTPS)
- Aspire Resource Service: 8100 (HTTP) / 8110 (HTTPS)
- Billing.UI: 8105 (HTTP) / 8115 (HTTPS)
- Billing.Api: 8101 (HTTP) / 8111 (HTTPS) / 8102 (gRPC insecure)
- Billing.BackOffice: 8103 (HTTP) / 8113 (HTTPS)
- Billing.BackOffice.Orleans: 8104 (HTTP) / 8114 (HTTPS)
- Documentation Service: 8119
- 54320: PostgreSQL
- 4317/4318: OpenTelemetry OTLP
- Docker (optional, for containerized deployment) or..
- .NET 9 SDK
- PostgreSQL running on localhost:5432 (username:
postgres, password:password@) - Liquibase CLI (for manual database setup)
- TBD