AOW4/docs/agent.md.md

agent.md — Game Reference Platform Agent Specification

Purpose

This agent defines the architecture, responsibilities, and operational expectations for the Game Reference, a Blazor‑based website to host:

• Build calculators

• Learning documentation

• Game data reference libraries

The web app is designed for modularity, data portability, and long‑term maintainability, with a roadmap toward self‑hosted offline builds.

---

High‑Level Responsibilities

• Data ingestion: Regularly update game data sets from external sources (official APIs, community wikis, manual imports).

• Data persistence: Store all game data, user builds, and metadata in PostgreSQL.

• Web delivery: Serve interactive Blazor WebAssembly or Server pages for calculators and documentation.

• Automation: Validate functionality through NUnit unit tests and Selenium UI automation.

• Containerization: Package each game site as a Docker image for deployment or local use.

• Offline mode: Allow users to download the site and run it with their own local PostgreSQL instance.

---

System Architecture

Platform Overview

• Frontend: Blazor WebAssembly or Blazor Server (project‑specific choice)

• Backend: ASP.NET Core minimal APIs or controllers

• Database: PostgreSQL (hosted or local)

• Containerization: Docker Compose for multi‑service orchestration

• Testing: NUnit + Selenium (C#)

• CI/CD: GitHub Actions or Azure DevOps (future)

---

Data Update Strategy

Data ingestion may occur via:

• Manual imports

• Official game APIs

• Community‑maintained datasets

The agent must support:

• Scheduled updates

• Versioning of game data

• Rollback capability

• Validation before ingestion

---

Docker Architecture

Container Layout

Each game site includes:

• blazor-app container

• postgres container (optional for production, required for offline mode)

• data-import container (optional automation)

Local Development

Users can run:

docker compose up --build

This launches:

• Blazor site

• Local PostgreSQL

• Optional admin tools (pgAdmin)

---

Testing Strategy

NUnit Unit Tests

Unit tests cover:

• Data models

• Calculation logic

• API endpoints

• Data ingestion validation

Tests live in:

/tests/GameSlop.Tests.Unit

Selenium UI Automation

A separate C# Selenium project validates:

• Page load behavior

• Calculator functionality

• Navigation flow

• Form inputs

• Error handling

Tests live in:

/tests/GameSlop.Tests.UI

Automation runs against:

• Local Docker environment

• Staging environment

• Production (read‑only tests)

---

Offline Mode (Long‑Term Goal)

Users will be able to:

1. Download a packaged version of a game site.

2. Run it locally via Docker.

3. Use a local PostgreSQL instance.

4. Save builds offline.

5. Import/export builds as JSON.

This requires:

• Self‑contained Docker Compose bundles

• Local EF migrations

---

Agent Responsibilities

Build Calculators

The agent must:

• Load game data dynamically

• Apply calculation logic (damage, stats, modifiers)

• Support multiple build variants

• Allow saving/loading builds from PostgreSQL

Documentation Engine

The agent must:

• Render markdown or rich text

• Support versioned documentation

Data Sync

The agent must:

• Detect outdated data

• Fetch new data

• Validate and sanitize

• Apply migrations if needed

Observability

The agent should log:

• Data ingestion events

• User build saves

• Errors and exceptions

• Performance metrics

---

Contributor Guidelines

• Follow C# coding standards

• Use EF migrations for schema changes

• Write NUnit tests for all logic

• Add Selenium tests for UI changes

• Document new features in /docs