# **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`