# 🤖 AI Agent Entry Point — Blazma LIMS

> **Any AI agent modifying this project MUST read this file first, then read `/docs/ai/system_overview.md` before making any changes.**

---

## What is Blazma?

**Blazma** is an enterprise-grade **Laboratory Information Management System (LIMS)** built in Saudi Arabia. It serves multi-tenant laboratory networks with complete end-to-end workflows: patient registration → test ordering → sample collection → analysis → result reporting → billing → insurance claims.

- **Framework**: Laravel 12 (PHP 8.2+)
- **Database**: MySQL — **320 tables**, direct UPPERCASE naming convention
- **Queue**: Redis + Laravel Horizon (49 async jobs)
- **Region**: Saudi Arabia (ZATCA, NPHIES, HESN Plus compliance)
- **Architecture**: Service-Oriented, Multi-tenant (PROFILE-scoped)

---

## 📚 AI Knowledge Base — Required Reading Order

Before modifying ANY part of this system, an AI agent must read these files **in order**:

| # | File | Purpose |
|---|------|---------|
| 1 | [`/docs/ai/system_overview.md`](docs/ai/system_overview.md) | High-level domain, purpose, major features |
| 2 | [`/docs/ai/architecture.md`](docs/ai/architecture.md) | Framework layers, request lifecycle, patterns |
| 3 | [`/docs/ai/database.md`](docs/ai/database.md) | All 320 tables, relationships, critical schema |
| 4 | [`/docs/ai/modules.md`](docs/ai/modules.md) | All system modules, boundaries, responsibilities |
| 5 | [`/docs/ai/business_flows.md`](docs/ai/business_flows.md) | Critical workflows, queues, events |
| 6 | [`/docs/ai/integrations.md`](docs/ai/integrations.md) | External APIs, payment gateways, healthcare systems |
| 7 | [`/docs/ai/coding_rules.md`](docs/ai/coding_rules.md) | Naming conventions, service layer rules, patterns |
| 8 | [`/docs/ai/laravel_structure.md`](docs/ai/laravel_structure.md) | Controllers, services, jobs, folder map |
| 9 | [`/docs/ai/deployment.md`](docs/ai/deployment.md) | Production config, workers, Redis, storage |
| 10 | [`/docs/ai/ai_modification_rules.md`](docs/ai/ai_modification_rules.md) | **Mandatory rules for AI agents** |
| — | [`/docs/ai/AI_SYSTEM_MAP.json`](docs/ai/AI_SYSTEM_MAP.json) | Machine-readable system map |

---

## ⚡ Quick Reference

```
App Name:      Blazma
Domain:        Laboratory Information Management (LIMS)
Stack:         Laravel 12 / PHP 8.2 / MySQL / Redis
Tables:        320 (UPPERCASE naming)
Models:        431
Controllers:   40
Services:      107
Jobs:          49 (Redis queue)
Middleware:    14
Migrations:    800+
Routes:        1911 (web.php)
```

---

## 🔄 Keeping This Documentation Updated

Run after every sprint to refresh the AI knowledge base:

```bash
php artisan ai:update-docs
```

---

## ⚠️ Critical Rules Summary

1. **Never bypass the Service Layer** — all business logic lives in `app/Services/`
2. **PROFILE_ID is the multi-tenancy key** — every query must scope by it
3. **All DB tables are UPPERCASE** — models use `protected $table = 'TABLE_NAME'`
4. **Queue jobs via Redis** — never run heavy logic synchronously
5. **ZATCA/NPHIES compliance** — invoices and claims have strict government formats
6. **Update `/docs/ai/`** whenever architecture or major logic changes

---

*Last updated: 2026-03-11 07:58:45 UTC — auto-generated by `php artisan ai:update-docs`*