Benjamin's Chili Oil Distribution System

AI coding agent instructions for developing a distribution management system for Benjamin's Chili Oil, tracking inventory across 10+ retail stores in Melbourne.

Project Architecture

This is a **distribution management system** with:

File Structure Reference

```

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

```

Step-by-Step Instructions

1. Development Workflow

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**:

2. Creating React Components

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

3. Styling with TailwindCSS

- 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`

4. Type System Alignment

**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`

5. Implementing Business Logic

#### 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

```

6. Data Flow Patterns

**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

```

7. Adding New Routes

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>

```

8. PWA Configuration

**Service Worker Strategy**:

**PWA Manifest**: Configured in `astro.config.mjs` under `AstroPWA()` integration

9. Business Configuration

**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.

10. Making Changes Checklist

**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

Common Issues and Solutions

TypeScript Error: Property doesn't exist

**Cause**: Type definitions in `src/types/` out of sync with mock data

**Fix**: Update types to match `DATABASE_SCHEMA_V2.md` schema

Component Not Interactive

**Cause**: Missing `client:load` directive in `.astro` file

**Fix**: Use `<Component client:load />` for components with hooks/events

Mock Data Doesn't Follow Rules

**Cause**: Generated data violates schema rules

**Fix**: Check `utils/mockInventoryData.ts` against trigger logic in `DATABASE_SCHEMA_V2.md`

Development Philosophy

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)

Documentation References

Constraints