# MOG APP – Final Fantasy XI Crafting & Inventory Companion

> A full-stack web application that helps crafters and adventurers manage items, discover recipes, and plan gear sets for **FFXI**.

---

## Contents

1. [Key Features](#key-features)
2. [Project Structure](#project-structure)
3. [Prerequisites](#prerequisites)
4. [Getting Started](#getting-started)
5. [Scripts & ETL Pipeline](#scripts--etl-pipeline)
6. [Database Schema](#database-schema)
7. [Development Tasks](#development-tasks)
8. [Contributing](#contributing)

---

## Key Features

* **Crafting Recipes** – colour-coded craft tabs (woodworking brown, smithing grey, etc.), full filters, icons, ingredients, HQ yields, and cross-links to inventory.
* **Desynthesis Recipes** – quickly find items to break down. Craft-coloured tabs and new "Owned / Partially owned" filters work off **ingredient ownership**, just like crafting recipes.
* **Inventory Manager** – grid view with sorting (slot ▶ default, name, type), duplicate-item indicator (orange bar on top), tooltips, quantity badges, and direct wiki links.
* **Item Explorer** – fast, fuzzy search across all items with type sub-tabs and recipe cross-navigation.
* **Item Detail Dialog** – centred modal with icon, description, usage breakdown, and craft-coloured section headers.
* **Responsive UI** – desktop / tablet / mobile layouts with dropdown storage selector on narrow screens.
* **Database-backed** – PostgreSQL stores normalised recipe / item / inventory / spells data.
* **Automation Scripts** – Python ETL & loaders for recipes and spells, plus scroll → spell parser.

## Project Structure

```
MOG APP/
├─ datasets/            # Raw .txt recipe dumps and generated *_v2.csv files
├─ scripts/             # Python ETL, DB loaders, helper tools
│  └─ README.md         # Detailed script docs
├─ frontend/            # React + TypeScript source (Vite)
├─ TODO.md              # High-level roadmap / feature backlog
├─ README.md            # ← you are here
└─ db.conf              # Local DB credentials (not committed)
```

## Prerequisites

| Stack | Version | Notes |
|-------|---------|-------|
| **Node.js** | ≥ 18 | Front-end build & dev server |
| **npm** / **pnpm** / **yarn** | latest | Your choice – commands below use **npm** |
| **Python** | ≥ 3.9 | ETL scripts, CSV → DB loaders |
| **PostgreSQL** | ≥ 13 | Stores items / recipes / inventory |

Ensure `db.conf` exists in the root with:

```ini
PSQL_HOST=localhost
PSQL_PORT=5432
PSQL_USER=ffxi
PSQL_PASSWORD=ffxi
PSQL_DBNAME=ffxi
```

## Getting Started

### 1. Clone & Install Front-end

```bash
# From project root
cd frontend
npm install                # or yarn / pnpm
npm run dev                # Vite dev server ➜ http://localhost:5173/
```

### 2. Generate Recipe CSVs

```bash
# Still in project root
cd scripts
python recipes_to_csv_v2.py --all   # parses all .txt dumps
```

### 3. Load Recipes into PostgreSQL

```bash
python load_recipes_v2_to_db.py     # loads all *_v2.csv into recipes_* tables
```

The console will display counts per craft.

### 4. Start the Front-end Again (if not already running)

Front-end auto-detects DB content via API (to-be-implemented backend) or mocked data.

## Scripts & ETL Pipeline

Scripts are documented in `scripts/README.md`. Highlights:

| Script | Purpose |
|--------|---------|
| `recipes_to_csv_v2.py` | Parse raw craft files to structured CSV (all crafts when no arg). |
| `load_recipes_v2_to_db.py` | Create `recipes_<craft>` tables and bulk-load CSVs. |
| `populate_spells_from_scrolls.py` | Extract scroll data & upsert into `spells` table. |

## Database Schema

Minimal snapshot (simplified):

```
recipes_<craft>
├─ id SERIAL PK
├─ category TEXT
├─ level INT
├─ subcrafts JSONB
├─ name TEXT
├─ crystal TEXT
├─ key_item TEXT
├─ ingredients JSONB
└─ hq_yields JSONB
```

Additional tables (items, inventory, etc.) will be added as features mature.

## Development Tasks

See `TODO.md` for the current backlog including UI polish, inventory enhancements, cross-section links, and stretch goals (Quest advisor, Gear build planner, AI assistant).

## Contributing

Pull requests are welcome! Please:

1. Fork ➜ feature branch ➜ PR.
2. Follow existing code style (Black for Python, Prettier/ESLint for TS).
3. Update / add tests where relevant.
4. Check off items in `TODO.md` when implemented.

Enjoy and may your synths never break! ✨