From 16f2d32f4aa11def3c417910cd37f300fd90fe76 Mon Sep 17 00:00:00 2001 From: Moukhtar Nsouli Date: Thu, 13 Aug 2026 10:51:43 -0700 Subject: [PATCH 1/5] Step 6: Add budget-based restocking feature - Backend: Add /api/restocking/recommendations endpoint (greedy budget-filling algorithm) - Backend: Add /api/restocking/orders endpoint with order creation and validation - Frontend: Create Restocking.vue component with budget slider, recommendations table - Frontend: Add real-time budget tracking, quantity adjustments, order submission - Frontend: Add i18n support (English/Japanese) for restocking UI - Add ARCHITECTURE.html documenting system design - Add WORKSHOP_GUIDE.md tracking workshop progress - Update CLAUDE.md with code style guidelines Co-Authored-By: Claude Haiku 4.5 --- ARCHITECTURE.html | 552 ++++++++++++++++++++++++++ CLAUDE.md | 4 + WORKSHOP_GUIDE.md | 158 ++++++++ client/src/App.vue | 3 + client/src/api.js | 10 + client/src/locales/en.js | 29 ++ client/src/locales/ja.js | 29 ++ client/src/main.js | 2 + client/src/views/Restocking.vue | 675 ++++++++++++++++++++++++++++++++ server/main.py | 123 +++++- 10 files changed, 1584 insertions(+), 1 deletion(-) create mode 100644 ARCHITECTURE.html create mode 100644 WORKSHOP_GUIDE.md create mode 100644 client/src/views/Restocking.vue diff --git a/ARCHITECTURE.html b/ARCHITECTURE.html new file mode 100644 index 000000000..e19038688 --- /dev/null +++ b/ARCHITECTURE.html @@ -0,0 +1,552 @@ + + + + + + Factory Inventory Management - Architecture Guide + + + +
+
+

๐Ÿญ Factory Inventory Management System

+

System Architecture & Technical Overview

+
+ +
+ +
+

System Architecture

+

This application is built with a classic frontend-backend separation design. Here's how it works:

+ +
+
+
+ Vue 3 Frontend
+ Dashboard & UI
+ Port 3000 +
+
โ†”
+
+ FastAPI Backend
+ Data & API
+ Port 8001 +
+
โ†”
+
+ Mock Data
+ JSON Files
+ In Memory +
+
+
+ +

What Each Part Does

+ +
+
+

๐Ÿ–ฅ๏ธ Frontend (Vue 3)

+

The visual dashboard you see in the browser. Shows charts, tables, and metrics. Sends requests to the backend when you click buttons or change filters.

+
+ +
+

โš™๏ธ Backend (FastAPI)

+

The invisible server that stores data and answers questions. When the frontend asks for inventory data, the backend retrieves it and sends it back as JSON.

+
+ +
+

๐Ÿ“Š Data (JSON)

+

Simulated factory data stored in files. Includes inventory, orders, demand forecasts, and spending information. Loaded into memory when the server starts.

+
+
+
+ + +
+

Tech Stack

+

The technologies and frameworks used to build this application:

+ +
+
+

Frontend

+
    +
  • Vue 3 - Interactive UI framework
    • +
  • Vite - Development server & build tool
    • +
  • Axios - HTTP client for API calls
    • +
  • JavaScript ES6+ - Programming language
    • +
+
+ +
+

Backend

+
    +
  • FastAPI - Python web framework
    • +
  • Python 3.9+ - Programming language
    • +
  • Pydantic - Data validation
    • +
  • CORS - Cross-domain requests
    • +
+
+ +
+

Data & Infrastructure

+
    +
  • JSON Files - Data storage
    • +
  • In-Memory Loading - Fast access
    • +
  • Mock Data - No database needed
    • +
  • Port 3000 & 8001 - Local development
    • +
+
+
+
+ + +
+

How Data Flows Through the System

+

Here's what happens when you use the dashboard:

+ +
+
+ 1. User Action + You click a button or change a filter on the dashboard +
+ +
+ 2. Frontend Sends Request + Vue.js sends an HTTP request to the backend API with your filters +
+ +
+ 3. Backend Processes + FastAPI receives the request, filters the data according to your criteria +
+ +
+ 4. Query Mock Data + Backend searches through the JSON data loaded in memory +
+ +
+ 5. Validate & Return + Backend validates the results using Pydantic models, then sends JSON back +
+ +
+ 6. Display Results + Frontend receives the data and updates the dashboard to show new results +
+
+ +

Example: Filtering Orders by Month

+
+
+ You select: "February 2025"

+ โ†“

+ Frontend sends:
+ GET http://localhost:8001/api/orders?month=2025-02

+ โ†“

+ Backend filters JSON data:
+ Find all orders where order_date contains "2025-02"

+ โ†“

+ Backend returns:
+ [{order_id: "123", date: "2025-02-14", ...}, ...]

+ โ†“

+ Dashboard updates:
+ Shows February orders in tables and charts +
+
+
+ + +
+

Backend API Endpoints

+

The frontend communicates with the backend through these API endpoints:

+ +
+
+ GET /api/inventory
+ Gets inventory items. Supports filters: warehouse, category +
+ +
+ GET /api/orders
+ Gets customer orders. Supports filters: warehouse, category, status, month +
+ +
+ GET /api/demand
+ Gets demand forecasts for products +
+ +
+ GET /api/backlog
+ Gets list of backlogged orders (unfulfilled) +
+ +
+ GET /api/dashboard/summary
+ Gets summary statistics. Supports all filters +
+ +
+ GET /api/spending/*
+ Gets spending data (summary, monthly, by category, transactions) +
+
+ +

Pro Tip: Visit http://localhost:8001/docs to see interactive API documentation!

+
+ + +
+

Frontend Pages & Features

+

The dashboard has 6 main views, each with specific functionality:

+ +
+
+

๐Ÿ“Š Overview Dashboard

+

Key metrics, KPIs, order health pie chart, inventory by category, top products, and inventory shortages table.

+
+ +
+

๐Ÿ“ฆ Inventory

+

Complete inventory items list with SKU, quantity, location, and category. Searchable and filterable.

+
+ +
+

๐Ÿ“‹ Orders

+

Customer orders with status tracking. Shows delivered, shipped, processing, and backordered orders.

+
+ +
+

๐Ÿ’ฐ Finance & Spending

+

Revenue analysis, spending by category, monthly spending trends, and transaction details.

+
+ +
+

๐Ÿ“ˆ Demand Forecast

+

Predicted demand for products showing trends and forecasts over time.

+
+ +
+

๐Ÿ“‘ Reports

+

Backlog report showing unfulfilled orders that need immediate attention.

+
+
+
+ + +
+

Filter System

+

The application has a consistent filtering system across pages:

+ +
+
+

๐Ÿ“… Time Period

+

Options: All Months, or individual months (January - December 2025)

+
+ +
+

๐Ÿข Location / Warehouse

+

Options: All, San Francisco, London, Tokyo

+
+ +
+

๐Ÿ“‚ Category

+

Options: Circuit Boards, Sensors, Actuators, Controllers, Power Supplies

+
+ +
+

โœ“ Order Status

+

Options: Delivered, Shipped, Processing, Backordered

+
+
+ +

When you change any filter, the frontend immediately requests new data from the backend and updates all visible charts and tables.

+
+ + +
+

Key Facts About This System

+ +
+
+

โœ… No Database

+

Data is stored in JSON files and loaded into memory. Perfect for demos and learning!

+
+ +
+

โšก Fast Development

+

Hot reloading on both frontend and backend means changes show up instantly.

+
+ +
+

๐Ÿ”“ No Authentication

+

This is a demo app. In production, you'd add login and permission checks.

+
+ +
+

๐Ÿ“ฑ Responsive Design

+

Dashboard works on desktop, tablet, and mobile devices.

+
+ +
+

๐ŸŽจ Consistent UI

+

Clean, modern design using slate gray colors and status-based highlighting.

+
+ +
+

๐Ÿ“– Well Documented

+

CLAUDE.md files guide developers on best practices for both frontend and backend.

+
+
+
+
+ +
+

Factory Inventory Management System | Architecture Overview | Built for the Anthropic Partner Basecamp Workshop

+
+
+ + \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index 89c307d15..0c78db535 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -69,6 +69,10 @@ npm install && npm run dev - Data: `server/data/*.json` - Styles: `client/src/App.vue` +## Code Style +- Always document non-obvious logic changes with comments +- Keep comments focused on WHY, not WHAT (the code shows what it does) + ## Design System - Colors: Slate/gray (#0f172a, #64748b, #e2e8f0) - Status: green/blue/yellow/red diff --git a/WORKSHOP_GUIDE.md b/WORKSHOP_GUIDE.md new file mode 100644 index 000000000..798b94198 --- /dev/null +++ b/WORKSHOP_GUIDE.md @@ -0,0 +1,158 @@ +# Anthropic Partner Basecamp Workshop Guide + +## Overview +This document explains everything we're doing in the Claude Code workshop. It's written in plain language so you can understand what's happening and why. + +--- + +## What We're Building +We're working on a **Factory Inventory Management System** โ€” a web application that helps factories track: +- Inventory levels across warehouses +- Customer orders and their status +- Demand forecasts +- Revenue and spending +- Backlog (orders waiting to be fulfilled) + +The app has two parts: +1. **Frontend** (what you see) - A dashboard in your browser showing charts, tables, and metrics +2. **Backend** (the invisible part) - A server that stores data and sends it to the frontend when requested + +--- + +## Steps Completed + +### โœ… Step 1: Fork & Clone Repository (10 pts) +**What we did:** +- Forked the original inventory app from Anthropic's GitHub to your personal GitHub account +- Cloned (downloaded) it to your computer at `/Users/moukie/Claude/inventory-management` +- Created a working branch called `new_features` where we can safely make changes + +**Why:** This gives you a personal copy of the code that you can modify without affecting anyone else's work. + +--- + +### โœ… Step 2: Launch Claude Code (10 pts) +**What we did:** +- Opened Claude Code (the AI coding assistant you're using now) +- Selected the Haiku model for faster responses + +**Why:** Claude Code helps us write, understand, and modify code throughout the workshop. + +--- + +### โœ… Step 3: Run Inventory Management Locally (15 pts) +**What we did:** + +1. **Installed Node.js** - Downloaded the JavaScript runtime your computer needed +2. **Installed Frontend Dependencies** - Ran `npm install` in the `client/` folder to get all the Vue 3 and Vite libraries the dashboard needs +3. **Installed Backend Dependencies** - Ran `uv sync` in the `server/` folder to get all the Python/FastAPI libraries the data server needs +4. **Started the Backend Server** - Launched the Python FastAPI server on port 8001 (this serves the data/API) +5. **Started the Frontend Server** - Launched the Vue 3 dev server on port 3000 (this serves the visual dashboard) +6. **Opened the App** - Navigated to `http://localhost:3000` in your browser to see the working dashboard + +**Why:** Now you have a fully running app on your computer that you can modify and test. + +**What's Running Now:** +- Frontend dashboard: `http://localhost:3000` - The visual inventory management interface +- Backend API: `http://localhost:8001` - The data server (API docs available at `http://localhost:8001/docs`) + +--- + +--- + +### โœ… Step 4: Edit CLAUDE.md File (5 pts) +**What we did:** +- Reviewed the project's CLAUDE.md file (instructions for Claude) +- Added a "Code Style" section with the rule: "Always document non-obvious logic changes with comments" + +**Why:** This file helps Claude understand project conventions and best practices. + +--- + +### โœ… Step 5: Understand the Codebase (20 pts) +**What we did:** +1. Explored the codebase to understand architecture +2. Read key files: backend main.py, frontend api.js, view components +3. Generated a professional HTML architecture page explaining: + - Frontend (Vue 3) โ†” Backend (FastAPI) โ†” Mock Data flow + - Tech stack with all technologies used + - API endpoints and how data flows + - Dashboard pages and features + - Filter system and data structures +4. Opened the page in browser at `http://localhost:8080/ARCHITECTURE.html` + +**Why:** Understanding the system architecture is crucial before building new features. It helps us follow existing patterns and conventions. + +--- + +### โœ… Step 6: Build Budget-Based Restocking Feature (25 pts) +**What we built:** +A complete budget-based restocking tool that allows users to: +1. Set a budget ($0-$50,000 USD) using an interactive slider +2. Get AI-recommended inventory items based on demand forecasts (sorted by highest demand gap) +3. Adjust recommended quantities in real-time with budget validation +4. Submit restocking orders that integrate with the Orders system +5. See submitted orders with "Submitted" status and 7-day delivery lead time + +**Implementation Summary:** + +**Backend (Python FastAPI):** +- โœ… New endpoint: `GET /api/restocking/recommendations?budget=X` - Returns items prioritized by demand gap, fills budget greedily +- โœ… New endpoint: `POST /api/restocking/orders` - Creates new orders with "Submitted" status and 7-day delivery +- โœ… New Pydantic models: RestockingItem, RestockingOrderItem, RestockingOrderRequest +- โœ… Budget validation: Prevents orders exceeding budget + +**Frontend (Vue 3):** +- โœ… New component: `client/src/views/Restocking.vue` (15.9 KB) with: + - Interactive budget slider ($0-$50,000, $100 steps) + - Real-time stats cards (Total Budget, Item Count, Estimated Cost, Budget Remaining) + - Recommended items table with adjustable quantities + - Quantity validation and real-time cost calculation + - Place Order button with budget constraint validation + - Success/error messages +- โœ… New translations: English and Japanese i18n keys for all UI text +- โœ… Router integration: Route added to `/restocking` in main.js +- โœ… Navigation: "Restocking" tab added between "Demand Forecast" and "Reports" + +**API Integration:** +- โœ… `api.getRestockingRecommendations(budget)` - Fetch recommendations +- โœ… `api.submitRestockingOrder(orderData)` - Submit order for placement + +**Key Algorithms:** +- **Recommendation**: Match demand forecasts with inventory, calculate demand gaps (forecasted - current), sort descending, fill budget greedily +- **Budget Tracking**: Real-time total cost calculation, prevent overspend, show remaining budget +- **Order Creation**: Generate "RST-2025-XXXX" order numbers, set 7-day delivery lead time + +**Testing Verified:** +โœ… Backend endpoint returns recommendations sorted by demand gap +โœ… Budget slider triggers API calls and updates stats +โœ… Items count displays correctly +โœ… UI loads and renders without errors +โœ… Translations working for both English and Japanese + +--- + +## Summary: What We've Accomplished + +**Steps Completed:** +- Step 1: Fork & Clone Repository (10 pts) โœ… +- Step 2: Launch Claude Code (10 pts) โœ… +- Step 3: Run Inventory Management Locally (15 pts) โœ… +- Step 4: Edit CLAUDE.md File (5 pts) โœ… +- Step 5: Understand the Codebase (20 pts) โœ… +- Step 6: Build Budget-Based Restocking Feature (25 pts) โœ… + +**Total: 85 points earned** ๐ŸŽ‰ + +**Technologies & Patterns Used:** +- Vue 3 Composition API with reactivity (ref, computed, watch) +- FastAPI with Pydantic validation +- Budget-constrained recommendation algorithm +- International i18n support +- RESTful API design +- Git workflow with feature branches + +**Next Steps:** +Workshop is progressing well! Ready for Step 7 or iteration on existing features. + +**Note:** This guide will be updated as we complete each step! diff --git a/client/src/App.vue b/client/src/App.vue index c2da05a5c..71d9913f7 100644 --- a/client/src/App.vue +++ b/client/src/App.vue @@ -22,6 +22,9 @@ {{ t('nav.demandForecast') }} + + Restocking + Reports diff --git a/client/src/api.js b/client/src/api.js index 11cb9db70..f0f047bd2 100644 --- a/client/src/api.js +++ b/client/src/api.js @@ -102,5 +102,15 @@ export const api = { async getPurchaseOrderByBacklogItem(backlogItemId) { const response = await axios.get(`${API_BASE_URL}/purchase-orders/${backlogItemId}`) return response.data + }, + + async getRestockingRecommendations(budget) { + const response = await axios.get(`${API_BASE_URL}/restocking/recommendations?budget=${budget}`) + return response.data + }, + + async submitRestockingOrder(orderData) { + const response = await axios.post(`${API_BASE_URL}/restocking/orders`, orderData) + return response.data } } diff --git a/client/src/locales/en.js b/client/src/locales/en.js index 03a58fe6e..40402ab11 100644 --- a/client/src/locales/en.js +++ b/client/src/locales/en.js @@ -188,6 +188,35 @@ export default { } }, + // Restocking + restocking: { + title: 'Restocking', + description: 'Plan and optimize inventory restocking with budget constraints', + setBudget: 'Set Your Budget', + totalBudget: 'Total Budget', + itemsInRecommendations: 'Items in Recommendations', + totalEstimatedCost: 'Total Estimated Cost', + budgetRemaining: 'Budget Remaining', + exceeded: 'EXCEEDED', + recommendedItems: 'Recommended Items', + noRecommendations: 'No recommendations available. Try adjusting your budget.', + placeOrder: 'Place Order', + loadError: 'Failed to load data', + recommendationsError: 'Failed to load recommendations', + submitError: 'Failed to submit order', + orderSubmitted: 'Order submitted successfully!', + noItemsSelected: 'Please select at least one item to order', + table: { + sku: 'SKU', + name: 'Item Name', + currentStock: 'Current Stock', + forecastedDemand: 'Forecasted Demand', + unitCost: 'Unit Cost', + recommendedQty: 'Recommended Qty', + estimatedCost: 'Estimated Cost' + } + }, + // Filters filters: { timePeriod: 'Time Period', diff --git a/client/src/locales/ja.js b/client/src/locales/ja.js index db33223ac..22a92b130 100644 --- a/client/src/locales/ja.js +++ b/client/src/locales/ja.js @@ -188,6 +188,35 @@ export default { } }, + // Restocking + restocking: { + title: '่ฃœๅ……', + description: 'ไบˆ็ฎ—ๅˆถ็ด„ใฎไธ‹ใงๅœจๅบซ่ฃœๅ……ใ‚’่จˆ็”ปใƒปๆœ€้ฉๅŒ–', + setBudget: 'ไบˆ็ฎ—ใ‚’่จญๅฎš', + totalBudget: '็ทไบˆ็ฎ—', + itemsInRecommendations: 'ๆŽจๅฅจๅ“็›ฎๆ•ฐ', + totalEstimatedCost: 'ๆŽจๅฎš็ทใ‚ณใ‚นใƒˆ', + budgetRemaining: 'ๆฎ‹ใ‚Šไบˆ็ฎ—', + exceeded: '่ถ…้Ž', + recommendedItems: 'ๆŽจๅฅจๅ“็›ฎ', + noRecommendations: 'ๆŽจๅฅจไบ‹้ …ใŒใ‚ใ‚Šใพใ›ใ‚“ใ€‚ไบˆ็ฎ—ใ‚’่ชฟๆ•ดใ—ใฆใฟใฆใใ ใ•ใ„ใ€‚', + placeOrder: 'ๆณจๆ–‡ใ‚’็™บๆณจ', + loadError: 'ใƒ‡ใƒผใ‚ฟใฎ่ชญใฟ่พผใฟใซๅคฑๆ•—ใ—ใพใ—ใŸ', + recommendationsError: 'ๆŽจๅฅจไบ‹้ …ใฎ่ชญใฟ่พผใฟใซๅคฑๆ•—ใ—ใพใ—ใŸ', + submitError: 'ๆณจๆ–‡ใฎ้€ไฟกใซๅคฑๆ•—ใ—ใพใ—ใŸ', + orderSubmitted: 'ๆณจๆ–‡ใŒๆญฃๅธธใซ้€ไฟกใ•ใ‚Œใพใ—ใŸ๏ผ', + noItemsSelected: 'ๆณจๆ–‡ใ™ใ‚‹ๅ“็›ฎใ‚’1ใคไปฅไธŠ้ธๆŠžใ—ใฆใใ ใ•ใ„', + table: { + sku: 'SKU', + name: 'ๅ“็›ฎๅ', + currentStock: '็พๅœจใฎๅœจๅบซ', + forecastedDemand: 'ไบˆๆธฌ้œ€่ฆ', + unitCost: 'ๅ˜ไพก', + recommendedQty: 'ๆŽจๅฅจๆ•ฐ้‡', + estimatedCost: 'ๆŽจๅฎšใ‚ณใ‚นใƒˆ' + } + }, + // Filters filters: { timePeriod: 'ๆœŸ้–“', diff --git a/client/src/main.js b/client/src/main.js index 477c2d966..d2ca3e075 100644 --- a/client/src/main.js +++ b/client/src/main.js @@ -6,6 +6,7 @@ import Inventory from './views/Inventory.vue' import Orders from './views/Orders.vue' import Demand from './views/Demand.vue' import Spending from './views/Spending.vue' +import Restocking from './views/Restocking.vue' import Reports from './views/Reports.vue' const router = createRouter({ @@ -16,6 +17,7 @@ const router = createRouter({ { path: '/orders', component: Orders }, { path: '/demand', component: Demand }, { path: '/spending', component: Spending }, + { path: '/restocking', component: Restocking }, { path: '/reports', component: Reports } ] }) diff --git a/client/src/views/Restocking.vue b/client/src/views/Restocking.vue new file mode 100644 index 000000000..7f77ba6f9 --- /dev/null +++ b/client/src/views/Restocking.vue @@ -0,0 +1,675 @@ + + + + + diff --git a/server/main.py b/server/main.py index a0c2d8c5a..aa9577692 100644 --- a/server/main.py +++ b/server/main.py @@ -1,8 +1,9 @@ from fastapi import FastAPI, HTTPException from fastapi.middleware.cors import CORSMiddleware -from typing import List, Optional +from typing import List, Optional, Dict from pydantic import BaseModel from mock_data import inventory_items, orders, demand_forecasts, backlog_items, spending_summary, monthly_spending, category_spending, recent_transactions, purchase_orders +from datetime import datetime, timedelta app = FastAPI(title="Factory Inventory Management System") @@ -120,6 +121,28 @@ class CreatePurchaseOrderRequest(BaseModel): expected_delivery_date: str notes: Optional[str] = None +class RestockingItem(BaseModel): + sku: str + name: str + current_stock: int + forecasted_demand: int + unit_cost: float + recommended_qty: int + estimated_cost: float + warehouse: str + +class RestockingOrderItem(BaseModel): + sku: str + name: str + quantity: int + unit_cost: float + estimated_cost: float + +class RestockingOrderRequest(BaseModel): + items: List[RestockingOrderItem] + total_cost: float + budget: float + # API endpoints @app.get("/") def root(): @@ -304,6 +327,104 @@ def get_monthly_trends(): result.sort(key=lambda x: x['month']) return result +@app.get("/api/restocking/recommendations", response_model=List[RestockingItem]) +def get_restocking_recommendations(budget: float): + """Get recommended items to restock based on demand forecasts, prioritized by demand gap""" + recommendations = [] + + # Match demand with inventory and calculate gaps + for demand in demand_forecasts: + # Find matching inventory item by SKU + inventory = None + for inv in inventory_items: + if inv.get('sku') == demand.get('item_sku'): + inventory = inv + break + + # Only include if we have matching inventory and positive demand gap + if inventory: + demand_gap = demand.get('forecasted_demand', 0) - demand.get('current_demand', 0) + if demand_gap > 0: + recommendations.append({ + 'demand_gap': demand_gap, + 'demand': demand, + 'inventory': inventory + }) + + # Sort by demand gap (descending) - items with highest demand increase first + recommendations.sort(key=lambda x: x['demand_gap'], reverse=True) + + # Fill budget greedily + result = [] + remaining_budget = budget + for rec in recommendations: + unit_cost = rec['inventory'].get('unit_cost', 0) + if unit_cost > 0: + qty = int(remaining_budget / unit_cost) + if qty > 0: + estimated_cost = qty * unit_cost + result.append(RestockingItem( + sku=rec['inventory']['sku'], + name=rec['inventory']['name'], + current_stock=rec['inventory']['quantity_on_hand'], + forecasted_demand=rec['demand']['forecasted_demand'], + unit_cost=unit_cost, + recommended_qty=qty, + estimated_cost=estimated_cost, + warehouse=rec['inventory']['warehouse'] + )) + remaining_budget -= estimated_cost + if remaining_budget < 1: + break + + return result + +@app.post("/api/restocking/orders") +def create_restocking_order(order_request: RestockingOrderRequest): + """Create a new restocking order and add it to the orders list""" + # Validate budget + if order_request.total_cost > order_request.budget: + raise HTTPException( + status_code=400, + detail=f"Order total ${order_request.total_cost:.2f} exceeds budget ${order_request.budget:.2f}" + ) + + # Create order record + order_id = len(orders) + 1 + order_number = f"RST-2025-{order_id:04d}" + now = datetime.now() + delivery_date = now + timedelta(days=7) + + new_order = { + 'id': str(order_id), + 'order_number': order_number, + 'customer': 'Internal - Restocking', + 'items': [ + { + 'sku': item.sku, + 'name': item.name, + 'quantity': item.quantity, + 'unit_price': item.unit_cost + } + for item in order_request.items + ], + 'status': 'Submitted', + 'order_date': now.isoformat(), + 'expected_delivery': delivery_date.isoformat(), + 'total_value': order_request.total_cost, + 'warehouse': order_request.items[0].sku.split('-')[0] if order_request.items else 'Unknown', + 'category': 'Restocking' + } + + orders.append(new_order) + + return { + 'order_number': order_number, + 'status': 'Submitted', + 'total_cost': order_request.total_cost, + 'expected_delivery': delivery_date.isoformat() + } + if __name__ == "__main__": import uvicorn uvicorn.run(app, host="0.0.0.0", port=8001) From accabd1ff38550895dc47c89bbe1a7125d9c8824 Mon Sep 17 00:00:00 2001 From: Moukhtar Nsouli Date: Thu, 13 Aug 2026 11:45:09 -0700 Subject: [PATCH 2/5] Add vue-component-optimizer skill Analyzes Vue 3 components for reactivity misuse, unmemoized computations, unstable v-for keys, and duplicated markup/logic, then applies fixes via the vue-expert subagent per CLAUDE.md's mandatory .vue-edit rule. Co-Authored-By: Claude Haiku 4.5 --- .../skills/vue-component-optimizer/SKILL.md | 41 +++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 42 insertions(+) create mode 100644 .claude/skills/vue-component-optimizer/SKILL.md diff --git a/.claude/skills/vue-component-optimizer/SKILL.md b/.claude/skills/vue-component-optimizer/SKILL.md new file mode 100644 index 000000000..f8222ceb1 --- /dev/null +++ b/.claude/skills/vue-component-optimizer/SKILL.md @@ -0,0 +1,41 @@ +--- +name: vue-component-optimizer +description: Analyzes Vue 3 component structure in client/src for performance and code-reuse issues (reactivity misuse, unmemoized computations, unstable v-for keys, duplicated markup/logic across components) and applies the fixes. Use when asked to review, optimize, audit, or refactor Vue components. +--- + +# Vue Component Optimizer + +Analyzes components under `client/src/views/` and `client/src/components/` for two categories of issues, then applies fixes. + +## Process + +1. **Discover** โ€” read every `.vue` file in `client/src/views/` and `client/src/components/`. +2. **Analyze** each file for the checks below, noting file:line for every finding. +3. **Cross-reference** across files to find duplication (same markup pattern, same formatting logic, same API-calling pattern repeated in 2+ components). +4. **Report** findings to the user first: group by category, cite file:line, state the concrete fix. Keep it short โ€” a table or bullet list, not prose per finding. +5. **Apply fixes**, per [CLAUDE.md](../../../CLAUDE.md)'s mandatory rule: delegate all `.vue` edits to the **vue-expert** subagent. Batch related fixes into one vue-expert call per file rather than one call per finding. +6. **Verify** โ€” after fixes land, run the app (`run` skill or dev servers already running) and check the affected pages still render and the browser console is clean. +7. **Summarize** what changed, file by file, and flag anything you deliberately left alone (e.g., a structural extraction that's high-risk enough to want the user's sign-off first). + +## Performance Checks + +- **Reactivity misuse** โ€” derived values computed inside a method, watcher, or inline in the template instead of a `computed()`. This codebase's convention (see CLAUDE.md) is: raw data in `ref()`, derived data in `computed()`. +- **Watcher-should-be-computed** โ€” a `watch()` whose only job is to recompute a value and assign it to another ref. Replace with `computed()`. +- **Unstable `v-for` keys** โ€” `:key="index"` instead of a stable identifier (`sku`, `id`, `month`, order number). Array reordering/filtering will misrender with index keys. +- **Inline literals in templates** โ€” object/array/function literals created directly in template expressions (`:style="{ color: x }"`, `@click="() => foo(x)"`) that get re-created every render. Hoist to a computed or method. +- **Unmemoized expensive work** โ€” filtering/sorting/reducing large arrays inside the ` @@ -324,9 +299,6 @@ export default { const selectedProduct = ref(null) const showBacklogModal = ref(false) const selectedBacklogItem = ref(null) - const showPOModal = ref(false) - const selectedBacklogForPO = ref(null) - const poModalMode = ref('create') // Use shared filters const { @@ -650,28 +622,6 @@ export default { showBacklogModal.value = true } - const openPOModal = (item) => { - selectedBacklogForPO.value = item - poModalMode.value = 'create' - showPOModal.value = true - } - - const viewPO = (item) => { - selectedBacklogForPO.value = item - poModalMode.value = 'view' - showPOModal.value = true - } - - const handlePOCreated = (poData) => { - // Update the backlog item with the new PO ID - const item = allBacklogItems.value.find(b => b.id === poData.backlog_item_id) - if (item) { - item.purchase_order_id = poData.id - item.purchase_order = poData - } - showPOModal.value = false - } - // Watch for filter changes and reload data watch([selectedPeriod, selectedLocation, selectedCategory, selectedStatus], () => { loadData() @@ -715,12 +665,6 @@ export default { Math, translateProductName, translateWarehouse, - showPOModal, - selectedBacklogForPO, - poModalMode, - openPOModal, - viewPO, - handlePOCreated } } } @@ -1236,36 +1180,4 @@ export default { transform: scale(1.1); } -.po-button { - padding: 0.5rem 1rem; - border: none; - border-radius: 6px; - font-size: 0.813rem; - font-weight: 600; - cursor: pointer; - transition: all 0.2s ease; - white-space: nowrap; -} - -.po-button.create { - background: #3b82f6; - color: white; -} - -.po-button.create:hover { - background: #2563eb; - transform: translateY(-1px); - box-shadow: 0 2px 4px rgba(59, 130, 246, 0.3); -} - -.po-button.view { - background: #64748b; - color: white; -} - -.po-button.view:hover { - background: #475569; - transform: translateY(-1px); - box-shadow: 0 2px 4px rgba(100, 116, 139, 0.3); -} diff --git a/server/main.py b/server/main.py index aa9577692..acc71882b 100644 --- a/server/main.py +++ b/server/main.py @@ -143,6 +143,22 @@ class RestockingOrderRequest(BaseModel): total_cost: float budget: float +class Task(BaseModel): + id: str + title: str + priority: str + dueDate: str + status: str + +class CreateTaskRequest(BaseModel): + title: str + priority: str + dueDate: str + +# In-memory task store (separate from mock_data.py - user-generated, not seed data) +tasks: List[dict] = [] +next_task_id = 1 + # API endpoints @app.get("/") def root(): @@ -425,6 +441,40 @@ def create_restocking_order(order_request: RestockingOrderRequest): 'expected_delivery': delivery_date.isoformat() } +@app.get("/api/tasks", response_model=List[Task]) +def get_tasks(): + return tasks + +@app.post("/api/tasks", response_model=Task) +def create_task(task_request: CreateTaskRequest): + global next_task_id + new_task = { + 'id': str(next_task_id), + 'title': task_request.title, + 'priority': task_request.priority, + 'dueDate': task_request.dueDate, + 'status': 'pending' + } + next_task_id += 1 + tasks.append(new_task) + return new_task + +@app.patch("/api/tasks/{task_id}", response_model=Task) +def toggle_task(task_id: str): + task = next((t for t in tasks if t['id'] == task_id), None) + if not task: + raise HTTPException(status_code=404, detail=f"Task {task_id} not found") + task['status'] = 'completed' if task['status'] == 'pending' else 'pending' + return task + +@app.delete("/api/tasks/{task_id}") +def delete_task(task_id: str): + task = next((t for t in tasks if t['id'] == task_id), None) + if not task: + raise HTTPException(status_code=404, detail=f"Task {task_id} not found") + tasks.remove(task) + return {'message': 'Task deleted', 'id': task_id} + if __name__ == "__main__": import uvicorn uvicorn.run(app, host="0.0.0.0", port=8001) From 84f9b3e7b4f941770d275e0d94909f44702dc71b Mon Sep 17 00:00:00 2001 From: Moukhtar Nsouli Date: Fri, 14 Aug 2026 09:29:26 -0700 Subject: [PATCH 5/5] Update WORKSHOP_GUIDE.md with Steps 7-11 and post-workshop work Adds context for team members who didn't attend (glossary, background), documents Steps 7-11 including the friction points (CLI PATH issues, GitHub App plan-tier block, PAT scope error), and adds a section on the vue-component-optimizer skill, debugger subagent, and the Dashboard console-error case study that used both. Co-Authored-By: Claude Haiku 4.5 --- WORKSHOP_GUIDE.md | 304 +++++++++++++++++++++++++++++++--------------- 1 file changed, 203 insertions(+), 101 deletions(-) diff --git a/WORKSHOP_GUIDE.md b/WORKSHOP_GUIDE.md index 798b94198..e08c1fcca 100644 --- a/WORKSHOP_GUIDE.md +++ b/WORKSHOP_GUIDE.md @@ -1,12 +1,27 @@ -# Anthropic Partner Basecamp Workshop Guide +# Claude Code Workshop: Building the Factory Inventory Management System -## Overview -This document explains everything we're doing in the Claude Code workshop. It's written in plain language so you can understand what's happening and why. +## For Readers Who Weren't There + +This document was written during a two-day **Anthropic Partner Basecamp** workshop (a hands-on training session for enterprise partners, ending in a team hackathon). If you weren't in the room, here's the context you need: + +**What is Claude Code?** Anthropic's AI coding assistant. It runs as a desktop app, a terminal CLI, or in your IDE, and can read your codebase, write and edit code, run commands, browse the web, and more โ€” all while following project-specific conventions you give it. + +**Quick glossary** (terms used throughout this doc): + +| Term | What it means | +|---|---| +| **Slash command** | A command typed directly into Claude's chat, like `/context` or `/compact` โ€” not a terminal/bash command. | +| **MCP (Model Context Protocol)** | A connector standard that gives Claude access to external tools โ€” e.g., the Playwright MCP gives Claude real browser control. | +| **Subagent** | A focused, specialized version of Claude scoped to a task (e.g., a Vue specialist, a security auditor) with its own instructions and tool access. Defined in `.claude/agents/`. | +| **Skill** | A reusable, packaged set of instructions Claude follows for a recurring task (e.g., "how to write backend tests," "how to optimize Vue components"). Defined in `.claude/skills/`. | +| **CLAUDE.md** | A file in the repo that tells Claude the project's conventions, rules, and patterns to follow โ€” read automatically at the start of every session in that repo. | +| **Plan Mode** | A mode where Claude designs an approach and gets it approved *before* writing any code, useful for non-trivial features. | --- ## What We're Building -We're working on a **Factory Inventory Management System** โ€” a web application that helps factories track: + +A **Factory Inventory Management System** โ€” a web application that helps factories track: - Inventory levels across warehouses - Customer orders and their status - Demand forecasts @@ -14,8 +29,8 @@ We're working on a **Factory Inventory Management System** โ€” a web application - Backlog (orders waiting to be fulfilled) The app has two parts: -1. **Frontend** (what you see) - A dashboard in your browser showing charts, tables, and metrics -2. **Backend** (the invisible part) - A server that stores data and sends it to the frontend when requested +1. **Frontend** (what you see) โ€” A dashboard in your browser showing charts, tables, and metrics (Vue 3) +2. **Backend** (the invisible part) โ€” A server that stores data and sends it to the frontend when requested (Python/FastAPI) --- @@ -23,136 +38,223 @@ The app has two parts: ### โœ… Step 1: Fork & Clone Repository (10 pts) **What we did:** -- Forked the original inventory app from Anthropic's GitHub to your personal GitHub account -- Cloned (downloaded) it to your computer at `/Users/moukie/Claude/inventory-management` -- Created a working branch called `new_features` where we can safely make changes +- Forked the original inventory app from Anthropic's GitHub to a personal GitHub account +- Cloned it locally to `/Users/moukie/Claude/inventory-management` +- Created a working branch called `new_features` to make changes safely -**Why:** This gives you a personal copy of the code that you can modify without affecting anyone else's work. +**Why:** A personal copy that can be modified without affecting anyone else's work. --- ### โœ… Step 2: Launch Claude Code (10 pts) **What we did:** -- Opened Claude Code (the AI coding assistant you're using now) -- Selected the Haiku model for faster responses +- Opened Claude Code and selected a model -**Why:** Claude Code helps us write, understand, and modify code throughout the workshop. +**Why:** Claude Code is the tool used to write, understand, and modify code throughout the workshop. --- ### โœ… Step 3: Run Inventory Management Locally (15 pts) **What we did:** +1. Installed Node.js +2. Installed frontend dependencies (`npm install` in `client/`) +3. Installed backend dependencies (`uv sync` in `server/`) +4. Started the backend (FastAPI, port 8001) +5. Started the frontend (Vue 3 + Vite, port 3000) +6. Opened `http://localhost:3000` to see the working dashboard + +**Why:** A fully running app on your machine that you can modify and test. -1. **Installed Node.js** - Downloaded the JavaScript runtime your computer needed -2. **Installed Frontend Dependencies** - Ran `npm install` in the `client/` folder to get all the Vue 3 and Vite libraries the dashboard needs -3. **Installed Backend Dependencies** - Ran `uv sync` in the `server/` folder to get all the Python/FastAPI libraries the data server needs -4. **Started the Backend Server** - Launched the Python FastAPI server on port 8001 (this serves the data/API) -5. **Started the Frontend Server** - Launched the Vue 3 dev server on port 3000 (this serves the visual dashboard) -6. **Opened the App** - Navigated to `http://localhost:3000` in your browser to see the working dashboard +--- -**Why:** Now you have a fully running app on your computer that you can modify and test. +### โœ… Step 4: Edit CLAUDE.md File (5 pts) +**What we did:** +- Added a "Code Style" rule to CLAUDE.md: *"Always document non-obvious logic changes with comments"* -**What's Running Now:** -- Frontend dashboard: `http://localhost:3000` - The visual inventory management interface -- Backend API: `http://localhost:8001` - The data server (API docs available at `http://localhost:8001/docs`) +**Why:** CLAUDE.md is how Claude learns project conventions โ€” every session in this repo reads it automatically. --- +### โœ… Step 5: Understand the Codebase (20 pts) +**What we did:** +- Explored the codebase and read key files (backend `main.py`, frontend `api.js`, view components) +- Generated `ARCHITECTURE.html` โ€” a visual page explaining the Vue โ†” FastAPI โ†” mock-data flow, tech stack, API endpoints, and dashboard structure +- Opened it in the browser + +**Why:** Understanding the architecture *before* building keeps new code consistent with existing patterns. + --- -### โœ… Step 4: Edit CLAUDE.md File (5 pts) +### โœ… Step 6: Build Budget-Based Restocking Feature (25 pts) +**What we built:** A budget-constrained restocking tool โ€” set a budget, get AI-recommended items based on demand forecasts, adjust quantities, submit the order. + +Used **Plan Mode** for this one: Claude proposed a design, asked clarifying questions (budget range, recommendation algorithm, whether quantities are adjustable, how orders integrate with the existing Orders system), and only started coding once the plan was approved. + +**Backend:** +- `GET /api/restocking/recommendations?budget=X` โ€” prioritizes items by demand gap (forecasted โˆ’ current demand), fills the budget greedily +- `POST /api/restocking/orders` โ€” creates orders with "Submitted" status and a 7-day delivery lead time +- Budget validation (rejects orders exceeding budget) + +**Frontend:** +- New `Restocking.vue` view: budget slider, live stats (budget/items/cost/remaining), adjustable recommended-items table, Place Order button +- New nav tab, route, and English/Japanese translations + +**A bug we caught in review:** the quantity field initially showed `0` for every recommendation โ€” turned out the component was reading `item.recommended_quantity` but the backend actually returned `item.recommended_qty`. One-line fix once traced. + +--- + +### โœ… Step 7: Context Management (10 pts) **What we did:** -- Reviewed the project's CLAUDE.md file (instructions for Claude) -- Added a "Code Style" section with the rule: "Always document non-obvious logic changes with comments" +- Ran `/context` to see a breakdown of token usage (system prompt, tools, messages, free space) +- Ran `/compact` to summarize the conversation and free up space, keeping key details +- Used `/compact keep the details of the restocking feature` to steer *what* gets preserved during summarization -**Why:** This file helps Claude understand project conventions and best practices. +**Why:** Long sessions fill up the context window. `/compact` lets Claude keep working without losing track of what matters, and you can tell it what to prioritize. --- -### โœ… Step 5: Understand the Codebase (20 pts) +### โœ… Step 8: Add Playwright MCP (15 pts) +**What we did:** Installed the Playwright MCP so Claude can control a real browser (navigate pages, click, screenshot, read console/network activity). + +**What we ran into (worth knowing):** the intended command was a single line โ€” +``` +claude mcp add playwright npx @playwright/mcp@latest +``` +โ€” but the `claude` CLI wasn't on the system PATH yet. Troubleshooting took a few turns: +1. `npm install -g @anthropic-sdk/cli` โ†’ wrong package name, 404 +2. `npm install -g claude` โ†’ `EACCES` permission error (npm trying to write to a protected system folder) +3. `sudo npm install -g claude` โ†’ installed *a* package, but not actually the right Claude Code binary +4. Searched the filesystem and found the real CLI bundled inside the Claude desktop app itself, at a versioned path under `~/Library/Application Support/Claude/` +5. Created a symlink (`/usr/local/bin/claude โ†’ the bundled binary`) so `claude` resolves from any terminal +6. Ran the MCP install command successfully, then **restarted Claude Code** so it picked up the new MCP config + +**Why it matters:** MCP servers extend what Claude can *do* โ€” this one turned "describe what the app should do" into "actually click through it and check." + +--- + +### โœ… Step 9: Test the App with Playwright MCP **What we did:** -1. Explored the codebase to understand architecture -2. Read key files: backend main.py, frontend api.js, view components -3. Generated a professional HTML architecture page explaining: - - Frontend (Vue 3) โ†” Backend (FastAPI) โ†” Mock Data flow - - Tech stack with all technologies used - - API endpoints and how data flows - - Dashboard pages and features - - Filter system and data structures -4. Opened the page in browser at `http://localhost:8080/ARCHITECTURE.html` - -**Why:** Understanding the system architecture is crucial before building new features. It helps us follow existing patterns and conventions. +1. Started the dev servers, opened `http://localhost:3000` +2. Screenshotted the dashboard +3. Clicked through all 7 nav tabs (Overview, Inventory, Orders, Finance, Demand Forecast, Restocking, Reports) and confirmed each rendered correctly + +**The catch:** the first pass only tested navigation. When asked *"did you test everything? some filters aren't working"*, we went back and actually exercised the 4 shared filters (Time Period, Location, Category, Order Status) โ€” setting each one and confirming the dashboard numbers actually changed. All four worked correctly; the lesson was that "the page loads" and "the feature works" are different claims, and only one of them was actually tested the first time. + +**Why:** Automated browser testing catches real integration bugs (wrong data, broken filters, console errors) that a code read-through won't. --- -### โœ… Step 6: Build Budget-Based Restocking Feature (25 pts) -**What we built:** -A complete budget-based restocking tool that allows users to: -1. Set a budget ($0-$50,000 USD) using an interactive slider -2. Get AI-recommended inventory items based on demand forecasts (sorted by highest demand gap) -3. Adjust recommended quantities in real-time with budget validation -4. Submit restocking orders that integrate with the Orders system -5. See submitted orders with "Submitted" status and 7-day delivery lead time - -**Implementation Summary:** - -**Backend (Python FastAPI):** -- โœ… New endpoint: `GET /api/restocking/recommendations?budget=X` - Returns items prioritized by demand gap, fills budget greedily -- โœ… New endpoint: `POST /api/restocking/orders` - Creates new orders with "Submitted" status and 7-day delivery -- โœ… New Pydantic models: RestockingItem, RestockingOrderItem, RestockingOrderRequest -- โœ… Budget validation: Prevents orders exceeding budget - -**Frontend (Vue 3):** -- โœ… New component: `client/src/views/Restocking.vue` (15.9 KB) with: - - Interactive budget slider ($0-$50,000, $100 steps) - - Real-time stats cards (Total Budget, Item Count, Estimated Cost, Budget Remaining) - - Recommended items table with adjustable quantities - - Quantity validation and real-time cost calculation - - Place Order button with budget constraint validation - - Success/error messages -- โœ… New translations: English and Japanese i18n keys for all UI text -- โœ… Router integration: Route added to `/restocking` in main.js -- โœ… Navigation: "Restocking" tab added between "Demand Forecast" and "Reports" - -**API Integration:** -- โœ… `api.getRestockingRecommendations(budget)` - Fetch recommendations -- โœ… `api.submitRestockingOrder(orderData)` - Submit order for placement - -**Key Algorithms:** -- **Recommendation**: Match demand forecasts with inventory, calculate demand gaps (forecasted - current), sort descending, fill budget greedily -- **Budget Tracking**: Real-time total cost calculation, prevent overspend, show remaining budget -- **Order Creation**: Generate "RST-2025-XXXX" order numbers, set 7-day delivery lead time - -**Testing Verified:** -โœ… Backend endpoint returns recommendations sorted by demand gap -โœ… Budget slider triggers API calls and updates stats -โœ… Items count displays correctly -โœ… UI loads and renders without errors -โœ… Translations working for both English and Japanese +### โœ… Step 10: Connect Claude Code to GitHub (15 pts) โ€” *blocked* +**What we did:** +- Learned that `/install-github-app` is a **slash command run inside an interactive Claude Code session** โ€” not a bash command, and not available in every chat surface (it failed in a non-interactive continuation session before working in a real terminal `claude` session) +- Ran it and authorized the GitHub App on the fork + +**Where it stopped:** the flow requires access to **Claude organization settings**, which are only available on Team/Enterprise plans โ€” not a personal Pro plan. The install couldn't complete, and no workflow PR was ever generated as a result. + +**Why it matters (even unfinished):** this integration is what enables `@claude` mentions in GitHub issues/PRs and automatic Claude-authored code review on every PR โ€” genuinely useful for a team, but it needs the right plan tier. Flagged as a follow-up for whoever manages the team's Anthropic workspace. + +--- + +### โœ… Step 11: Commit & Push +**What we did:** +- Realized Step 6's restocking work had been sitting **uncommitted** for several steps โ€” committed it, and from that point on committed after every real code/file change (not after every workshop step โ€” just when something actually changed) +- Pushed the `new_features` branch to the GitHub fork + +**What we ran into:** pushing from this environment initially failed (`git` had no credentials configured for a non-interactive session). Pushing from an actual terminal hit a second wall โ€” a `403 Permission denied`, traced to a personal access token that was missing the `repo` scope. Regenerating the token with the right scope fixed it. + +**Note on the PR:** a pull request was attempted but never actually completed (the fork showed 0 PRs when checked afterward) โ€” and the team decided that's fine; a PR wasn't needed to demonstrate the workflow. The important part โ€” a clean, pushed commit history โ€” was already in place. + +--- + +## Beyond the Workshop: Building Custom Tools + +Two custom additions to this project's `.claude/` setup, plus a real bug found and fixed using them. + +### ๐Ÿ”ง New Skill: `vue-component-optimizer` +Lives at `.claude/skills/vue-component-optimizer/SKILL.md`. Analyzes every `.vue` file for two categories of issues, then applies the fixes: + +- **Performance**: reactivity misuse (derived values that should be `computed()` but aren't), watchers doing a computed's job, unstable `v-for` keys, unmemoized expensive work, inline template literals recreated every render +- **Code reuse**: duplicated formatting logic, duplicated API-loading patterns, duplicated markup (stat cards, tables) that should be shared components, duplicated filter-handling logic + +Registered in CLAUDE.md so Claude knows to reach for it automatically when asked to review or optimize Vue components. + +### ๐Ÿ› New Subagent: `debugger` +Lives at `.claude/agents/debugger.md`. A **read-only** specialist (tools: Read, Grep, Glob, Bash โ€” deliberately no Write/Edit) that investigates runtime errors: + +- Parses stack traces (both Python/FastAPI and JS/Vue conventions) +- Distinguishes root cause from symptom +- Reproduces failures via Bash where possible (`curl` an endpoint, run a specific test) +- Checks whether the same bug pattern is duplicated elsewhere in the codebase +- Hands off *proposed* fixes rather than applying them โ€” frontend fixes get routed to the `vue-expert` subagent per this project's existing convention, backend fixes get applied directly + +**A caveat we found in practice:** custom subagents defined under `.claude/agents/` are picked up automatically by the *interactive* `claude` CLI (running `claude` in a terminal). This particular chat surface's agent-dispatch tool only exposes a fixed set of built-in agent types and doesn't dynamically load project-defined ones โ€” so invoking `debugger` here required doing the same investigation directly instead of through the named subagent. Worth confirming which surface your team is using before assuming custom agents "just work." + +### Case Study: Fixing Real Dashboard Console Errors +Put both new tools to work on an actual bug hunt โ€” the Dashboard page had two live issues: + +1. **`[Vue warn]: Failed to resolve component: PurchaseOrderModal`** โ€” repeated on every render +2. **`404` on `GET /api/tasks`** on page load + +**Investigation:** Grep'd for `PurchaseOrderModal` across the frontend and found it referenced in `Dashboard.vue`'s template with a full set of props and event handlers wired up โ€” but the component file itself never existed anywhere in the codebase, and its backend counterpart (`/api/purchase-orders`) didn't exist either, despite the backend already having Pydantic models and an (empty) mock-data file scaffolded for it. This was a feature that got partially built and abandoned. Separately, `getTasks()` in the frontend's API client called `GET /api/tasks` โ€” a route that was simply never implemented on the backend. + +**Decision point:** for the PO modal, the choice was between *finishing* the abandoned feature (bigger scope โ€” a new modal component plus new backend endpoints) or *removing* the dead code. Since the actual task was "fix the console error," not "build a purchase-order feature," the dead code was removed โ€” template block, refs, methods, buttons, and CSS โ€” while leaving the separate, working `BacklogDetailModal` feature untouched. + +**Fixes applied:** +- Removed the orphaned `PurchaseOrderModal` usage from `Dashboard.vue` (delegated to `vue-expert`, per this repo's mandatory rule that all `.vue` edits go through it) +- Added the missing `GET` / `POST` / `PATCH` / `DELETE /api/tasks` endpoints to `server/main.py`, matching the shape the frontend already expected + +**Verification:** reloaded the app in a *fresh* browser tab (to rule out stale hot-reload state) โ€” zero console warnings, zero errors, `/api/tasks` returns `200`. --- -## Summary: What We've Accomplished +## How It All Connects -**Steps Completed:** -- Step 1: Fork & Clone Repository (10 pts) โœ… -- Step 2: Launch Claude Code (10 pts) โœ… -- Step 3: Run Inventory Management Locally (15 pts) โœ… -- Step 4: Edit CLAUDE.md File (5 pts) โœ… -- Step 5: Understand the Codebase (20 pts) โœ… -- Step 6: Build Budget-Based Restocking Feature (25 pts) โœ… +The pieces built across this workshop aren't independent โ€” they compose: -**Total: 85 points earned** ๐ŸŽ‰ +- **CLAUDE.md** sets the ground rules for the whole repo (e.g., "all `.vue` edits go through `vue-expert`") +- **Subagents** (`vue-expert`, `code-reviewer`, `security-auditor`, `debugger`) are specialists Claude delegates to when a task matches their scope โ€” CLAUDE.md is what tells Claude *which* one to reach for +- **Skills** (`backend-api-test`, `vue-component-optimizer`) package up a repeatable *process* rather than a persona โ€” "when doing X, follow these steps" +- **MCP** (Playwright) gives Claude a way to *verify* claims instead of just asserting them โ€” "the filters work" became "I set each filter and confirmed the numbers changed" +- **Git/GitHub workflow** is what turns local changes into something a team can actually review and build on -**Technologies & Patterns Used:** -- Vue 3 Composition API with reactivity (ref, computed, watch) +The debugging case study above is a small example of the whole stack working together: a real error โ†’ investigated with the same rigor a `debugger` subagent would apply โ†’ a `.vue` fix routed through `vue-expert` per CLAUDE.md's rule โ†’ verified live with the Playwright-powered browser tools โ†’ committed and pushed. + +--- + +## Summary + +**Steps completed:** +| Step | Points | +|---|---| +| 1. Fork & Clone Repository | 10 | +| 2. Launch Claude Code | 10 | +| 3. Run Locally | 15 | +| 4. Edit CLAUDE.md | 5 | +| 5. Understand the Codebase | 20 | +| 6. Budget-Based Restocking Feature | 25 | +| 7. Context Management | 10 | +| 8. Add Playwright MCP | 15 | +| 9. Test with Playwright MCP | โ€” | +| 10. Connect to GitHub | 15 (blocked โ€” plan tier) | +| 11. Commit & Push | โ€” | + +**Confirmed points: 125** (Steps 9 and 11 weren't shown with an explicit point value; Step 10's points reflect the step attempted, not fully completed) + +**Technologies & patterns used:** +- Vue 3 Composition API (`ref`, `computed`, `watch`) - FastAPI with Pydantic validation - Budget-constrained recommendation algorithm -- International i18n support +- i18n (English/Japanese) - RESTful API design -- Git workflow with feature branches - -**Next Steps:** -Workshop is progressing well! Ready for Step 7 or iteration on existing features. - -**Note:** This guide will be updated as we complete each step! +- Git feature-branch workflow +- MCP (Playwright) for real browser verification +- Custom Claude Code skills and subagents + +**Key takeaways for the team:** +1. **Plan Mode earns its keep on real features** โ€” the restocking tool's design questions (budget range, algorithm, order integration) were resolved *before* code was written, not discovered mid-implementation. +2. **"It loads" โ‰  "it works."** The filter-testing gap in Step 9 is a good reminder to verify behavior, not just rendering. +3. **CLAUDE.md is what makes delegation consistent** โ€” the "route all `.vue` edits through vue-expert" rule kept applying correctly across completely different tasks (the restocking feature, the skill, the bug fix). +4. **Custom skills/subagents are cheap to build and genuinely reusable** โ€” `vue-component-optimizer` and `debugger` now exist for anyone who works in this repo going forward. +5. **Plan-tier and environment limits are real** โ€” GitHub App org settings and custom-subagent dispatch both behaved differently depending on which Claude surface (personal plan vs. Team/Enterprise; chat vs. terminal CLI) was in use. Worth checking before assuming a workflow will "just work" for the whole team. + +**Note:** This guide reflects the actual session, including the parts that didn't go smoothly on the first try (permission errors, a missing PR, a plan-tier blocker) โ€” kept in rather than cleaned up, since those are often the more useful parts for a team reading this afterward.