template/examples/CONVENTIONS.example.md

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.