# ServDiary — Agent Instructions

Home servicing scheduling tool and CRM. Agents must follow this file and the wiki under [`docs/`](docs/).

## Stack

- PHP `^8.3`, Laravel `^13`
- Jetstream (Inertia + Teams) for the website
- Sanctum for Android/iOS webservices
- Vue + Inertia for the web UI
- Application code lives in [`laravel/`](laravel/)

## Non-negotiables

1. **Independent domains** — Product features live in `laravel/app/Domains/{Feature}/`. Features must be addable and removable without breaking other features.
2. **Normalised database** — Schema must be normalised (target: third normal form). No duplicated business data across tables/columns; use foreign keys and related tables. Document any intentional denormalisation on the feature wiki page with rationale.
3. **Docs wiki** — Every meaningful change updates [`docs/`](docs/). No orphan feature code without a page under `docs/features/`.
4. **Feature tests** — Every feature ships PHPUnit Feature tests. Run `cd laravel && php artisan test` before considering work done.
5. **Docblocks** — Every PHP method (public, protected, private) gets a PHPDoc block with `@param`, `@return`, and `@throws` when relevant.

## Platform vs product

| Layer | Location | Removable? |
|-------|----------|------------|
| Platform (auth, User, Team, profile, Jetstream) | Default Laravel/Jetstream paths | No — shared kernel |
| Product features (scheduling, customers, jobs, etc.) | `laravel/app/Domains/{Feature}/` | Yes |

Do not put removable product logic in platform folders. Do not couple domains to each other via model imports, shared tables, or hard route dependencies unless the dependency is platform (`User` / `Team` / auth) and documented on the feature page.

## Add a feature

1. Create `laravel/app/Domains/{Feature}/` (see [`docs/architecture/domains.md`](docs/architecture/domains.md)).
2. Copy [`docs/features/_template.md`](docs/features/_template.md) to `docs/features/{feature}.md` and fill it in.
3. Link the page from [`docs/README.md`](docs/README.md).
4. Add Feature tests under `laravel/tests/Feature/Domains/{Feature}/`.
5. Register only that domain’s service provider / routes.

## Remove a feature

1. Delete `laravel/app/Domains/{Feature}/`.
2. Delete `docs/features/{feature}.md` and unlink it from the wiki index.
3. Delete `laravel/tests/Feature/Domains/{Feature}/`.
4. Unregister the domain’s provider / routes.
5. Nothing else should break.

## Scope discipline

- Prefer small, focused changes inside one domain.
- Do not invent CRM entities unless the task asks for them.
- Prefer updating the wiki and tests in the same change as the code.