# 02 — Arquitetura técnica

## Stack confirmada

| Camada | Tecnologia | Evidência |
|--------|------------|-----------|
| Runtime | PHP **8.3** | `.php-version`, `php -v` |
| Framework | Laravel **13.18.1** | `composer.json` `laravel/framework ^13.0`, `php artisan --version` |
| Frontend server-rendered | Blade + Livewire 3 | `livewire/livewire`, views `resources/views` |
| UI base | Material Dashboard (Creative Tim) evoluíada | `public/vendor/laravel-frontend-presets`, layout custom |
| Assets | Laravel Mix + Vite config presente | `webpack.mix.js`, `vite.config.js`, `package.json` |
| Auth web | Sessão Laravel + `laravel/ui` | `SessionsController`, middleware `auth` |
| API tokens | Sanctum (rota `/api/user`) | `laravel/sanctum`, `routes/api.php` |
| ACL | Spatie Permission 6 | `spatie/laravel-permission` |
| Planilhas | PhpSpreadsheet 5 | exports Excel |
| Captcha | anhskohbo/no-captcha | composer |
| HTTP client | Guzzle 7 | integrações |
| Banco | MySQL 8.0.46 · DB `simulador_tributa` | `php artisan db:show` |
| Queue | `sync` (config env) | `.env` `QUEUE_CONNECTION=sync` |
| Cache | file (example) | `.env.example` |
| Multi-tenant | coluna `idtenant` + `TenantScope` | `app/Scopes/TenantScope.php` |

## Diagrama lógico (CONFIRMADO)

```mermaid
flowchart TB
  subgraph Browser
    UI[Blade + Livewire + JS]
  end
  subgraph LaravelApp[Laravel 13 App]
    Web[routes/web.php]
    Api[routes/api.php]
    Ctrl[Controllers Admin/Api]
    Svc[Services ~53]
    Jobs[Jobs: ConsultaSimples / SyncClassTrib]
    Models[Eloquent Models ~50]
  end
  subgraph Data
    MySQL[(MySQL simulador_tributa)]
    Storage[storage/ uploads SPED]
  end
  subgraph External
    BrasilAPI[BrasilAPI CNPJ/CEP]
    SVRS[Portal SVRS ClassTrib]
    Brevo[Brevo SMTP API]
  end
  UI --> Web
  UI --> Api
  Web --> Ctrl
  Api --> Ctrl
  Ctrl --> Svc
  Svc --> Models
  Models --> MySQL
  Svc --> Storage
  Jobs --> Svc
  Svc --> BrasilAPI
  Svc --> SVRS
  Ctrl --> Brevo
```

## Padrões arquiteturais observados

| Padrão | Uso | Classificação |
|--------|-----|---------------|
| Controllers finos/médios + Services ricos | Núcleo fiscal em `app/Services/*` | CONFIRMADO |
| Sem camada Repository dedicada | Não há `app/Repositories` | CONFIRMADO ausência |
| TenantScope global em models de negócio | Quase todos os models | CONFIRMADO |
| Validação inline nos controllers | Sem `FormRequest` | CONFIRMADO |
| Eventos de domínio Laravel | Pouco uso; auditoria via service | CONFIRMADO |
| Versionamento por snapshot JSON | `simulacao_versao`, `reforma_*_versao` | CONFIRMADO |
| Legado ERP coexistente | Controllers eventos/empresas/NF rastros | CONFIRMADO / LEGADO |

## Estrutura de diretórios relevante

```
app/
  Console/Commands/     SyncClassTribCommand
  Dto/                  PendenciaDto
  Exceptions/           SimulacaoBloqueadaException
  Http/Controllers/Admin|Api
  Http/Livewire/        Evento*, SpedRelatorio*
  Http/Middleware/      AdminTenant, SingleSession, ...
  Jobs/
  Mail/                 ResetPasswordMail (aparentemente não usado no fluxo Brevo)
  Models/
  Scopes/TenantScope.php
  Services/             núcleo de negócio
  Support/              CnpjHelper, UnidadeMedidaSped
  Traits/HandlesFileUploads.php
database/migrations/    119 arquivos (inclui legado)
resources/views/admin/  telas do produto
routes/web.php | api.php | console.php
docs/                   documentação de produto/escopo/manual
```

## Autenticação e sessão

1. Login em `/sign-in` (`SessionsController`).
2. Middleware `single.session`: compara `users.idsession` com `Session::getId()` — impede múltiplas sessões simultâneas (**CONFIRMADO**).
3. Pós-login: redirect para simulações (**CONFIRMADO** no inventário de telas / SessionsController).
4. Reset de senha: Brevo API HTTP (**CONFIRMADO** `ForgotPasswordController`).

## Isolamento multi-tenant

- Usuário possui `idtenant`.
- Models aplicam `TenantScope`.
- Controllers do simulador filtram por `$request->user()->idtenant`.
- Middleware `admin.tenant`: somente tenant com `is_admin_tenant = 1` acessa gestão de tenants.

## Configurações de negócio relevantes

Procurar em `config/` (especialmente reforma tributária / ClassTrib). Evidência de config referida em services: `reforma_tributaria.classtrib.*`, alíquotas indicativas Simples, lote SPED.

## Infraestrutura identificável

| Item | Evidência |
|------|-----------|
| Deploy FTP | `.ftp-deploy-sync-state.json`, pasta `deploy/` |
| GitHub Actions | `.github/` |
| Ambiente local virtual host | `simulador-tributario.local` |
| Debugbar | `barryvdh/laravel-debugbar` (dev) |

## Dependências npm (runtime UI)

`bootstrap-select`, `cep-promise`, `flatpickr`, `jquery-mask-plugin` + axios/lodash via Mix.