# Engineering Conventions

This document defines project engineering standards. It should stay practical,
specific, and enforceable. For architecture boundaries, see
[ARCHITECTURE.md](ARCHITECTURE.md). For quality gates, see
[CHECKLISTS.md](CHECKLISTS.md).

## General Rules

- Prefer correctness, maintainability, and clear ownership over speed.
- Read nearby code and docs before editing.
- Keep changes scoped; do not mix unrelated cleanup with behavior changes.
- Preserve user work and unrelated local changes.
- Treat missing business logic as an unknown, not as permission to invent it.
- Update documentation when setup, architecture, operations, or public behavior
  changes.

## Naming

- Use domain terms over technical shorthand.
- Name Vue components in `PascalCase.vue`.
- Name composables as `useThing.ts`.
- Name API helpers by feature or API area.
- Name backend endpoints, contracts, services, and repositories by feature.
- Name booleans as predicates, such as `isEnabled`, `hasPermission`, or
  `canSubmit`.

## Frontend

- Use Vue 3 single-file components with TypeScript.
- Keep `.vue` files focused; split large admin or workflow screens into smaller
  components and composables.
- Keep route-level views in `frontend/src/views`.
- Keep reusable UI in `frontend/src/components`.
- Keep API calls in `frontend/src/lib/api` or established API helpers.
- Keep local state limited to UI interaction and unsaved form state when backend
  data exists.
- Public pages should use backend/admin truth instead of duplicated demo data.
- Admin pages should be dense, scannable, permission-aware, and operationally
  clear.
- Use existing design guidance in [../DESIGN.md](../DESIGN.md) before creating
  new visual patterns.

## Backend

- Use nullable-enabled C# with implicit usings.
- Keep endpoint groups focused on HTTP shape, mapping, authorization, and
  orchestration.
- Put reusable use-case behavior in services.
- Put persistence-specific behavior in repositories when it is repeated,
  cross-feature, or domain-significant.
- Keep request/response DTOs in `Backend/Contracts`; do not expose persistence
  entities as public contracts by default.
- Keep auth and permission behavior server-side, even when the frontend hides
  controls.
- Prefer explicit validation responses over relying on database exceptions for
  expected user errors.

## Database And Migrations

- Use EF Core migrations for schema changes.
- Review migration names and generated operations before committing.
- Consider indexes, constraints, backfill, and rollback/recovery before schema
  changes.
- Production migrations are applied by the deploy workflow; do not add
  production startup auto-migrations without an explicit decision.
- Keep demo/presentation seed behavior controlled by environment flags.

## Configuration And Secrets

- Use `Backend/appsettings.Development.json` only for local defaults.
- Keep `Backend/appsettings.json` production-safe.
- Use `VTSA_POSTGRES` or `ConnectionStrings__Postgres` outside local defaults.
- Never hardcode secrets, tokens, API keys, production credentials, or private
  URLs in source.
- Non-development CORS origins must be explicit HTTP(S) origins.

## Validation

Default validation before pushing application changes:

```bash
cd frontend
npm run build

cd ..
dotnet build Backend/Backend.csproj --configuration Release
git diff --check
```

Add targeted checks when risk is higher:

- API `curl` checks for endpoint behavior.
- Browser checks for public/admin UI changes.
- Mobile width checks at `360px`, `390px`, `768px`, and desktop for responsive
  UI changes.
- Authenticated admin checks for permission or team-management changes.
- Live health checks only when the user explicitly moves the task to live or a
  release/deploy task requires it.

## Git And PRs

- Keep commits focused and imperative, for example `Fix team profile auth recovery`.
- Use PR descriptions with summary, validation, risks, screenshots for UI
  changes, and migration/deployment notes when relevant.
- Do not commit generated output such as `frontend/dist`, `Backend/bin`,
  `Backend/obj`, archives, prototype exports, or handoff documents.
- Explain failed or skipped validation clearly.

## Documentation

- Keep one authoritative source per topic and link to it instead of duplicating
  large sections.
- Use [PROJECT.md](PROJECT.md) for project facts and runtime expectations.
- Use [ARCHITECTURE.md](ARCHITECTURE.md) for system structure and boundaries.
- Use [DECISIONS.md](DECISIONS.md) for durable trade-offs.
- Use [workflow-feedback-plan.md](workflow-feedback-plan.md) and similar docs
  for scoped product plans.

## Review Priorities

Reviews should prioritize:

- user-visible correctness;
- security and authorization;
- data integrity and migrations;
- backend/admin truth versus duplicated state;
- operational risk and deploy safety;
- maintainability and file size;
- adequate validation evidence.