vtuber-awards/docs/CONVENTIONS.md

Engineering Conventions

This document defines project engineering standards. It should stay practical, specific, and enforceable. For architecture boundaries, see ARCHITECTURE.md. For quality gates, see 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 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:

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 for project facts and runtime expectations.
• Use ARCHITECTURE.md for system structure and boundaries.
• Use DECISIONS.md for durable trade-offs.
• Use 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.