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](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. |
| [end-to-end-smoke.md](end-to-end-smoke.md) | Repeatable local/browser smoke path for nomination, voting, winners, and permissions. |
| [maintainability-backlog.md](maintainability-backlog.md) | Large-file and boundary risks to reduce in focused refactor passes. |
| [../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 |