# Atlas Desk Conventions

## Naming

- Use support-domain language: request, assignment, note, queue, audit event.
- Use `Async` suffix for asynchronous backend methods.
- Name Vue components by feature and purpose, such as `RequestDetailPanel`.
- Name authorization policies by action, such as `CanAssignRequest`.

## File Organization

- Keep backend files under their owning module.
- Keep Vue components below 250 lines when practical.
- Co-locate component tests with feature components.
- Keep generated API types in `frontend/src/shared/api/generated`.

## Folder Organization

| Folder | Rule |
| --- | --- |
| `backend/src/Requests` | Owns request workflow commands, queries, and domain rules. |
| `backend/src/Shared` | Contains cross-cutting primitives only. |
| `frontend/src/features/requests` | Owns request screens and feature-specific components. |
| `frontend/src/shared` | Contains reusable UI primitives and API utilities. |

## Dependency Injection

- Register backend services by module.
- Inject clocks, email clients, database contexts, and external gateways.
- Do not inject primitive configuration values directly into domain classes.

## Logging

- Use structured logs with `requestId` and `userId` where available.
- Log workflow transitions at information level.
- Log authorization denials at warning level only when they indicate suspicious behavior.
- Do not log customer message bodies.

## Validation

- Validate API DTO shape at the API boundary.
- Validate workflow invariants inside request commands.
- Validate authorization before loading sensitive detail views.

## Error Handling

- Use stable problem codes for client-visible API errors.
- Return validation errors as field-level responses.
- Include correlation IDs in error responses.
- Do not expose stack traces outside local development.

## DTO Rules

- API DTOs are separate from persistence entities.
- Request detail DTOs must not include internal audit metadata unless the user has manager or auditor access.
- Public API changes require a changelog entry.

## Repository Rules

- Use the repository pattern for persistence boundaries.
- Keep repository interfaces in the owning backend module.
- Keep repository implementations near persistence infrastructure.
- Use specific repositories such as `RequestRepository` and `UserRepository`.
- Keep queries explicit, such as `FindOpenRequestsForQueue`.
- Do not add generic repository abstractions over the database context.
- Write operations that can be retried must be idempotent or transactionally protected.

## Service Rules

- Application services coordinate commands and queries.
- Domain services contain request workflow rules only when the rule spans entities.
- External email delivery is behind an interface.

## Testing

- Unit test request state transitions.
- Integration test authorization and database persistence.
- End-to-end test create, assign, comment, and close workflows.
- Add regression tests for production defects.

## Git Workflow

- Branch names use `feature/`, `fix/`, `refactor/`, `docs/`, or `hotfix/`.
- Squash merge pull requests into `main`.
- Commit messages use imperative summaries.

## Pull Requests

- Include summary, validation, risk, and screenshots for UI changes.
- Include migration notes when database schema changes.
- Keep unrelated refactors in separate pull requests.

## Code Reviews

- Block on correctness, security, data integrity, missing validation, or unclear ownership.
- Prefer suggestions for style issues that are not covered by tooling.
- Ask for ADR updates when a decision changes system structure.