136 lines
4.0 KiB
Markdown
136 lines
4.0 KiB
Markdown
# 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! ✨
|