# Final Fantasy XI Item Browser – Project Plan

## Overview
This web application lets a player:
1. Browse **their own inventory** (split into tabs by `storage_type`).
2. Browse **all items** in the database (split into tabs by `type_description`).
3. Click any item to view rich details (stats, flags, descriptions, icons).

## Tech Stack
| Layer   | Choice                     | Reason |
| ------- | -------------------------- | ------ |
| Backend | **Python 3 + FastAPI**     | Minimal boilerplate, async support, automatic OpenAPI docs. |
| DB      | **PostgreSQL** (existing)  | Already hosts `ffxi_items` schema. |
| ORM     | **SQLAlchemy 2 + asyncpg** | Rich modelling, async queries. |
| Front-end | **React + TypeScript**      | Component ecosystem & type safety. |
| UI Kit | **Material-UI (MUI)**       | Ready-made tabs, tables, dialogs. |
| Data-fetch | **React-Query**            | Caching & pagination out of the box. |
| DevOps | **Docker Compose**          | Consistent local/dev deployments. |

## Data Model Notes
- Core tables: `inventory`, every `*_items` table.
- Create a **view** `all_items` that UNIONs all item tables with common columns plus `type_description`.
- Suggested indexes:
  - `inventory(character_name, storage_type)`
  - Primary keys on item tables already exist (`id`).

## API Endpoints (FastAPI)
| Method | Path | Purpose |
| ------ | ---- | ------- |
| `GET` | `/api/metadata` | Lists distinct `storage_type` and `type_description` for building tabs. |
| `GET` | `/api/inventory/{character}` | Items grouped by `storage_type`. Query params: `storage_type`, `search`, `page`. |
| `GET` | `/api/items` | Pageable list across all items. Query params: `type`, `search`, `page`, `page_size`. |
| `GET` | `/api/items/{id}` | Detailed single-item payload (joins correct table for extra columns). |

## Front-End Pages
### 1. Inventory Viewer
- Tabs dynamically rendered from `/api/metadata.storage_types`.
- Each tab: 8×10 grid (80 cells) of item icons with quantity badge; implements lazy loading as the user scrolls.
- Search bar filters rows client-side.
- Icon click ⇒ `ItemDetailPanel` opens at right (drawer style) and lazy-loads `/api/items/{id}` if not already cached.

### 2. Item Explorer
- Tabs from `/api/metadata.type_descriptions`.
- Each tab fetches `/api/items?type=...` with pagination.
- Displayed as the same 8×10 icon grid; hover shows name, click opens detail panel. (Optional toggle to list view with extra stats – e.g., `damage`, `defense`).

### Shared Components
- `ItemIcon` – resolves icon_id to asset URL.
- `ItemDetailDrawer` – generic detail viewer with conditional sections.
- `PaginatedTable` – wrapper around MUI DataGrid + React-Query pagination.

## Development Roadmap
1. **Repo Setup**
   - Create backend & frontend directories.
   - Add `Dockerfile` for backend and `docker-compose.yml` (API container + optional postgres proxy) using environment variables from `db.conf` via `.env`.
2. **Backend MVP**
   - SQLAlchemy models & pydantic schemas.
   - Implement `/metadata`, `/items` (basic), `/inventory/{character}`.
   - Unit tests (pytest + httpx).
3. **Frontend MVP**
   - CRA/Vite + TS + MUI scaffold.
   - Fetch & display `/metadata`; build tabs; simple grids.
4. **Detail Drawer & Search**
   - Implement `ItemDetailDrawer`.
   - Add search fields and React-Query debounced queries.
5. **Refinement**
   - Responsive layout tweaks, icons, loading/error states.
   - Optional auth groundwork (JWT).
6. **Deployment**
   - Build Docker images; push to registry / run on VPS or Netlify (frontend) + Fly.io/Render (API).

## Next Steps
- Confirm tech stack and roadmap with stakeholders.  
- Scaffold backend (`fastapi`, `sqlalchemy`) first to stabilise data contract.  
- Implement `/api/metadata` and seed small React prototype to validate UI.

---
Generated: 2025-07-02