# Decent Billing ERP - Development Guide

## 1. Sub-sprint workflow

Every sub-sprint follows the same 18-step workflow, in order:

1. Planning
2. Database Design
3. Models
4. Services
5. Repositories
6. Controllers
7. Requests & Validation
8. Policies
9. Routes
10. Views
11. JavaScript
12. Responsive UI
13. Security Review
14. Unit Testing
15. Integration Testing
16. Performance Optimization
17. Documentation
18. Self QA

A sub-sprint is only "done" when the completion report has all ten sections
green (Completed Module Checklist, Database Changes, File Structure Changes,
New Dependencies, Security Review, Performance Report, Test Results, Known
Issues, Deployment Readiness, Next Sub-Sprint Plan).

## 2. Coding standards

- PHP 8.2, strict types on every file (`declare(strict_types=1);`).
- Class-first: no procedural code outside `app/Support/helpers.php` and the
  routes files.
- `final` by default. `abstract` for extension points.
- Constructor property promotion, readonly where possible.
- No `mixed` return types on public APIs; use unions or generics.
- Static analysis: PHPStan level 8 (added under `composer analyse`).
- Formatting: Laravel Pint with the shipped preset.

## 3. Blade rules

- Layouts live in `resources/views/layouts/`.
- Reusable components live in `resources/views/components/`.
- Pages live in `resources/views/pages/`.
- Error views live in `resources/views/errors/`.
- Never call the DB or the router from a Blade view. Pass everything through
  the view data.

## 4. JavaScript rules

- Vanilla ES modules under `resources/js/modules/*`.
- No jQuery. No global state beyond `window.DecentERP` (read-only export).
- Client behaviour is driven by `data-action="..."` attributes so it is
  trivially testable and CSP-safe.
- Fetch requests always include the CSRF token from the `<meta>` tag.

## 5. CSS rules

- Bootstrap 5.3 partials are imported explicitly (no monolithic
  `@import "bootstrap"`) so the built CSS stays small.
- All colors reference `--dc-*` variables. See `UI-DESIGN-SYSTEM.md`.
- No inline styles without a CSP nonce.

## 6. Test rules

- Every domain class ships with a unit test.
- Every route ships with at least one feature test.
- Deterministic tests only: no network, no time-dependent assertions
  (freeze time when needed).
- Assertions describe intent (`test_landing_page_uses_guest_layout_...`),
  not the framework verb.

## 7. Commit conventions

- Conventional Commits: `feat:`, `fix:`, `chore:`, `docs:`, `test:`,
  `refactor:`, `perf:`, `build:`, `ci:`, `revert:`.
- One logical change per commit. Multi-file refactors are fine when they
  serve one intent.
- Reference the sub-sprint id in the body when relevant: `feat(theme):
  add density switch (S0.1)`.

## 8. Local runbook

```bash
# Install
composer install
npm install

# Prepare
cp .env.example .env
php artisan key:generate
php artisan migrate --seed

# Develop
php artisan serve       # in one terminal
npm run dev             # in another

# Verify
composer test
composer analyse        # PHPStan
composer format         # Pint --test
```