AzuTear
fc5c13a4fd
Adds AGENTS.md, DESIGN.md, and docs/* covering architecture, conventions, decisions, checklists, branching, release process, and prompts. Updates README and workflow-feedback-plan to reflect the decoupled GroupName nomination model. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
131 lines
4.8 KiB
Markdown
131 lines
4.8 KiB
Markdown
# 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.
|