A world-class SaaS payroll system built with Clean Architecture, Domain-Driven Design, and AI-agent friendly development practices.
# Windows (PowerShell)
.\tools\dev.ps1 bootstrap
# Linux/macOS (Bash)
./tools/dev.sh bootstrapThis will:
✅ Install all dependencies
✅ Create and migrate database
✅ Seed initial data
✅ Verify installation
# Start both backend and frontend
.\tools\dev.ps1 run
# Or run separately:
# Terminal 1 - Backend API (http://localhost:52938)
.\tools\dev.ps1 run backend
# Terminal 2 - Frontend SPA (http://localhost:4200)
.\tools\dev.ps1 run frontend- DEVELOPMENT.md - Development setup, workflows, and commands
- AGENTS.md - AI agent operating manual (for Copilot, Cursor, etc.)
- ARCHITECTURE.md - System architecture and design decisions
- docs/adr/ - Architecture Decision Records
┌─────────────────────────────────────┐
│ Presentation (Angular SPA) │
├─────────────────────────────────────┤
│ API Layer (ASP.NET Core) │
├─────────────────────────────────────┤
│ Application (Use Cases, DTOs) │
├─────────────────────────────────────┤
│ Domain (Entities, Business Logic)│
├─────────────────────────────────────┤
│ Infrastructure (EF Core, Services) │
└─────────────────────────────────────┘
- Employees - Employee management
- Payroll - Pay runs, payslips, calculations
- PayrollConfig - Tax rules, allowances, deductions
- Organizations - Companies, branches, cost centers
- Leave - Leave management
- Loans - Employee loans
- Overtime - OT tracking
- GeneralLedger - GL integration
- Auditing - Audit trail
- .NET 8 - Framework
- ASP.NET Core - Web API
- Entity Framework Core - ORM
- SQL Server - Database
- MediatR - CQRS implementation
- FluentValidation - Input validation
- AutoMapper - Object mapping
- Angular 18+ - SPA framework
- PrimeNG - UI components
- RxJS - Reactive programming
- TypeScript - Type safety
- xUnit - Backend unit tests
- Jasmine/Karma - Frontend unit tests
- Playwright - E2E tests
# Build everything
.\tools\dev.ps1 build
# Run all tests
.\tools\dev.ps1 test
# Run specific tests
.\tools\dev.ps1 test backend
.\tools\dev.ps1 test frontend
.\tools\dev.ps1 test e2e
# Lint and format code
.\tools\dev.ps1 lint
# Clean build artifacts
.\tools\dev.ps1 clean
# Database operations
.\tools\dev.ps1 db-migrate "MigrationName"
.\tools\dev.ps1 db-update
.\tools\dev.ps1 db-resetPayRoll/
├── backend/ # .NET backend (current)
│ ├── Payroll.Api # API controllers
│ ├── Payroll.Application # Use cases, DTOs
│ ├── Payroll.Domain # Domain entities
│ ├── Payroll.Infrastructure # Data access
│ └── Payroll.Shared # Common utilities
├── frontend/ # Angular frontend (current)
│ └── payroll-web/ # SPA application
├── qa-automation/ # Playwright E2E tests
├── docs/ # Documentation
│ ├── adr/ # Architecture decisions
│ ├── architecture/ # Architecture diagrams
│ └── product/ # Product requirements
├── tools/ # Development tools
│ ├── dev.ps1 # PowerShell dev script
│ └── dev.sh # Bash dev script
└── .github/ # GitHub workflows
└── workflows/ # CI/CD pipelines
Note: We're gradually migrating to a
/srcmonorepo structure. See ADR-0001 for details.
/\
/E2E\ ← 10% (Critical user journeys)
/------\
/ API \ ← 20% (Integration tests)
/----------\
/ Unit \ ← 70% (Business logic)
/--------------\
# All tests
.\tools\dev.ps1 test
# Backend unit tests
cd backend/Payroll.Application.Tests
dotnet test
# Frontend unit tests
cd frontend/payroll-web
npm test
# E2E tests
cd qa-automation
npx playwright test- Authentication: JWT-based
- Authorization: Role-based + Permission-based
- Data Protection: SQL Server TDE (production)
- Input Validation: Server-side validation mandatory
- Audit Trail: Immutable audit log
- ✅ EPF (Employees' Provident Fund) calculations
- ✅ ETF (Employees' Trust Fund) calculations
- ✅ PAYE Tax calculations per Inland Revenue Department
- ✅ Support for Sri Lankan date formats
- ✅ Currency: LKR (Sri Lankan Rupee)
This repository is optimized for AI coding assistants:
- Clear Structure: Organized by bounded contexts
- Consistent Naming: PascalCase (C#), kebab-case (Angular)
- Comprehensive Docs: AGENTS.md guides AI agents
- Type Safety: TypeScript + C# strong typing
- Test Coverage: High test coverage for confidence
See AGENTS.md for AI agent guidelines.
- Development: Local development
- Test: QA testing
- Staging: Pre-production
- Production: Live system
- ✅ Automated build and test
- ✅ Code quality checks
- ✅ Security scanning
- ⏳ Automated deployment (coming soon)
- ✅ Clean architecture setup
- ✅ Core payroll calculations
- ✅ Employee management
- ✅ Basic reporting
- ⏳ Advanced reporting
- ⏳ Leave management
- ⏳ Loan management
- ⏳ Performance optimization
- 📋 Multi-currency support
- 📋 Advanced GL integration
- 📋 Mobile app
- 📋 Self-service portal
- 📋 Microservices architecture
- 📋 Advanced analytics
- 📋 AI-powered insights
- 📋 International expansion
We welcome contributions! Please follow these steps:
- Read DEVELOPMENT.md
- Read AGENTS.md for conventions
- Create a feature branch
- Make your changes
- Run tests:
.\tools\dev.ps1 test - Run lint:
.\tools\dev.ps1 lint - Submit a PR using the template
This project is licensed under the MIT License - see the LICENSE file for details.
- Documentation: Check DEVELOPMENT.md and AGENTS.md
- Issues: Create a GitHub issue
- Discussions: Use GitHub Discussions
- Built with ❤️ for Sri Lankan businesses
- Powered by .NET and Angular
- Inspired by Clean Architecture and DDD principles
Last Updated: 2025-12-25
Version: 1.0.0
Maintained By: Development Team