# VTuber Star Awards

Production monorepo for the VTuber Star Awards platform.

## Stack

- Frontend: Vue 3, Vite, Pinia, Tailwind CSS, PrimeVue, lucide icons
- Backend: ASP.NET Core 8, EF Core 8, PostgreSQL
- Delivery: Gitea Actions, Docker Compose, Nginx-served frontend, ASP.NET API

## Repository Structure

- `frontend/` Vue application and public assets
- `Backend/` ASP.NET Core API, EF Core migrations, services and endpoints
- `.gitea/workflows/ci.yaml` build, hygiene, deploy and live verification pipeline
- `docs/PROJECT.md` project facts, runtime expectations and documentation map
- `docs/ARCHITECTURE.md` system structure, source-of-truth and deployment flow
- `docs/CONVENTIONS.md` coding, validation, review and documentation standards
- `docs/DECISIONS.md` durable architecture and operations decisions
- `docker-compose.dev.yml` optional local PostgreSQL container for development

Generated archives, prototype exports, Word handoff files and local document-update scripts are intentionally ignored and should not be committed.

## Engineering Docs

Start with:

- [AGENTS.md](AGENTS.md) for the engineering execution contract.
- [docs/PROJECT.md](docs/PROJECT.md) for project/runtime facts.
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for system boundaries.
- [docs/CONVENTIONS.md](docs/CONVENTIONS.md) for coding and validation standards.
- [docs/CHECKLISTS.md](docs/CHECKLISTS.md) for quality gates.
- [DESIGN.md](DESIGN.md) for UI and product design guidance.

## Local Development

Start the database:

```bash
docker compose -f docker-compose.dev.yml up -d
```

Run the backend:

```bash
cd Backend
dotnet restore
dotnet ef database update
ASPNETCORE_ENVIRONMENT=Development dotnet run --urls http://127.0.0.1:5084
```

Run the frontend:

```bash
cd frontend
npm ci
cp .env.example .env
npm run dev
```

Default development database:

```text
Host=localhost;Port=5433;Database=vtuber_star_awards_dev;Username=vtsa_dev;Password=change-me-local-only
```

The same defaults live in `Backend/appsettings.Development.json`. For non-local environments, set `VTSA_POSTGRES` or `ConnectionStrings__Postgres`.

## Useful Endpoints

- Public API: `/api/public/*`
- Admin dashboard: `/api/admin/dashboard`
- Admin moderation and risk workflows: `/api/admin/*`
- Sessions and auth: `/api/auth/*`
- App health: `/api/health`
- Database health and migrations: `/api/health/database`

Development admin session example:

```bash
curl -X POST http://localhost:5084/api/auth/dev-login \
  -H "Content-Type: application/json" \
  -d '{"twitchUserId":"jayuhime_demo","displayName":"Jayuhime","role":"admin"}'
```

## Validation

Run these before pushing application changes:

```bash
cd frontend
npm run build

cd ..
dotnet build Backend/Backend.csproj --configuration Release
git diff --check
```

## Deployment

Pushes to `main` run `.gitea/workflows/ci.yaml`.

The pipeline:

1. Checks repository hygiene.
2. Builds the backend and frontend.
3. Syncs the repository to the production host.
4. Builds and recreates the Docker Compose `api` and `web` services.
5. Writes a PostgreSQL predeploy backup.
6. Applies EF Core migrations.
7. Verifies live health, database connectivity and frontend assets.

Production runs at `https://award.noveria.net`.

See [docs/release-process.md](docs/release-process.md) for release readiness,
smoke tests and rollback expectations.
