# Star Citizen Inventory

A read-only item inventory website for Star Citizen players, built from the
[scunpacked](https://github.com/richardthombs/scunpacked) game data (mirrored at
[StarCitizenWiki/scunpacked-data](https://github.com/StarCitizenWiki/scunpacked-data)).

Ships, ship equipment, and FPS items are browsable with search, manufacturer /
type / size filters, pagination, and a detail view per item.

## Stack

| Piece    | Tech                                   | Role                                            |
| -------- | -------------------------------------- | ----------------------------------------------- |
| backend  | FastAPI (python:3.12-slim container)   | Serves normalized scunpacked JSON over `/api/v1` |
| frontend | nginx:1.27-alpine + vanilla JS/CSS     | Inventory UI; proxies `/api/` and `/healthz`      |
| deploy   | Ansible + Podman (containers.podman)   | Builds images and runs the two containers       |

The backend image downloads the full scunpacked dataset (~83 MB) at build time,
so no database is needed — the inventory is read-only game data.

## Layout

```
playbook.yml               Ansible deployment (hosts: webservers)
inventory.ini              Inventory (localhost + commented remote example)
trade-hub/
  podman-compose.yml       Local two-service stack (backend + frontend)
  backend/                 FastAPI app, tests, data fetch script, Dockerfile
  frontend/                nginx config + static inventory UI
```

## Run locally with Podman Compose

```bash
cd trade-hub
podman-compose up -d --build
# or: podman compose up -d --build
```

Then open http://localhost:8080

## Deploy with Ansible

Deploys to every host in the `webservers` group (defaults to localhost):

```bash
ansible-playbook playbook.yml
```

To deploy to a remote server, edit `inventory.ini`:

```ini
[webservers]
server1 ansible_host=203.0.113.10 ansible_user=deploy
```

Then run the same command from this directory. The playbook:

1. installs podman if missing,
2. removes the legacy `my-apache-server` container if present,
3. builds `sc-inventory-backend` / `sc-inventory-frontend` images (skipped when
   they already exist; set `-e force_rebuild=true` to rebuild),
4. creates the `sc-inventory` podman network,
5. runs both containers (only the frontend publishes a port: 8080),
6. verifies `http://localhost:8080/healthz` returns 200.

## Verify

```bash
curl -fsS http://localhost:8080/healthz
curl -fsS http://localhost:8080/api/v1/stats
curl -fsS "http://localhost:8080/api/v1/items?search=carrack"
```

## Backend development

```bash
cd trade-hub/backend
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt -r requirements-dev.txt
.venv/bin/python -m pytest tests/ -q          # 19 tests
DATA_DIR=./data/samples .venv/bin/uvicorn main:app --port 8000
```

- `data/samples/` — small real-schema subset for local dev/tests
- `scripts/fetch_data.py` — downloads the full dataset (used by the Dockerfile)

## API

```
GET /healthz
GET /api/v1/stats
GET /api/v1/manufacturers
GET /api/v1/items?category=&search=&manufacturer=&type=&size=&page=&page_size=
GET /api/v1/items/{class_name}
```

Data source: scunpacked — unofficial Star Citizen fansite content, not
affiliated with Cloud Imperium Games.