79 lines
3.8 KiB
Markdown
79 lines
3.8 KiB
Markdown
# 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
|