Contributing Guide — Laundry Management System¶

Welcome¶

This guide helps you set up the development environment, understand the workflow, and contribute code and documentation.

Quick Start¶

Prerequisites¶

Tool	Version	Purpose
.NET SDK	9.0+	Backend
Node.js	22+	Frontend
Docker Desktop	26+	PostgreSQL, Seq, Traefik for local dev
Rust (optional)	1.80+	Only if modifying Tauri Rust code
Git	2.40+	Version control

First Setup¶

# 1. Clone the repository
git clone git@github.com:<org>/laundry.git
cd laundry

# 2. Start development Docker services
cd backend/Laundry.Api
docker compose -f docker-compose.dev.yml up -d postgres seq

# 3. Apply database migrations
dotnet ef database update

# 4. Run the backend
dotnet run
# → API at http://localhost:5000
# → Swagger at http://localhost:5000/swagger

# 5. Install frontend dependencies
cd ../../frontend/laundry-app
npm install

# 6. Run the frontend + Tauri
npx tauri dev
# → Tauri window opens at http://localhost:4200 (or laundry.local)

Now open the project in Visual Studio 2022 (backend/Laundry.sln) and VS Code (frontend/laundry-app/).

Git Workflow (Git Flow)¶

main               ← Production releases (tagged)
  │
  ├── develop      ← Integration branch
  │     │
  │     └── feature/<name>    ← Your work
  │
  ├── hotfix/<name>           ← Emergency fixes
  │
  └── release/<version>       ← Release preparation

Branch Naming¶

Type	Pattern	Example
Feature	`feature/invoice-print`	`feature/carpet-receipt`
Bug fix	`fix/payment-calculation`	`fix/invoice-number-duplicate`
Hotfix	`hotfix/login-crash`	`hotfix/1.0.1-payment-null`
Release	`release/1.1.0`	`release/1.1.0`
Docs	`docs/api-reference`	`docs/security-overview`

Commit Conventions (Conventional Commits)¶

feat: add carpet receipt creation
fix: prevent duplicate invoice numbers
chore: update NuGet packages
docs: add Mermaid diagram to data model
test: add accounting balance validation tests
refactor: extract GL posting logic

Project Board (GitHub Projects)¶

We use a GitHub Projects Kanban board:

Column	Meaning
Backlog	Approved, not yet scheduled
Sprint Backlog	Selected for current sprint
In Progress	Being worked on
Review	PR opened, awaiting review
Done	Merged to `develop`

How to Pick Up Work¶

Open the GitHub Projects board.
Find an unassigned issue in "Sprint Backlog".
Assign it to yourself.
Create a feature branch from develop.
Move the issue to "In Progress".
Open a PR. The issue auto-moves to "Review".
After merge, the issue auto-moves to "Done".

Pull Request Checklist¶

Before opening a PR, ensure:

[ ] Backend tests pass: dotnet test (all green)
[ ] Frontend tests pass: npm test (all green)
[ ] Code coverage meets thresholds: BE ≥ 80%, FE ≥ 70%
[ ] Lint clean: npm run lint (no warnings)
[ ] Production build succeeds: npm run build -- --configuration=production
[ ] Tauri dev build works: npx tauri dev

[ ] EF Core migration added if the database schema changed. Test with:

dotnet ef migrations add <MigrationName> -p Laundry.Infrastructure -s Laundry.Api

[ ] Migration tested against a fresh PostgreSQL container
[ ] PR description includes:
What was changed and why
Screenshots (if UI changed)
Breaking changes (if any)
Migration impact (if schema changed)
[ ] PR linked to an issue in GitHub Projects
[ ] At least one approving review

Code Conventions¶

Backend (C#)¶

PascalCase for public members, camelCase for parameters, _camelCase for private fields
One class/enum/interface per file
All I/O operations are async with CancellationToken
Use Result<T> pattern for expected failures. Exceptions only for unexpected errors.
decimal for all monetary values — never float/double
UUIDs: Guid.NewGuid(), never auto-generated by the database
Enable nullable reference types in all .csproj files

Frontend (TypeScript/Angular)¶

kebab-case for file names, PascalCase for class names
Smart containers: *-container.component.ts. Dumb components: descriptive names.
All components: standalone: true, changeDetection: OnPush
Use async pipe in templates. Subscribe only in Effects.
interface for DTOs (not class)
NEVER hardcode Arabic/English strings. Use translate pipe.
Services suffixed Service for HTTP, Facade for store abstraction.

Documentation¶

Docs Folder¶

All documentation lives in docs/ as Markdown files. This includes:

Requirements (SRS)
Architecture (Data Model, Security, ADRs)
Development guides (Backend, Frontend, Testing)
Operations (Deployment, CI/CD, License)
Management (Execution Plan)

MkDocs Website¶

The docs are rendered into a website using MkDocs + Material for MkDocs:

# Install
pip install mkdocs mkdocs-material

# Serve locally
mkdocs serve

# Build
mkdocs build

The website is auto-deployed to GitHub Pages on every merge to main.

Editing Docs¶

Edit .md files in docs/.
If you add a new file, update mkdocs.yml nav section.
Commit with docs: prefix.

Testing¶

Backend: dotnet test in the solution root
Frontend: npm test in frontend/laundry-app/
Single test: dotnet test --filter "FullyQualifiedName=Namespace.Class.Method"
Accounting validation: Every accounting flow must have a test asserting SUM(debit) == SUM(credit)
Sync validation: Export-import round-trip tests must assert row counts and balances match

See docs/Testing_Strategy_EN.md for the full strategy.

Environment Variables (Sensitive)¶

Never commit these to the repository:

DB_PASSWORD
JWT_KEY
CLIENT_TOKEN_SECRET
LICENSE_MASTER_KEY
license.dat
.env files

Use .gitignore to exclude them. Templates are in deploy/.env.template.

Getting Help¶

Code questions: Comment on the relevant GitHub Issue or open a Discussion
Architecture questions: See docs/Architecture_Decision_Records.md
Setup issues: Check docs/Infrastructure_Deployment_EN.md
Bug reports: Open a GitHub Issue with steps to reproduce, expected vs actual behavior, and logs from Seq (if available)

Revision History¶

Date	Version	Author	Changes
2026-05-10	1.0	Tech Lead	Initial contributing guide