vtuber-awards/docs/PROJECT.md

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. For engineering standards, see 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:

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:

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	Quick start, stack, validation, and deployment overview.
../AGENTS.md	AI-agent and engineering execution contract.
ARCHITECTURE.md	System boundaries, module responsibilities, data flow, and security posture.
CONVENTIONS.md	Coding, validation, review, and documentation standards.
DECISIONS.md	Accepted architecture and operations decisions.
CHECKLISTS.md	Quality gates for common change types.
workflow.md	Day-to-day delivery flow.
branching.md	Branch and commit policy.
release-process.md	Release, deploy, smoke test, and rollback expectations.
end-to-end-smoke.md	Repeatable local/browser smoke path for nomination, voting, winners, and permissions.
maintainability-backlog.md	Large-file and boundary risks to reduce in focused refactor passes.
../DESIGN.md	Product visual language and UI implementation guidance.
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