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
2. Project Structure
3. Prerequisites
4. Getting Started
5. Scripts & ETL Pipeline
6. Database Schema
7. Development Tasks
8. 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.
• 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:

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

Getting Started

1. Clone & Install Front-end

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

2. Generate Recipe CSVs

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

3. Load Recipes into PostgreSQL

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! ✨