# Arquitectura Técnica — amimak FSM Platform

## Stack

| Camada | Tecnologia |
|---|---|
| Backend | Laravel 11 (PHP 8.3+) |
| Frontend inicial | Blade + Livewire 3 + Tailwind CSS |
| API | API-first, Laravel Sanctum (tokens), `routes/api.php`, versionado `/api/v1` |
| Base de dados | MySQL 8 / PostgreSQL 15 (single-tenant por instalação — ver docs/07) |
| Filas | Laravel Queue (Redis driver) |
| Storage | Laravel Filesystem abstraction — driver `local` em dev, `s3`/`minio` em produção |
| RBAC | spatie/laravel-permission (com "teams" = organization_id) |
| Autorização | Laravel Policies + Gates (nunca só roles) |
| Auditoria | owen-it/laravel-auditing (ou solução própria — ver `05-AUDITORIA.md`) |
| Testes | Pest / PHPUnit, Feature + Unit + testes de segurança dedicados |
| Notificações | Laravel Notifications (Mail, Database, Broadcast) — preparado para WhatsApp/SMS via driver custom |

## Princípios de código (secção 46 da spec)

```
app/
├── Actions/          → uma ação de negócio = uma classe invocável
│   ├── MaintenanceRequests/
│   │   ├── CreateMaintenanceRequestAction.php
│   │   └── ApproveMaintenanceRequestAction.php
│   └── WorkOrders/
│
├── Services/          → lógica de negócio mais ampla / orquestração
│   ├── SlaService.php
│   ├── MaintenanceResponsibilityResolver.php
│   └── FileStorageService.php
│
├── Models/             → Eloquent, magro, sem lógica de negócio pesada
├── Policies/           → uma policy por model sensível
├── Http/
│   ├── Controllers/Api/V1/
│   ├── Requests/       → validação (nunca validar em controller)
│   └── Resources/      → serialização da API (nunca devolver Model::toArray())
├── Events/
├── Listeners/
├── Jobs/                → filas assíncronas (envio de email, geração de tarefas preventivas)
├── Notifications/
├── Enums/               → status/estado como PHP 8.1 Enums nativos (nunca strings soltas)
├── Traits/
│   └── (sem trait de tenancy — sistema é single-tenant, ver docs/07)
└── DTOs/                → apenas onde há benefício real (ex: dados vindos de múltiplos inputs)
```

**Regra de ouro:** um Controller nunca deve ter mais do que "validar → chamar
Action/Service → devolver Resource". Toda a lógica de negócio (cálculo de SLA,
determinação de responsável, workflow de aprovação) vive em `Actions/` ou
`Services/`, nunca no Controller nem no Model.

## Fluxo de uma requisição típica (ex: criar Work Order)

```
Request
  → Middleware (auth:sanctum)
  → Form Request (valida input + autoriza via Policy::create)
  → Controller (fino)
  → Action (CreateWorkOrderAction)
      → aplica Services (SlaService, MaintenanceResponsibilityResolver)
      → dispara Event (WorkOrderCreated)
  → Listener grava Audit Log + dispara Notification
  → Resource devolve JSON
```

## Módulos (mapeados 1:1 à hierarquia da secção 7 e ao MVP da secção 52)

Ver `03-ERD.md` para o modelo de dados completo e `04-MULTI-TENANCY-E-RBAC.md`
para autorização.