# 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](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.