# AGENTS.md

> Project map for AI agents. Keep this file up-to-date as the project evolves.

## Project Overview
Stroyprofit CRM is a Laravel 11 application for managing orders of building structures (windows, doors, MAF). Covers the full lifecycle: order creation, production tracking, document generation (Excel/PDF), reclamation management, spare parts, and scheduling.

## Tech Stack
- **Language:** PHP 8.2+
- **Framework:** Laravel 11
- **Database:** MySQL 8.0
- **ORM:** Eloquent
- **Frontend:** Blade + Bootstrap 5 + jQuery + Vite + Sass
- **Queue:** Redis + Laravel Queue Jobs
- **Cache:** Redis (predis)
- **WebSocket:** Node.js custom server (JWT + Redis pub/sub)
- **Documents:** PHPSpreadsheet (Excel templates in /templates/)
- **DevOps:** Docker Compose + Nginx + PHP-FPM

## Project Structure
```
strprfcrm/
├── app/
│   ├── Console/              # Artisan commands
│   ├── Events/               # Broadcast events (WebSocket)
│   ├── Helpers/              # Utility helpers
│   ├── Http/
│   │   ├── Controllers/      # Request handlers
│   │   │   └── Admin/        # Admin-specific controllers
│   │   └── Middleware/       # HTTP middleware
│   ├── Jobs/                 # Queue jobs (export, import, generate, notify)
│   │   ├── Export/           # Export jobs
│   │   └── Import/           # Import jobs
│   ├── Models/               # Eloquent models
│   │   ├── Dictionary/       # Reference data models
│   │   └── Scopes/           # Global query scopes
│   ├── Notifications/        # Notification classes (FCM)
│   ├── Observers/            # Model event observers
│   ├── Providers/            # Service providers
│   └── Services/             # Business logic layer
│       ├── Export/           # Excel export services
│       ├── Import/           # Excel import services
│       └── Generate/         # Document generation services
├── database/
│   ├── migrations/           # Database migrations
│   ├── seeders/              # Database seeders
│   └── factories/            # Model factories
├── resources/
│   ├── views/                # Blade templates
│   │   ├── layouts/          # Base layouts
│   │   ├── partials/         # Reusable partials
│   │   ├── orders/           # Order views
│   │   ├── maf_orders/       # MAF order views
│   │   ├── reclamations/     # Reclamation views
│   │   ├── schedule/         # Schedule views
│   │   ├── spare_parts/      # Spare parts views
│   │   ├── spare_part_orders/# Spare part order views
│   │   ├── catalog/          # Product catalog views
│   │   ├── contracts/        # Contract views
│   │   ├── reports/          # Report views
│   │   └── admin/            # Admin panel views
│   ├── sass/                 # SCSS stylesheets
│   └── js/                   # JavaScript entry points
├── routes/
│   ├── web.php               # Main web routes
│   ├── channels.php          # Broadcast channels
│   └── console.php           # Artisan routes
├── templates/                # Excel templates for document generation
├── docker/                   # Docker service configs
│   ├── nginx/                # Nginx config
│   ├── php/                  # PHP-FPM config
│   ├── mysql/                # MySQL config
│   └── simple-ws/            # Node.js WebSocket server
├── docs/                     # Development documentation
├── tech-docs/                # Technical documentation
├── Makefile                  # Dev shortcuts (make up, make install, etc.)
├── docker-compose.yml        # Docker Compose services
└── CLAUDE.md                 # Claude Code project instructions
```

## Key Entry Points
| File | Purpose |
|------|---------|
| `routes/web.php` | All application routes |
| `app/Http/Controllers/` | Request handlers |
| `app/Services/` | Business logic (import/export/generate) |
| `app/Jobs/` | Async queue jobs |
| `app/Models/` | Eloquent models |
| `templates/` | Excel templates for document generation |
| `docker/simple-ws/server.js` | Node.js WebSocket server |
| `Makefile` | Dev commands (make up, make install, etc.) |
| `.env.example` | Environment variables reference |

## Key Models
| Model | Table/View | Purpose |
|-------|-----------|---------|
| `Order` | `orders` | Client orders |
| `MafOrder` | `maf_orders` | MAF (small architectural forms) orders |
| `OrderView` | `order_views` (view) | Aggregated order data |
| `MafOrdersView` | `maf_orders_views` (view) | Aggregated MAF data |
| `Product` | `products` | Product catalog |
| `ProductSKU` | `product_skus` | Product SKU variants |
| `Reclamation` | `reclamations` | Client reclamations |
| `ReclamationView` | `reclamation_views` (view) | Aggregated reclamation data |
| `Contract` | `contracts` | Client contracts |
| `Schedule` | `schedules` | Production/delivery schedule |
| `SparePart` | `spare_parts` | Spare parts inventory |
| `SparePartOrder` | `spare_part_orders` | Spare part procurement orders |

## Service Layer
| Service | Purpose |
|---------|---------|
| `Services/Export/` | Excel export (orders, MAFs, schedules, reclamations) |
| `Services/Import/` | Excel import (orders, MAFs, reclamations, catalog) |
| `Services/Generate/` | Document pack generation (installation, handover, reclamation) |
| `FileService` | File management |
| `ShortageService` | Shortage/deficit tracking |
| `SparePartInventoryService` | Spare part stock management |
| `PdfConverterClient` | HTTP client for pdf-converter service |

## Documentation
| Document | Path | Description |
|----------|------|-------------|
| README | README.md | Project landing page |
| Claude instructions | CLAUDE.md | Dev commands and architecture overview |
| Spare parts module | SPARE_PARTS_MODULE.md | Spare parts feature documentation |
| Spare parts enhancements | SPARE_PARTS_ENHANCEMENTS.md | Enhancement notes |
| Tech docs | tech-docs/ | Technical documentation |

## AI Context Files
| File | Purpose |
|------|---------|
| AGENTS.md | This file — project structure map |
| .ai-factory/DESCRIPTION.md | Project specification and tech stack |
| .ai-factory/ARCHITECTURE.md | Architecture decisions and guidelines |
| CLAUDE.md | Claude Code instructions and dev commands |