253 lines
4.1 KiB
Markdown
253 lines
4.1 KiB
Markdown
# **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` |