Initial commit

2025-07-07 13:39:46 +01:00
commit cfa2eff6ef
69 changed files with 70452 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,135 @@
+# 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** – browse every craft with filters, icons, ingredients, HQ yields, and cross-links to inventory.
+* **Inventory Manager** – compact grid with tooltips, duplicate highlighting, scroll badges, and wiki links.
+* **Item Explorer** – searchable catalogue with dynamic sub-tabs for each item type.
+* **Spell Database** – scroll parsing auto-populates a `spells` table with job-level learn data.
+* **Responsive UI** – desktop / tablet / mobile layouts.
+* **Database-backed** – PostgreSQL stores normalised recipe / item / inventory / spells data.
+* **Automation Scripts** – Python ETL & loaders for recipes and spells.
+
+## 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! ✨