supersam/QWEN.md

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

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

Production Build

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

Linting

npm run lint       # ESLint check

Testing

npm run test       # Run Vitest tests

Local Supabase Stack

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