Initial commit

plan.md

@@ -0,0 +1,78 @@
+# 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