Add project documentation and update workflow plan
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>
This commit is contained in:
AzuTear
@@ -0,0 +1,226 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user