bao/vtuber-awards
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add project documentation and update workflow plan

Browse Source 
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
2026-06-28 23:31:13 +02:00
parent 18b61bed52
commit fc5c13a4fd
13 changed files with 1670 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ARCHITECTURE.md
+206
View File
@@ -0,0 +1,206 @@
# Architecture
This document describes the structure, boundaries, flows, and technical rules of
the VTuber Star Awards system. For project facts, see [PROJECT.md](PROJECT.md).
For coding standards, see [CONVENTIONS.md](CONVENTIONS.md).
For recorded trade-offs, see [DECISIONS.md](DECISIONS.md).
## High-Level Overview
VTuber Star Awards is a production monorepo with a Vue/Vite frontend, an
ASP.NET Core 8 minimal API backend, and a PostgreSQL database managed by EF Core
migrations.
```mermaid
flowchart LR
Public["Public users"]
Team["Team/admin users"]
Frontend["Vue/Vite frontend"]
Api["ASP.NET Core API"]
Domain["Domain models and services"]
Database["PostgreSQL"]
Twitch["Twitch OAuth"]
CI["Gitea Actions"]
Public --> Frontend
Team --> Frontend
Frontend --> Api
Api --> Domain
Domain --> Database
Api --> Twitch
CI --> Api
CI --> Frontend
CI --> Database
```
The frontend is the user interface. The backend is the source of truth for
season state, content, team permissions, moderation, workflow rules, and public
overview data.
## Architecture Style
| Field | Value |
| --- | --- |
| Style | Layered modular monolith |
| Runtime shape | One frontend app, one backend API, one PostgreSQL database |
| Primary reason | Keep deployment simple while preserving clearer internal feature boundaries. |
| Main trade-off | Boundaries depend on code organization and review discipline rather than service isolation. |
## Repository Structure
```text
VTubeAwards/
frontend/
src/
views/
components/
stores/
lib/
types/
Backend/
Common/
Configuration/
Contracts/
Data/
Domain/
Endpoints/
Extensions/
Migrations/
Repositories/
Security/
Services/
docs/
.gitea/workflows/
```
| Folder | Responsibility |
| --- | --- |
| `frontend/src/views` | Route-level Vue views. |
| `frontend/src/components` | Reusable public/admin UI components and composables. |
| `frontend/src/lib` | API clients, HTTP helpers, formatting, and shared frontend utilities. |
| `frontend/src/types` | TypeScript contract and payload types. |
| `Backend/Endpoints` | Minimal API endpoint groups and endpoint-specific mapping helpers. |
| `Backend/Contracts` | Request and response DTOs. |
| `Backend/Domain` | Persistent domain entities and core business concepts. |
| `Backend/Data` | EF Core `DbContext`, seed/bootstrap code, and design-time setup. |
| `Backend/Repositories` | Domain-specific persistence boundaries. |
| `Backend/Services` | Use-case, audit, session, risk, and workflow services. |
| `Backend/Security` | Session filters, role/permission catalog, and security middleware. |
| `docs` | Durable project, architecture, workflow, and decision documentation. |
## Backend Flow
```mermaid
sequenceDiagram
participant Client as Frontend or API client
participant Endpoint as Minimal API endpoint
participant Filter as Admin/session filter
participant Service as Service or repository
participant Db as EF Core/PostgreSQL
Client->>Endpoint: HTTP request
Endpoint->>Filter: Auth and permission checks when required
Endpoint->>Service: Validate intent and execute use case
Service->>Db: Query or persist through DbContext/repository
Db-->>Service: Domain data
Service-->>Endpoint: Contract DTO
Endpoint-->>Client: JSON response or problem result
```
Endpoint files should stay focused on transport concerns, authorization,
mapping, and orchestration. Domain rules and cross-endpoint behavior belong in
services, repositories, or domain-specific helpers.
## Frontend Flow
```mermaid
flowchart TD
Route["Vue route/view"]
Components["Focused components"]
Composables["Composables and stores"]
ApiClient["frontend/src/lib/api"]
Backend["Backend API"]
Route --> Components
Components --> Composables
Composables --> ApiClient
ApiClient --> Backend
```
Public pages should render backend/admin truth. Admin pages should favor clear
workspace structure, permission-aware controls, explicit loading/error states,
and smaller Vue files split by feature.
## Data Ownership
| Data | Owner | Notes |
| --- | --- | --- |
| Seasons, categories, candidates, winners | Backend | Public and admin views read from canonical backend state. |
| Nominations and clip submissions | Backend | Public writes are validated and reviewed through admin workflows. |
| Site settings, landing content, footer links, showacts, sponsors | Backend | Content hub/admin settings own public presentation data. |
| Team members, roles, permissions, sessions | Backend | UI may hide controls, but API authorization is authoritative. |
| Risk flags and audit entries | Backend | Used for admin review, diagnostics, and accountability. |
| Frontend interaction state | Frontend | Local state is allowed only for view state and unsaved form state. |
## Persistence Boundary
The backend uses EF Core with PostgreSQL. Domain-specific repositories exist for
session, risk flag, and audit behavior. Direct `AwardsDbContext` use is still
acceptable inside endpoint groups or services when the operation is simple and
local to one feature, but repeated or cross-feature persistence behavior should
move behind a repository or focused service.
Production migrations are applied by the Gitea deploy workflow. Development can
auto-apply migrations during API startup.
## Authentication And Authorization
- Team/admin authentication is session-based.
- Twitch OAuth is handled through backend auth endpoints.
- Admin endpoints use session/permission checks at the trusted backend boundary.
- The frontend should reflect permissions to improve UX, but never be the only
authorization layer.
- `creator` is not a normal assignable role in team management.
## Security Posture
| Area | Policy |
| --- | --- |
| CORS | Non-development environments require explicit configured frontend origins. |
| Public writes | Rate-limited and validated server-side. |
| Secrets | Environment variables only; no checked-in production credentials. |
| Demo data | Controlled by seed/demo environment flags. Production defaults must remain safe. |
| Headers | Security headers are applied by backend middleware. |
| Audit | Admin-relevant changes should emit useful audit records where supported. |
## Deployment Flow
```mermaid
flowchart LR
Push["Push to main or manual dispatch"]
Verify["Build, typecheck, hygiene"]
Sync["Sync code to production host"]
Backup["Predeploy PostgreSQL backup"]
Migrate["Apply EF Core migrations"]
Restart["Recreate api and web services"]
Smoke["Health, database, and asset checks"]
Push --> Verify
Verify --> Sync
Sync --> Backup
Backup --> Migrate
Migrate --> Restart
Restart --> Smoke
```
The production deploy path is encoded in `.gitea/workflows/ci.yaml`.
## Known Constraints
- There is no dedicated checked-in test project yet.
- Build/type checks and targeted manual verification are currently required for
most changes.
- Production database migration rollback must be considered before risky schema
changes; the pipeline writes backups but does not make destructive migrations
automatically safe.
- Large admin and public Vue surfaces should continue to be split as they grow.
docs/CHECKLISTS.md
+92
View File
@@ -0,0 +1,92 @@
# Checklists
Use these concise checklists as quality gates. Expand them only when repeated
project experience proves that more detail is necessary.
For workflow details, see [workflow.md](workflow.md). For code standards, see
[CONVENTIONS.md](CONVENTIONS.md). For releases, see
[release-process.md](release-process.md).
## Feature Development
- [ ] Objective, users, acceptance criteria, and non-goals are clear.
- [ ] Relevant docs and existing implementation were read.
- [ ] Frontend/backend contract and source of truth are identified.
- [ ] Permission, workflow, empty, loading, error, and disabled states are handled.
- [ ] Docs are updated when behavior, setup, or architecture changed.
- [ ] Frontend build, backend build, and targeted manual checks are run.
## Bug Fix
- [ ] Observed behavior is understood.
- [ ] Expected behavior is confirmed.
- [ ] Root cause is identified before changing code.
- [ ] Fix is scoped to the cause.
- [ ] Regression coverage or targeted manual verification covers the failing path.
- [ ] Remaining risk is documented.
## Frontend UI Change
- [ ] Existing components, composables, and design guidance were checked.
- [ ] Public UI uses backend/admin truth when available.
- [ ] Admin UI is scannable and permission-aware.
- [ ] Text wraps without overlap at mobile and desktop widths.
- [ ] Browser checks include relevant routes and responsive widths.
- [ ] `npm run build` passes.
## API Change
- [ ] Request and response contracts are stable and typed.
- [ ] Authorization is enforced server-side.
- [ ] Validation errors are consistent and actionable.
- [ ] Public writes are rate-limited where appropriate.
- [ ] Idempotency, pagination, filtering, or sorting are considered when relevant.
- [ ] Frontend clients and TypeScript types are updated.
## Database Change
- [ ] Data ownership and invariants are clear.
- [ ] Migration operations are reviewed manually.
- [ ] Constraints and indexes match expected behavior.
- [ ] Backfill and deployment order are documented when needed.
- [ ] Rollback or forward-fix path is understood.
- [ ] Database health and pending migrations are checked after applying.
## Security Review
- [ ] Authentication is required where expected.
- [ ] Authorization is enforced on the backend.
- [ ] Inputs are validated.
- [ ] Outputs are safely serialized or encoded.
- [ ] Secrets are not logged or committed.
- [ ] Sensitive user or team data exposure is minimized.
- [ ] Demo, seed, and local-only behavior cannot leak into production.
## Pull Request
- [ ] Summary explains what and why.
- [ ] Scope is focused.
- [ ] Validation commands and manual checks are listed.
- [ ] Screenshots or recordings are included for visible UI changes.
- [ ] Migration and deployment notes are included when relevant.
- [ ] Risks, skipped validation, and follow-ups are documented.
- [ ] No generated output, secrets, debug code, or unrelated files are included.
## Release
- [ ] Release scope and target commit are known.
- [ ] Required CI checks passed.
- [ ] Migration risk is reviewed.
- [ ] Configuration and secrets are ready.
- [ ] Predeploy backup is confirmed by the pipeline.
- [ ] Health, database, and frontend asset checks pass.
- [ ] Rollback or recovery path is understood.
## Production Readiness
- [ ] Runtime environments and URLs are documented.
- [ ] Health checks exist and are reachable.
- [ ] Database connectivity and pending migrations can be inspected.
- [ ] Production CORS, seed mode, and demo login settings are safe.
- [ ] Backups and restore expectations are documented.
- [ ] Operational ownership and alerting gaps are explicit.
docs/CONVENTIONS.md
+130
View File
@@ -0,0 +1,130 @@
# 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.
docs/DECISIONS.md
+226
View File
@@ -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.
docs/PROJECT.md
+148
View File
@@ -0,0 +1,148 @@
# VTuber Star Awards Project
This document is the durable source of truth for project intent, runtime facts,
and operational expectations. For system structure, see [ARCHITECTURE.md](ARCHITECTURE.md).
For engineering standards, see [CONVENTIONS.md](CONVENTIONS.md).
## Project Identity
| Field | Value |
| --- | --- |
| Project name | VTuber Star Awards |
| Repository | `https://git.noveria.net/bao/vtuber-awards.git` |
| Primary product | Public awards platform with admin operations tooling |
| Production URL | `https://award.noveria.net` |
| Status | Active production application |
## Vision
VTuber Star Awards is a public awards platform for nominations, clip
submissions, voting, winner presentation, showact applications, sponsor content,
and supporting public information pages.
The platform should be expressive and celebratory for public users while giving
operators a clear admin workspace for content, seasons, moderation, risk review,
team access, release visibility, and operational readiness.
## Goals
- Keep public pages driven by backend/admin truth rather than duplicated demo
state.
- Support the full awards workflow: season setup, nominations, clip review,
voting, results, landing content, sponsors, showacts, and static policy pages.
- Make admin workflows scannable, permission-aware, auditable, and reliable.
- Keep local development reproducible with a local PostgreSQL database and
explicit frontend/backend validation.
- Keep production deployment repeatable through the Gitea pipeline, database
backups, EF Core migrations, health checks, and frontend asset verification.
## Non-Goals
- Do not self-host user-submitted video clips unless that product decision is
explicitly revisited.
- Do not keep parallel frontend-only demo data when backend-backed data exists.
- Do not expose privileged roles, especially `creator`, as normal assignable
team roles.
- Do not rely on checked-in secrets or production credentials.
## Users And Roles
| Role | Description | Key Access |
| --- | --- | --- |
| Public visitor | Views current awards content, winners, schedules, policies, and extras. | Public pages and read-only public APIs. |
| Participant | Submits nominations, clips, votes, or showact applications when enabled. | Public write APIs with rate limits and workflow gates. |
| Team member | Authenticated operator with scoped permissions. | Admin routes permitted by role and `TeamRolePermission` records. |
| Admin | Maintains seasons, categories, candidates, moderation, content, settings, and team operations. | Broad admin API access with audit expectations. |
| Creator | Bootstrap/owner-level identity. | Not a regular assignable UI role. |
## Tech Stack
| Area | Choice | Notes |
| --- | --- | --- |
| Frontend | Vue 3, Vite, TypeScript, Pinia, Tailwind CSS, PrimeVue, lucide icons | Source under `frontend/src`. |
| Backend | ASP.NET Core 8 minimal API | Entry point in `Backend/Program.cs`; endpoint groups under `Backend/Endpoints`. |
| Database | PostgreSQL with EF Core 8 and Npgsql | Migrations under `Backend/Migrations`. |
| Auth | Session-based team/admin auth plus Twitch OAuth support | Auth endpoints under `Backend/Endpoints/Auth*`; idle timeout is configurable in admin operational settings with a minimum of 3 hours. |
| Delivery | Gitea Actions, Docker Compose, Nginx-served frontend, ASP.NET API | Pipeline in `.gitea/workflows/ci.yaml`. |
## Runtime Environments
| Environment | Entry Point | Notes |
| --- | --- | --- |
| Local database | `localhost:5433` | Started with `docker compose -f docker-compose.dev.yml up -d`. |
| Local backend | `http://127.0.0.1:5084` | Run from `Backend/` with `ASPNETCORE_ENVIRONMENT=Development dotnet run --urls http://127.0.0.1:5084`. |
| Local frontend | Vite dev server, usually `http://localhost:5173` | Run from `frontend/` with `npm run dev`. |
| Production | `https://award.noveria.net` | Deployed by Gitea Actions on `main` pushes and manual dispatches. |
Default local database connection:
```text
Host=localhost;Port=5433;Database=vtuber_star_awards_dev;Username=vtsa_dev;Password=change-me-local-only
```
Non-local environments must provide `VTSA_POSTGRES` or
`ConnectionStrings__Postgres`.
## CI/CD
The Gitea workflow in `.gitea/workflows/ci.yaml`:
- rejects tracked build output, handoff artifacts, and obvious secret patterns;
- restores and builds the .NET backend;
- runs the frontend typecheck/build through `npm run build`;
- deploys `main` or manual dispatches to the production host;
- writes a PostgreSQL predeploy backup;
- applies EF Core migrations before restarting production services;
- verifies API health, database connectivity, pending migrations, and frontend
asset version metadata.
## Required Local Validation
Before pushing application changes, run:
```bash
cd frontend
npm run build
cd ..
dotnet build Backend/Backend.csproj --configuration Release
git diff --check
```
`npm run build` already runs `vue-tsc -b` before `vite build`.
Use manual API or browser validation for user-facing, auth, moderation,
settings, deployment, and responsive UI changes.
## Security And Configuration
- Use `Backend/appsettings.Development.json` only for local defaults.
- Keep `Backend/appsettings.json` production-safe and secret-free.
- Provide production secrets through environment variables.
- Configure explicit frontend CORS origins in non-development environments.
- Keep server-side authorization as the trusted boundary for admin routes.
- Keep public write endpoints rate-limited and validated.
## Documentation Map
| File | Purpose |
| --- | --- |
| [../README.md](../README.md) | Quick start, stack, validation, and deployment overview. |
| [../AGENTS.md](../AGENTS.md) | AI-agent and engineering execution contract. |
| [ARCHITECTURE.md](ARCHITECTURE.md) | System boundaries, module responsibilities, data flow, and security posture. |
| [CONVENTIONS.md](CONVENTIONS.md) | Coding, validation, review, and documentation standards. |
| [DECISIONS.md](DECISIONS.md) | Accepted architecture and operations decisions. |
| [CHECKLISTS.md](CHECKLISTS.md) | Quality gates for common change types. |
| [workflow.md](workflow.md) | Day-to-day delivery flow. |
| [branching.md](branching.md) | Branch and commit policy. |
| [release-process.md](release-process.md) | Release, deploy, smoke test, and rollback expectations. |
| [../DESIGN.md](../DESIGN.md) | Product visual language and UI implementation guidance. |
| [workflow-feedback-plan.md](workflow-feedback-plan.md) | Product feedback implementation plan for awards workflow improvements. |
## Open Questions
| Question | Why It Matters | Status |
| --- | --- | --- |
| Dedicated automated test project | Builds currently protect compile/type safety, but durable regression coverage is still limited. | Open |
| Production alerting owner and channels | Release docs can define checks, but ownership and paging policy are not encoded in the repo. | Open |
| Formal rollback drills | The pipeline writes backups, but restore rehearsal policy is not documented in code. | Open |
docs/PROMPTS.md
+154
View File
@@ -0,0 +1,154 @@
# Reusable Engineering Prompts
Use these prompts with [../AGENTS.md](../AGENTS.md),
[PROJECT.md](PROJECT.md), [ARCHITECTURE.md](ARCHITECTURE.md), and
[CONVENTIONS.md](CONVENTIONS.md).
## Feature Development
```text
Act as a senior engineer in the VTuber Star Awards repository.
Objective:
Implement <feature>.
Context:
- Product goal: <goal>
- Relevant docs: docs/PROJECT.md, docs/ARCHITECTURE.md, docs/CONVENTIONS.md
- Relevant files: <files>
Requirements:
- <requirement>
Non-goals:
- <non-goal>
Before coding:
- Inspect current frontend/backend behavior.
- Confirm the backend/admin source of truth.
- Ask concise questions if confidence is below 95%.
After coding:
- Run npm run build, dotnet build Backend/Backend.csproj --configuration Release,
git diff --check, and targeted manual checks.
- Summarize changed files, validation, and residual risk.
```
## Bug Investigation
```text
Investigate this bug before changing code.
Observed behavior:
<observed behavior>
Expected behavior:
<expected behavior>
Evidence:
<logs, screenshots, steps, URLs>
Task:
- Reproduce or reason from available evidence.
- Identify the most likely root cause.
- Locate affected frontend, backend, database, or deployment code.
- Propose the smallest maintainable fix.
- Implement only after the cause is understood.
- Add or describe regression validation.
```
## Admin UI Audit
```text
Audit this admin page for logical structure, all-at-a-glance clarity, duplicate
controls, permissions, and component-level behavior.
Scope:
<route or files>
Expectations:
- Preserve backend/admin truth.
- Split oversized Vue files where useful.
- Keep operational UI dense and scannable.
- Verify the page in browser when practical.
- Report validation and any remaining risks.
```
## Architecture Review
```text
Review the architecture of <system or module>.
Use:
- docs/PROJECT.md
- docs/ARCHITECTURE.md
- docs/DECISIONS.md
- Relevant source files
Focus on:
- Boundary clarity.
- Backend/admin source of truth.
- Data ownership.
- Failure modes.
- Security and authorization assumptions.
- Operational complexity.
- Maintainability over the next release cycle.
Return findings ordered by severity, then trade-offs and recommended ADR updates.
```
## Security Review
```text
Perform a security review of <scope>.
Focus on:
- Authentication.
- Authorization.
- Input validation.
- Output encoding.
- Secrets handling.
- Data exposure.
- Demo or seed behavior.
- Logging of sensitive data.
- SSRF, injection, XSS, CSRF, path traversal, and insecure deserialization where relevant.
For each finding include impact, exploitability, evidence, recommended fix, and
validation strategy.
```
## Documentation Update
```text
Improve documentation for <area>.
Goals:
- Make setup and maintenance easier.
- Preserve existing project-specific docs.
- Remove outdated or duplicated information.
- Add links to authoritative docs.
- Avoid placeholders and invented policy.
Validate:
- Links are correct.
- Commands match the repository.
- The document is useful to a new contributor.
```
## Release Verification
```text
Verify the latest release for VTuber Star Awards.
Scope:
<commit, PR, or change summary>
Check:
- CI/deploy status when available.
- https://award.noveria.net/api/health
- https://award.noveria.net/api/health/database
- Frontend asset version when relevant.
- One targeted public or authenticated workflow affected by the change.
Return confirmed facts, failures, and residual risk.
```
docs/branching.md
+76
View File
@@ -0,0 +1,76 @@
# Branching Strategy
This repository uses a simple trunk-based model with short-lived branches and
`main` as the deploy branch.
For delivery workflow, see [workflow.md](workflow.md). For PR expectations, see
[CONVENTIONS.md](CONVENTIONS.md#git-and-prs).
## Default Model
```mermaid
gitGraph
commit id: "main"
branch docs-change
checkout docs-change
commit id: "work"
commit id: "validate"
checkout main
merge docs-change
commit id: "deploy"
```
## Branch Types
| Type | Pattern | Purpose |
| --- | --- | --- |
| Feature | `feature/<short-description>` | New user-facing or system capability. |
| Bug fix | `fix/<short-description>` | Defect correction. |
| Refactor | `refactor/<short-description>` | Behavior-preserving structural work. |
| Documentation | `docs/<short-description>` | Documentation-only changes. |
| Chore | `chore/<short-description>` | Tooling or maintenance work. |
| AI-assisted local work | `codex/<short-description>` | Short-lived Codex branch when branch creation is useful. |
| Hotfix | `hotfix/<short-description>` | Urgent production correction. |
## Main Branch
`main` should remain deployable.
Minimum expectations:
- required checks pass;
- risky migrations and config changes are documented;
- production-impacting changes include validation evidence;
- direct pushes are limited to maintainers or automation.
## Feature Branches
- Keep scope focused.
- Rebase or merge from `main` according to reviewer preference.
- Delete branches after merge.
- Avoid stacking unrelated changes.
- Do not include generated build output or handoff artifacts.
## Commit Messages
Use short imperative subjects that describe the outcome.
Examples:
- `Fix team profile auth recovery`
- `Refine admin risk workspace`
- `Document engineering workflow`
Use a longer body when context, migration notes, or validation evidence is
important for future archaeology.
## Hotfixes
Hotfixes should restore production safely:
1. Branch from the deployed commit or current `main`.
2. Apply the smallest safe fix.
3. Validate the failing path.
4. Deploy.
5. Merge back to `main`.
6. Add follow-up cleanup or tests when the hotfix intentionally stayed narrow.
docs/release-process.md
+99
View File
@@ -0,0 +1,99 @@
# Release Process
This document defines release expectations for VTuber Star Awards.
For daily delivery flow, see [workflow.md](workflow.md). For branch policy, see
[branching.md](branching.md). For release checklist, see
[CHECKLISTS.md](CHECKLISTS.md#release).
## Release Principles
- Keep releases small when practical.
- Prefer repeatable automation over manual server edits.
- Validate before and after deployment.
- Review migration and configuration risk before deploy.
- Keep rollback or recovery options ready.
## Release Types
| Type | Description |
| --- | --- |
| Standard | Planned change deployed from `main` through the Gitea workflow. |
| Hotfix | Urgent production correction with the smallest safe change. |
| Documentation-only | Docs update that does not require runtime deployment validation. |
| Infrastructure | Runtime, hosting, Docker, database, network, or secret/config change. |
## Versioning
The frontend package version lives in `frontend/package.json`. The deploy
workflow appends build metadata and writes `VITE_BUILD_VERSION` plus
`VITE_BUILD_DATE` before building production assets.
## Readiness
Before releasing application changes:
- frontend build passes;
- backend Release build passes;
- `git diff --check` passes;
- migration operations are reviewed;
- target environment config and secrets are present;
- demo, seed, CORS, and production safety settings are understood;
- UI or API behavior has targeted validation evidence.
## Automated Deployment
The production deploy job in `.gitea/workflows/ci.yaml` runs on `main` pushes
and manual dispatches.
Pipeline responsibilities:
1. Verify repository hygiene.
2. Build backend and frontend.
3. Resolve version/build metadata.
4. Verify production host layout.
5. Sync repository contents to the production app directory.
6. Write frontend build metadata.
7. Build Docker images.
8. Write a PostgreSQL predeploy backup.
9. Apply EF Core migrations.
10. Recreate `api` and `web` services.
11. Verify API health, database connectivity, pending migrations, and frontend
assets.
## Smoke Tests
Minimum automated smoke signals:
- `https://award.noveria.net/api/health`
- `https://award.noveria.net/api/health/database`
- `pendingMigrations` is empty;
- frontend index serves current JS and CSS assets;
- JS asset contains expected build version metadata.
Add manual smoke checks for the changed workflow, especially for admin,
auth/permissions, voting, nomination, clip review, showact, sponsor, or content
management changes.
## Rollback And Recovery
Rollback planning should address:
- application artifact rollback or redeploy from a previous commit;
- database restore or forward-fix path;
- configuration rollback;
- disabling demo/seed/optional public features;
- communication of degraded public workflows.
If a migration is destructive or hard to reverse, document the recovery path
before deployment.
## Post-Release Review
After production-impacting releases:
- confirm health checks and relevant public/admin workflows;
- check for unexpected database migration state;
- record incidents or anomalies;
- update docs, checklists, or ADRs when release steps drift;
- add follow-up tests or runbooks for gaps found during release.
docs/workflow-feedback-plan.md
+23 -15
View File
@@ -10,7 +10,7 @@ Die erste grosse Aenderung sollte den Core Workflow stabilisieren: Nominierung,
Die wichtigsten Produktentscheidungen:
- Kategorien mit Viewer-Groessen werden als einzelne Kategorien pro Unterkategorie abgebildet, gruppiert ueber `GroupName`.
- Viewer duerfen pro Kategorie bis zu drei Stream- oder Kanal-Links nominieren.
- Viewer duerfen pro Hauptkategorie so viele Stream- oder Kanal-Links nominieren, wie in der Hauptkategorie als `MaxNomineesPerUser` konfiguriert ist. Der aktuelle Default bleibt drei.
- Eine Nominierung muss nicht fuer alle Kategorien abgegeben werden.
- Clip-Compilations werden nicht als Videodateien in der App gespeichert.
- Voting und Gewinnerbereiche nutzen externe YouTube-/Twitch-Links oder Embeds.
@@ -29,21 +29,23 @@ Das Dokument beschreibt pro Award-Kategorie drei Unterkategorien nach Viewer-Gro
Im aktuellen Datenmodell passt das am besten zu einzelnen `Category`-Datensaetzen pro Unterkategorie. Der uebergeordnete Award-Bereich, zum Beispiel `Gamer`, bleibt `GroupName`; die konkrete Unterkategorie wird `Name`, zum Beispiel `Hidden Star der Gamer`.
Damit entsteht kein paralleles Kategorienmodell. Admin-, Public- und Voting-Flows koennen weiter mit `CategoryId` arbeiten.
Damit entsteht kein paralleles Kategorienmodell. Admin- und Voting-Flows arbeiten weiter mit konkreten `CategoryId`s. Die Public-Nominierung wurde davon bewusst entkoppelt: User nominieren auf Hauptkategorie/`GroupName`, das passende Viewer-Tier wird danach ueber Tracker- und Admin-Review bestimmt.
Um die Pflege fuer Admins einfacher zu machen, bleibt die normale Hauptkategorie-Pflege erhalten, waehrend Unterkategorien zentral in einem Season-Modal konfiguriert werden. Ein Award-Bereich bleibt `GroupName`, Unterkategorien bleiben im Ausfuehrungsmodell normale `Category`-Datensaetze, werden aber aus der globalen Definition fuer alle Hauptkategorien synchron gehalten. Viewer-Range, Name, Slug und Reihenfolge werden pro Unterkategorie strukturiert gespeichert; ein separates Standard-Set wird nicht mehr angeboten.
### Nominierung
Das Feedback wuenscht pro Kategorie bis zu drei Nominierungen als Stream-/Kanal-Links. Namen sind nicht zwingend noetig, weil die Admins aus dem Link den finalen Kandidaten erstellen oder zuordnen koennen.
Das Feedback wuenscht pro Kategorie mehrere Nominierungen als Stream-/Kanal-Links. Namen sind nicht zwingend noetig, weil die Admins aus dem Link den finalen Kandidaten erstellen oder zuordnen koennen. Das konkrete Link-Limit kommt aus der Admin-Hauptkategorie.
Geplanter Zielzustand:
- Pro Kategorie koennen ein bis drei Links eingereicht werden.
- Doppelte Links innerhalb derselben Kategorie werden blockiert.
- Pro Hauptkategorie koennen ein bis zum konfigurierten Limit Links eingereicht werden.
- Doppelte Links innerhalb derselben Hauptkategorie werden blockiert.
- Leere Kategorien duerfen uebersprungen werden.
- Die Nominierungsoberflaeche wird wie ein Wizard aufgebaut: Kategorien links, Inhalt rechts, klare Weiter-Navigation.
- Clip-Einreichung wird aus dem Nominierungsformular entfernt oder deutlich getrennt, weil laut Feedback Clips in der Nominierungsphase eher Probleme verursachen.
Backendseitig existiert bereits eine passende Grundlage: `CreateNominationRequest` unterstuetzt mehrere `Nominations`, und die API verhindert doppelte Links innerhalb eines Requests. Die groesste Arbeit liegt daher im Public UI und in der Kommunikation der Regeln.
Backendseitig speichert `Nomination` jetzt `CategoryGroupName` statt eine Tier-Kategorie als primaere Zuordnung. `CategoryId` bleibt als nullable Legacy-Feld erhalten. Twitch-Links werden best-effort ueber TwitchTracker angereichert; Nicht-Twitch-Links bleiben erlaubt und werden im Admin-Review manuell einem Tier zugeordnet.
### Vorbereitung
@@ -52,6 +54,9 @@ Nach der Nominierungsphase prueft das Team die Nominierungen, zaehlt aus und kon
Geplanter Zielzustand:
- Admins sehen pro Review-Fall genug Signal, um Kandidaten zuzuordnen.
- Admins sehen Nominierungen gruppiert nach Hauptkategorie und Streamer-Identitaet.
- Das System zeigt Trackerstatus, durchschnittliche Viewer, Tier-Vorschlag und Tally der eindeutigen User.
- Beim Uebernehmen entsteht der Kandidat im vorgeschlagenen oder manuell gewaelten Tier.
- Final ausgewaehlte Nominierte bekommen einen Annahmestatus.
- Admins koennen pro Kandidat eine externe Clip-Compilation-URL pflegen.
- Es wird keine Upload-Infrastruktur fuer Videodateien gebaut.
@@ -85,7 +90,8 @@ Diese Regeln sollten nicht still im Public UI verschwinden, sondern als Admin-Gu
Geplanter Zielzustand:
- Admins koennen final maximal vier Nominierte pro Unterkategorie festlegen.
- Admins sehen Warnungen, wenn eine Person zu oft nominiert oder als Gewinner markiert wird.
- Streamer-Identitaet wird zentral ueber Plattform/Login modelliert, damit dieselbe Person ueber Kategorien hinweg erkannt werden kann.
- Admins sehen Warnungen oder Blocker, wenn eine Person zu oft nominiert oder als Gewinner markiert wird.
- Die App blockiert riskante finale Veroeffentlichungen oder verlangt eine bewusste Admin-Bestaetigung.
- Gewinner werden pro Unterkategorie bestimmt; bei Gleichstand oder Sonderfaellen entscheidet das Team manuell.
@@ -103,14 +109,14 @@ Folgeplanung:
### Phase 1: Public Nominierungs- und Voting-UX
Ziel: Der Public Flow entspricht dem Feedback, ohne zuerst das Datenmodell stark umzubauen.
Ziel: Der Public Flow entspricht dem Feedback: Nominierung auf Hauptkategorie, Voting weiter auf Tier-Kategorie.
Umsetzung:
- Nominierungsmodal zu einem Wizard umbauen.
- Pro Kategorie bis zu drei Link-Felder anbieten.
- Kategorien als linke Navigation anzeigen.
- Kategorien ohne Eingaben erlauben.
- Pro Hauptkategorie bis zum konfigurierten `MaxNomineesPerUser`-Limit Link-Felder anbieten.
- Hauptkategorien als linke Navigation anzeigen.
- Hauptkategorien ohne Eingaben erlauben.
- Doppelte Links clientseitig validieren und Backend-Fehler sauber anzeigen.
- Clip-Einreichung aus dem Nominierungsflow entfernen oder als separaten, weniger prominenten Flow belassen.
- Voting-Wizard um Weiter-Button und fehlende-Stimmen-Hinweis erweitern.
@@ -118,8 +124,8 @@ Umsetzung:
Akzeptanz:
- Eine Kategorie kann mit einem, zwei oder drei Links eingereicht werden.
- Doppelte Links in derselben Kategorie werden blockiert.
- Eine Hauptkategorie kann mit einem oder mehreren Links bis zum konfigurierten Limit eingereicht werden.
- Doppelte Links in derselben Hauptkategorie werden blockiert.
- Ein leerer Kategorienblock verhindert nicht das Absenden anderer Kategorien.
- Voting kann gespeichert und in derselben Phase erneut geaendert werden.
@@ -184,9 +190,9 @@ Akzeptanz:
### Beibehalten
- `CategoryId` bleibt die zentrale Einheit fuer Nominierung und Voting.
- `CategoryId` bleibt die zentrale Einheit fuer Voting, Kandidaten und Gewinner.
- `GroupName` bleibt die Gruppierung fuer uebergeordnete Award-Bereiche.
- Die Nominierungs-API bleibt grundsaetzlich erhalten.
- Die Nominierungs-API bleibt grundsaetzlich erhalten, nimmt aber `CategoryGroupName` als neues Zielfeld; `CategoryId` bleibt Legacy-Fallback.
- Die Voting-API bleibt grundsaetzlich erhalten.
- Wiederholtes Vote-Speichern bleibt erlaubt und wird als Bearbeiten behandelt.
@@ -198,6 +204,8 @@ Akzeptanz:
- Plattform
- optionaler Embed-Status
- Admin-Review braucht Statusinformationen fuer final ausgewaehlte Nominierte.
- `Nomination` speichert Tracker-/Review-Metadaten: `ResolvedChannel`, `ResolvedPlatform`, `AvgViewers`, `SuggestedCategoryId`, `StreamerIdentityId`, `TrackerStatus`.
- `StreamerIdentity` wird als eigene Entity fuer Plattform/Login/Normalisierung eingefuehrt.
- Gewinnerverwaltung braucht Guards fuer interne Regeln, inklusive "maximal ein Gewinnerplatz" und "Clip-Link fuer Gewinner erforderlich".
### Nicht bauen
docs/workflow.md
+124
View File
@@ -0,0 +1,124 @@
# Development Workflow
This document defines the default path from idea to released change.
For branch policy, see [branching.md](branching.md). For release execution, see
[release-process.md](release-process.md). For task quality gates, see
[CHECKLISTS.md](CHECKLISTS.md).
## Workflow Overview
```mermaid
flowchart LR
Idea["Idea, bug, or feedback"]
Clarify["Clarify scope"]
Plan["Plan or ADR"]
Implement["Implement"]
Validate["Validate"]
Review["Review"]
Merge["Merge"]
Release["Release"]
Learn["Update docs/checklists"]
Idea --> Clarify
Clarify --> Plan
Plan --> Implement
Implement --> Validate
Validate --> Review
Review --> Merge
Merge --> Release
Release --> Learn
```
## 1. Clarify Scope
Before implementation:
- restate the objective in engineering terms;
- identify affected public, admin, backend, database, or deployment surfaces;
- confirm acceptance criteria and non-goals;
- identify security, authorization, migration, data-loss, or live-production
risk;
- ask concise questions when ambiguity affects important behavior.
## 2. Inspect Existing Context
Read the relevant source and docs before editing:
- [PROJECT.md](PROJECT.md) for runtime and product facts;
- [ARCHITECTURE.md](ARCHITECTURE.md) for boundaries;
- [CONVENTIONS.md](CONVENTIONS.md) for coding standards;
- [DECISIONS.md](DECISIONS.md) for durable trade-offs;
- [../DESIGN.md](../DESIGN.md) for UI work;
- feature plans such as [workflow-feedback-plan.md](workflow-feedback-plan.md)
when the task builds on planned product feedback.
## 3. Plan The Change
Use a lightweight plan for non-trivial changes. Create or update an ADR when
the change affects:
- architecture style or module boundaries;
- data ownership or public contracts;
- authentication, authorization, or security posture;
- deployment strategy, migrations, or long-term operating cost.
## 4. Implement
Implementation expectations:
- keep changes focused and reviewable;
- follow existing frontend/backend patterns;
- split large Vue surfaces into smaller components or composables;
- keep backend/admin data authoritative for public behavior;
- avoid unrelated refactors unless needed for the requested change;
- preserve user changes in a dirty worktree.
## 5. Validate
Default validation:
```bash
cd frontend
npm run build
cd ..
dotnet build Backend/Backend.csproj --configuration Release
git diff --check
```
Add targeted validation by risk:
- API checks for backend behavior;
- authenticated checks for admin/team/permission changes;
- browser checks for visible UI changes;
- responsive geometry checks for layout work;
- database health and migration checks for schema changes;
- live checks only for release or explicitly live-scoped work.
When frontend and backend are both actively used for local verification, keep
them running as a pair or shut both down together.
## 6. Review
Review should answer:
- Does the change solve the stated problem?
- Does it preserve backend/admin truth?
- Is authorization enforced at the trusted boundary?
- Are migrations and deployment risk understood?
- Are docs and validation sufficient for the risk?
## 7. Merge And Release
`main` is the production deployment branch. Pushes to `main` run CI and deploy
when the workflow conditions match. Follow [release-process.md](release-process.md).
## 8. Learn
After meaningful releases, regressions, or repeated review feedback:
- update docs or checklists;
- add or update ADRs;
- add regression coverage when practical;
- record follow-up work where the repo exposes an operational or test gap.