# Construction Delivery Control — QWEN Context

## Project Overview

**Construction Delivery Control** is a React-based single-page application for managing construction orders across the full lifecycle: order creation, production, logistics, and delivery coordination. It integrates with chatbot channels (VK, Telegram, Messenger Max) for automated customer communication about delivery slots.

### Key Features

- **OTP authentication** via Supabase Auth with a demo mode when backend is not configured
- **Role-based dashboard** for 5 roles: Manager, Production Lead, Logistician, Driver, Admin
- **Order lifecycle management** — creation, editing, status transitions, delivery slot scheduling
- **Production queue panel** — Kanban-style view for production workflow
- **Chatbot integration** — unified adapter layer for VK, Telegram, Messenger Max
- **Client-facing delivery page** — token-based link for customers to confirm/reschedule delivery
- **Installable PWA** with offline support (service worker + manifest)
- **Light/dark themes** with responsive, minimalist UI
- **Supabase backend** — PostgreSQL schema with Row-Level Security (RLS), audit triggers, and Supabase Edge Functions

### Tech Stack

| Layer | Technology |
|---|---|
| Frontend | React 18, React Router 7, Tailwind CSS, Framer Motion |
| State | React Context (`AuthContext`, `ThemeContext`), local component state |
| Backend | Supabase (PostgreSQL, Auth, Edge Functions) |
| Build | Vite 6 |
| Testing | Vitest |
| Linting | ESLint 9 |
| PWA | Custom service worker + Web App Manifest |

## Project Structure

```
super-sam/
├── src/                          # Frontend source
│   ├── components/               # UI components
│   │   ├── admin/                # Admin panels (users, audit)
│   │   ├── auth/                 # Login / OTP components
│   │   ├── chat/                 # Chat message components
│   │   ├── client/               # Client-facing delivery page
│   │   ├── dashboard/            # KPI, production queue panels
│   │   ├── driver/               # Driver delivery panel
│   │   ├── logistics/            # Bot control, delivery slots
│   │   ├── orders/               # Order list, card, editor, history
│   │   └── UI/                   # Shared UI primitives
│   ├── constants/                # Workflow statuses, transitions
│   ├── context/                  # AuthContext, ThemeContext
│   ├── data/                     # Mock/demo data
│   ├── hooks/                    # useOrders, usePwaStatus, etc.
│   ├── layouts/                  # AppShell (sidebar + content)
│   ├── lib/                      # Utility libraries
│   ├── pages/                    # Route-level pages
│   ├── services/                 # Business logic (pure functions)
│   │   └── supabase/             # Supabase repository adapters
│   ├── styles/                   # Theme CSS
│   ├── test/                     # Test utilities
│   └── utils/                    # General utilities
├── supabase/
│   ├── schema.sql                # Full DB schema with RLS policies
│   └── functions/                # Supabase Edge Functions
│       ├── chatbot-webhook/      # Inbound webhook handler
│       ├── send-chatbot-message/ # Outbound message sender
│       ├── confirm-delivery-choice/
│       ├── create-delivery-invitation/
│       ├── get-delivery-invitation/
│       ├── report-delivery-result/
│       ├── transfer-to-logistics/
│       └── _shared/              # Shared modules (chatbot, workflow)
├── public/
│   ├── manifest.webmanifest      # PWA manifest
│   ├── service-worker.js         # Offline caching
│   └── icons/                    # PWA install icons
├── docs/
│   ├── architecture.md           # Frontend architecture
│   ├── chatbot-integration.md    # Bot channel integration spec
│   ├── scenarios.md              # Order lifecycle scenarios
│   ├── operations/               # Operational docs
│   └── superpowers/              # Feature/agent instructions
└── docker-compose.yml            # Self-hosted Supabase stack
```

## Building and Running

### Prerequisites

- Node.js 18+
- npm

### Development

```bash
npm install        # Install dependencies
npm run dev        # Start Vite dev server (http://localhost:5173)
```

### Production Build

```bash
npm run build      # Build for production (dist/)
npm run preview    # Preview production build
```

### Linting

```bash
npm run lint       # ESLint check
```

### Testing

```bash
npm run test       # Run Vitest tests
```

### Local Supabase Stack

```bash
docker compose up -d   # Start self-hosted Supabase
docker compose down    # Stop
```

### Environment Variables

Copy `.env.example` to `.env` and configure:

```
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key
```

Without these variables, the app runs in **demo mode** with local mock data.

## Architecture Highlights

### Authentication Flow

1. User enters email on `/login`
2. Supabase sends OTP via email (or demo mode bypasses this)
3. On success, `AuthContext` loads user profile + role from `public.users` table
4. Role-based routing guards dashboard access

### Order Service Layer

- `src/services/orderService.js` — pure functions for order CRUD, status transitions, filtering, metrics, auto-assignment
- `src/services/supabase/orderRepository.js` — Supabase adapter for real reads/writes
- The service layer is decoupled: tests mock data without needing a live database

### Role-Based Access Control

| Role | Permissions |
|---|---|
| `manager` | Create/edit own orders, read own orders, manage comments |
| `production_lead` | Read all orders, manage production queue, update production statuses |
| `logistician` | Read assigned orders, manage delivery, manage chatbots |
| `driver` | Read assigned deliveries, update driver statuses (Загружен, В пути, Доставлен) |
| `admin` | Full access to everything |

RLS policies in `schema.sql` enforce these at the database level.

### Workflow Statuses

Orders move through a defined pipeline:
`Новый` → `Подтверждён` → `В очереди производства` → `В производстве` → `Готово к доставке` → `Ожидает ответа клиента` → `Доставка согласована` → `Доставка запланирована` → ... → `Доставка завершена`

Transitions are gated by role via `src/constants/deliveryWorkflow.js`.

### Routing

| Route | Component | Description |
|---|---|---|
| `/` | → redirect to `/dashboard` | |
| `/login` | `LoginPage` | Email OTP authentication |
| `/dashboard` | `DashboardPage` | Role-based control center |
| `/delivery/:token` | `ClientDeliveryPage` | Client-facing delivery confirmation |
| `*` | `NotFoundPage` | 404 fallback |

## Development Conventions

- **ESLint** with `eslint:recommended`, `react`, and `react-hooks` plugins
- **Tailwind CSS** with `tailwind-merge` + `clsx` for className composition
- **Framer Motion** for animations and transitions
- **Module alias**: imports use relative paths from `src/`
- **Test coverage**: `orderService.js`, `deliveryInvitationApi.js`, `driverDeliveries.js`, `orderViews.js` all have `.test.js` files
- **Code splitting**: Vite config manually chunks `react`, `supabase`, and `motion` into separate bundles