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>
5.6 KiB
Decisions
This document contains Architecture Decision Records (ADRs). Record decisions that materially affect architecture, operations, security, data ownership, public contracts, or long-term maintainability.
For architecture context, see ARCHITECTURE.md.
Status Values
- Proposed: under discussion.
- Accepted: current decision.
- Superseded: replaced by a newer decision.
- Deprecated: no longer recommended, but still present.
- Rejected: considered and intentionally not chosen.
ADR Index
| ID | Title | Status | Date |
|---|---|---|---|
| ADR-001 | Keep durable engineering documentation in the repository | Accepted | 2026-06-28 |
| ADR-002 | Use a Vue and ASP.NET Core monorepo | Accepted | 2026-06-28 |
| ADR-003 | Keep backend/admin data as public truth | Accepted | 2026-06-28 |
| ADR-004 | Apply production migrations in the deploy pipeline | Accepted | 2026-06-28 |
| ADR-005 | Require explicit validation evidence for application changes | Accepted | 2026-06-28 |
ADR Template
Status
Proposed
Date
YYYY-MM-DD
Context
Describe the forces, constraints, project stage, and previous behavior.
Problem
State the specific problem being solved.
Alternatives
| Alternative | Summary |
|---|---|
| Option A | Summary. |
| Option B | Summary. |
Decision
State the chosen option and why it fits the current constraints.
Consequences
- Expected benefit.
- Expected cost or trade-off.
- Follow-up or review trigger.
ADR-001: Keep Durable Engineering Documentation In The Repository
Status
Accepted
Date
2026-06-28
Context
The project uses AI-assisted development and has accumulated product, runtime, security, admin, deployment, and design knowledge across code and local context.
Problem
Important engineering knowledge is harder to maintain when it lives only in chat, memory, or transient planning notes.
Decision
Keep durable engineering documentation in docs/ and link high-level entry
points from README.md and AGENTS.md.
Consequences
- Architecture, conventions, workflow, release, and decision context can be reviewed with code changes.
- Planning notes may still exist for scoped work, but accepted project rules should move into durable docs.
- Documentation must be maintained when architecture or operations change.
ADR-002: Use A Vue And ASP.NET Core Monorepo
Status
Accepted
Date
2026-06-28
Context
The platform has a tightly related public frontend, admin frontend, backend API, database migrations, and deployment pipeline.
Problem
Splitting the application too early would increase coordination cost for a small product surface whose frontend and backend contracts evolve together.
Decision
Keep the Vue/Vite frontend and ASP.NET Core backend in one monorepo, with clear folder boundaries and shared validation through the Gitea workflow.
Consequences
- Cross-stack changes can be reviewed and deployed together.
- CI can enforce frontend and backend build health in one place.
- Internal boundaries must be protected through conventions and review, not repository separation.
ADR-003: Keep Backend/Admin Data As Public Truth
Status
Accepted
Date
2026-06-28
Context
The public landing page and workflow screens need to reflect seasons, settings, showacts, sponsors, footer links, voting state, and participation state managed through the backend/admin surface.
Problem
Parallel frontend-only demo data creates drift between what admins configure and what users see.
Decision
Use backend/admin state as the source of truth for public pages whenever a backend-backed model exists.
Consequences
- Public UI should use
/api/public/*data instead of local duplicate content. - Admin changes need API and frontend contract updates when public content changes.
- Local-only state is reserved for interaction state, draft forms, and optimistic UI where appropriate.
ADR-004: Apply Production Migrations In The Deploy Pipeline
Status
Accepted
Date
2026-06-28
Context
The backend can auto-apply migrations in development, while production deploys
run through .gitea/workflows/ci.yaml.
Problem
Automatic production startup migrations make rollback and failure handling less predictable.
Decision
Apply EF Core migrations during the production deploy workflow after a predeploy PostgreSQL backup and before service restart. Keep development startup migrations for local convenience.
Consequences
- Production schema changes are visible in deployment logs.
- Backups are written before migrations.
- Destructive or hard-to-reverse migrations still require manual review and a recovery plan before release.
ADR-005: Require Explicit Validation Evidence For Application Changes
Status
Accepted
Date
2026-06-28
Context
The repository currently relies on frontend type/build checks, backend Release builds, CI hygiene checks, and targeted manual verification. A dedicated test project is not checked in yet.
Problem
Without explicit validation evidence, reviewers cannot reliably distinguish a verified full-stack change from a plausible but untested edit.
Decision
Every non-trivial application change should include the commands and manual checks that were run, plus any failures or skipped checks.
Consequences
- Final work summaries and PR descriptions must name validation.
- UI, auth, migration, and live/deploy changes need targeted checks beyond a generic build when practical.
- Missing automated regression coverage remains visible as residual risk until test projects are added.