AI coding agent for building a distribution management system tracking inventory across retail stores in Melbourne. Frontend (Astro + React PWA) with planned backend. Enforces strict TypeScript, database-aligned types, and application-layer validation.
AI coding agent instructions for developing a distribution management system for Benjamin's Chili Oil, tracking inventory across 10+ retail stores in Melbourne.
This is a **distribution management system** with:
```
business.config.local.ts # Gitignored business data (pricing, stores, contacts)
DATABASE_SCHEMA_V2.md # Complete PostgreSQL schema (11 tables, triggers, functions)
frontend/
src/
components/ # React functional components (strict TypeScript)
pages/ # Astro file-based routing (SSR + client islands)
types/ # Type definitions (authoritative types)
inventory.ts # Inventory, product, location types
product.ts # Product catalog types
dashboard.ts # Dashboard widget types
hub.ts # Hub expansion & region types (Phase 2)
utils/ # Business logic utilities
mockData.ts # Mock data generators (until backend ready)
melbourneRegions.ts # 7 default Melbourne regions configuration
hubEconomics.ts # Hub economic viability calculator
```
When starting development:
```bash
cd frontend
npm run dev # Dev server on :4321
npm run typecheck # MUST pass (0 errors) before commits
npm run build # Production build
```
**Pre-commit Requirements**:
Every React component must follow this structure:
```tsx
/**
* ComponentName Component
* Brief description of what this component does
*/
import type { TypeName } from '../types/module';
interface ComponentNameProps {
prop1: Type1;
prop2?: Type2; // Optional props use ?
onAction?: () => void;
}
export default function ComponentName({ prop1, prop2, onAction }: ComponentNameProps) {
// Implementation using functional component pattern
}
```
**Component Requirements**:
1. Use TypeScript with `interface ComponentNameProps`
2. Be functional (no class components)
3. Include JSDoc header comment explaining purpose
4. Import types from `../types/` (never inline types)
5. Use only TailwindCSS utilities for styling
- Primary brand: `text-red-600`
- Neutral tones: `text-gray-*`
- Status colors:
- Critical: `text-red-600`, `bg-red-50`
- Warning: `text-yellow-600`, `bg-yellow-50`
- Info: `text-blue-600`, `bg-blue-50`
- Healthy: `text-green-600`, `bg-green-50`
**Source of Truth**: `frontend/src/types/inventory.ts` mirrors `DATABASE_SCHEMA_V2.md`
When working with data:
1. **Always check** `DATABASE_SCHEMA_V2.md` for schema structure
2. **Import types** from `src/types/` modules:
- `InventoryItem` - stock records
- `ProductWithVariants` - product catalog
- `StoreLocation` - retail locations
- `StockMovement` - transfers/adjustments
- `AlertQueueItem` - notification queue
3. **Match enums exactly**:
- `stock_status: 'healthy' | 'low' | 'critical' | 'overstocked'`
- `movement_type: 'transfer' | 'adjustment' | 'restock' | 'sale' | 'waste'`
4. **Computed fields are always calculated**, never hardcoded:
- `stock_value = current_stock * unit_cost`
- `profit_per_unit = retail_price * (1 - commission_rate / 100) - unit_cost`
#### Restock Calculation (21-day cycle)
```typescript
// Based on DATABASE_SCHEMA_V2.md trigger logic
next_restock_date = last_restock_date + restock_cycle_days
needs_restock = (current_stock < minimum_stock) OR (days_until_restock <= 3)
```
#### Profit Formula
```typescript
// R × (1 - C) - U
profit_per_unit = retail_price * (1 - commission_rate / 100) - unit_cost
// Example: $12.80 × (1 - 0.30) - $4.50 = $4.46
```
#### Stock Status Rules
```typescript
if (current_stock === 0) return 'critical';
if (current_stock < minimum_stock) return 'low';
if (current_stock > maximum_stock) return 'overstocked';
return 'healthy';
```
#### Hub Economics (Phase 2)
```typescript
// From utils/hubEconomics.ts
const economics = calculateHubEconomics(storeCount, commissionRate, storageFee, setupCost);
// Returns: monthly_savings, break_even_months, roi_percentage, is_economical
// Viability criteria:
// - Minimum 3 stores in region
// - Minimum $100/month savings
// - Maximum 24 months to break even
```
**Current Architecture (Mock Data Phase)**:
```
Astro Page → imports mockData → passes to React component (client:load) → renders
```
Example in `pages/index.astro`:
```astro
---
import { mockDashboardStats } from '../utils/mockData';
import DashboardWidget from '../components/DashboardWidget';
---
<DashboardWidget client:load data={mockDashboardStats} />
```
**Future Architecture (Backend Integration)**:
```
Astro Page (SSR) → fetch('/api/...') → pass to component → client-side updates
```
Astro uses file-based routing:
1. Create `.astro` file in `src/pages/`
2. File path becomes URL path: `alerts/pending.astro` → `/alerts/pending`
3. Wrap content in `<MainLayout>`:
```astro
---
import MainLayout from '../layouts/MainLayout.astro';
---
<MainLayout title="Page Title" currentPage="page-id">
<!-- Page content -->
</MainLayout>
```
**Service Worker Strategy**:
**PWA Manifest**: Configured in `astro.config.mjs` under `AstroPWA()` integration
**Never commit** `business.config.local.ts` (contains real pricing/contacts)
Access configuration:
```typescript
import { BUSINESS_CONFIG } from '../business.config.local';
const { pricing, stores, contacts } = BUSINESS_CONFIG;
```
Use `business.config.example.ts` as template for new setups.
**When adding a new component**:
**When modifying data structures**:
**When adding API endpoints (planned)**:
- `GET /api/inventory` → list with filters
- `POST /api/stock-movements` → create transfer
- `PATCH /api/inventory/:id` → update stock
- `POST /api/alerts/:id/approve` → approve alert
**Cause**: Type definitions in `src/types/` out of sync with mock data
**Fix**: Update types to match `DATABASE_SCHEMA_V2.md` schema
**Cause**: Missing `client:load` directive in `.astro` file
**Fix**: Use `<Component client:load />` for components with hooks/events
**Cause**: Generated data violates schema rules
**Fix**: Check `utils/mockInventoryData.ts` against trigger logic in `DATABASE_SCHEMA_V2.md`
1. **Type Safety First**: 0 TypeScript errors is non-negotiable
2. **Schema Alignment**: All types mirror `DATABASE_SCHEMA_V2.md` exactly
3. **Component Isolation**: Each component is self-contained with clear props interface
4. **Mock Realism**: Mock data must follow real business rules (restock cycles, profit formulas)
5. **Offline-Ready**: All features must gracefully handle offline state via PWA
6. **Economic Viability**: Hub expansion decisions driven by data (calculate before building)
7. **Hybrid Approach**: Provide sensible defaults, allow customization (regions, hub types)
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/benjamins-chili-oil-distribution-system/raw