Mog-Squire/plan.md

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