Skip to content

Add Restocking tab with budget slider, demand recommendations, and su… #117

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sgorinta-deloitte wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add Restocking tab with budget slider, demand recommendations, and su… #117

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 72 additions & 57 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,74 +1,89 @@
# CLAUDE.md

Factory Inventory Management System Demo with GitHub integration - Full-stack application with Vue 3 frontend, Python FastAPI backend, and in-memory mock data (no database).
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Critical Tool Usage Rules
Factory Inventory Management System — full-stack demo app with Vue 3 frontend, Python FastAPI backend, and in-memory mock data (no database).

### Subagents
Use the Task tool with these specialized subagents for appropriate tasks:
## Commands

- **vue-expert**: Use for Vue 3 frontend features, UI components, styling, and client-side functionality
- Examples: Creating components, fixing reactivity issues, performance optimization, complex state management
- **MANDATORY RULE: ANY time you need to create or significantly modify a .vue file, you MUST delegate to vue-expert**
- **code-reviewer**: Use after writing significant code to review quality and best practices
- **Explore**: Use for understanding codebase structure, searching for patterns, or answering questions about how components work
- **general-purpose**: Use for complex multi-step tasks or when other agents don't fit

### Skills
- **backend-api-test** skill: Use when writing or modifying tests in `tests/backend` directory with pytest and FastAPI TestClient
**Backend** (from `server/`):
```bash
uv sync # Install dependencies
uv run python main.py # Start server on http://localhost:8001
```

### MCP Tools
- **ALWAYS use GitHub MCP tools** (`mcp__github__*`) for ALL GitHub operations
- Exception: Local branches only - use `git checkout -b` instead of `mcp__github__create_branch`
- **ALWAYS use Playwright MCP tools** (`mcp__playwright__*`) for browser testing
- Test against: `http://localhost:3000` (frontend), `http://localhost:8001` (API)
**Frontend** (from `client/`):
```bash
npm install && npm run dev # Start dev server on http://localhost:3000
npm run build # Production build to client/dist/
```

## Stack
- **Frontend**: Vue 3 + Composition API + Vite (port 3000)
- **Backend**: Python FastAPI (port 8001)
- **Data**: JSON files in `server/data/` loaded via `server/mock_data.py`
**Tests** (from `tests/`):
```bash
uv run pytest backend/ -v # All 51 tests
uv run pytest backend/test_inventory.py -v # Single file
uv run pytest --cov=../server --cov-report=html # With coverage
```

## Quick Start
**Windows note:** `scripts/start.sh` is macOS/Linux only. Start backend and frontend in separate terminals manually.

```bash
# Backend
cd server
uv run python main.py
## Architecture

# Frontend
cd client
npm install && npm run dev
```
client/src/
api.js # Centralized Axios client — all HTTP calls go here
composables/ # Shared state: useFilters.js (4-filter system), useAuth.js, useI18n.js
views/ # Page components (Dashboard, Inventory, Orders, Spending, Demand, Reports)
components/ # Reusable UI (FilterBar, *DetailModal, TasksModal, ProfileMenu)

server/
main.py # All FastAPI endpoints + apply_filters() + filter_by_month()
mock_data.py # Loads server/data/*.json into memory at startup
data/*.json # Source of truth — inventory, orders, spending, demand_forecasts, backlog_items
```

Data flow: Vue filter composable → `api.js` query params → FastAPI → in-memory filtering → Pydantic response → Vue computed properties.

## Critical Tool Usage

- **vue-expert subagent**: MANDATORY for any `.vue` file creation or significant modification
- **code-reviewer subagent**: Use after writing significant code
- **backend-api-test skill**: Use when writing/modifying tests in `tests/backend/`
- **GitHub MCP** (`mcp__github__*`): Use for ALL GitHub operations (exception: local branch creation with `git checkout -b`)
- **Playwright MCP** (`mcp__playwright__*`): Use for browser testing against `http://localhost:3000` / `http://localhost:8001`

## Key Patterns

**Filter System**: 4 filters (Time Period, Warehouse, Category, Order Status) apply to all data via query params
**Data Flow**: Vue filters → `client/src/api.js` → FastAPI → In-memory filtering → Pydantic validation → Computed properties
**Reactivity**: Raw data in refs (`allOrders`, `inventoryItems`), derived data in computed properties

## API Endpoints
- `GET /api/inventory` - Filters: warehouse, category
- `GET /api/orders` - Filters: warehouse, category, status, month
- `GET /api/dashboard/summary` - All filters
- `GET /api/demand`, `/api/backlog` - No filters
- `GET /api/spending/*` - Summary, monthly, categories, transactions

## Common Issues
1. Use unique keys in v-for (not `index`) - use `sku`, `month`, etc.
2. Validate dates before `.getMonth()` calls
3. Update Pydantic models when changing JSON data structure
4. Inventory filters don't support month (no time dimension)
5. Revenue goals: $800K/month single, $9.6M YTD all months

## File Locations
- Views: `client/src/views/*.vue`
- API Client: `client/src/api.js`
- Backend: `server/main.py`, `server/mock_data.py`
- Data: `server/data/*.json`
- Styles: `client/src/App.vue`
**Filter system**: 4 filters — Time Period, Warehouse, Category, Order Status — passed as query params to every endpoint. Filter values of `'all'` are skipped. Inventory endpoints do **not** support month filtering (no time dimension on inventory data).

**Backend filtering**:
```python
# Never mutate global data — filter on copies
if warehouse and warehouse != 'all':
results = [r for r in results if r.get('warehouse') == warehouse]
```

**Date/quarter filtering**: Supports `2025-01` (month) and `Q1-2025` (quarter) formats. Parse safely and handle null dates.

**Frontend reactivity**:
- Raw data in `ref()`, derived data in `computed()` — never the reverse
- Always use unique IDs (not array index) as `v-for` keys
- Validate dates before calling `.getMonth()`: `if (!isNaN(date.getTime()))`
- In `<script>`: `.value` required. In `<template>`: automatic unwrapping.

**Adding a backend endpoint**:
1. Define Pydantic model → add route → filter on copy of data → return typed response → write test in `tests/backend/`

**Adding data**: Update JSON in `server/data/` → update Pydantic model if structure changed → restart server.

## Known Constants

- Revenue goals: $800K/month (single warehouse), $9.6M YTD (all months)
- API docs: http://localhost:8001/docs
- Mock data scope: Circuit Boards, Sensors, Actuators, Controllers across 12 months

## Design System
- Colors: Slate/gray (#0f172a, #64748b, #e2e8f0)
- Status: green/blue/yellow/red
- Charts: Custom SVG, CSS Grid for layouts

- Colors: Slate/gray (`#0f172a`, `#64748b`, `#e2e8f0`); status uses green/blue/yellow/red
- Charts: Custom SVG with CSS Grid layouts
- No emojis in UI
Loading