# Arquitetura do Projeto Lotep (Loteria do Estado da Paraíba)

Este documento descreve a arquitetura técnica, os padrões de design e as tecnologias utilizadas no projeto Lotep, servindo como guia fundamental para qualquer intervenção de IA ou desenvolvedor humano.

## 1. Stack Tecnológica Base
- **Linguagem:** PHP 7.2+
- **Framework:** Laravel 5.5 (LTS na época de lançamento)
- **Banco de Dados:** PostgreSQL (com extensões PostGIS para geoprocessamento)
- **Frontend:** Laravel Blade, AdminLTE 1.22, jQuery, Angular (módulo parcial)
- **Autenticação/Autorização:** Cartalyst Sentinel 2.0 (Gerenciamento robusto de roles e permissões)
- **Geração de Documentos:** DomPDF e TCPDF (FPDF para serviços específicos)
- **Integração de Mapas:** PostGIS (suporte a coordenadas geográficas)

## 2. Estrutura de Diretórios e Responsabilidades

### `app/Models`
Contém as entidades do Eloquent. Devem ser leves, focando apenas em relacionamentos, scopes e cast de atributos.
- Exemplos: `Indicador.php`, `TipoJogoAutorizado.php`.

### `app/Repositories`
Implementa o **Repository Pattern**. Toda interação com o banco de dados que não seja trivial deve passar por aqui.
- `app/Repositories/Contracts`: Interfaces que definem o contrato de busca de dados.
- `app/Repositories/Eloquent`: Implementações concretas usando Eloquent.

### `app/Services`
Camada de lógica de negócio. Os Controllers devem delegar ações complexas para os Services.
- Exemplo: `FPdfService.php`.

### `app/Http/Presenters`
Utiliza o pacote `laracasts/presenter`. Responsável por formatar dados para a view sem poluir o Model ou a lógica do Service.

### `app/Http/Requests`
Validação centralizada de formulários usando FormRequests do Laravel.

### `app/Enum`
Centraliza constantes e tipos fixos para evitar "magic strings" e "magic numbers".

## 3. Fluxo de Dados (Data Flow)
1. **Request:** Capturada pelo `web.php` ou `api.php`.
2. **Controller:** Recebe a requisição, injeta o `Service` ou `Repository` necessário.
3. **Service:** Executa a lógica de negócio pesada, transações de DB, integrações.
4. **Repository:** Executa a query no banco de dados.
5. **View/Response:** Retorna o resultado usando `Presenters` para formatação visual.

## 4. Segurança e Permissões
- **Sentinel:** O sistema utiliza o Sentinel para controle de acesso. As permissões são granulares e vinculadas a perfis (`roles`).
- **Middleware:** Filtros de acesso em `app/Http/Middleware` garantem que apenas usuários autenticados e autorizados acessem rotas críticas.
- **Sanitização:** O uso de Eloquent/Query Builder previne SQL Injection. Inputs devem ser validados via FormRequests.
## 5. Convenções de Banco de Dados
- **Nomes de Tabelas:** Geralmente snake_case plural.
- **Chaves Primárias:** `id` auto-increment ou UUID conforme o módulo. Obrigatório em todas as tabelas.
- **Timestamps:** `created_at` e `updated_at` obrigatórios em quase todas as tabelas.
- **Soft Deletes:** Utilizado em entidades críticas para auditoria.
- **Categorização Unificada:** Novos módulos devem utilizar a tabela `[modulo]_categories` com coluna `type` para evitar poluição do schema.

## 6. Auditoria e Logs
- **Logs de Execução (Developer):** A prioridade para rastreamento técnico e depuração é o uso da facade nativa do Laravel `Log::[info|error|debug|...]`. Deve ser empregada para registrar o fluxo de execução, erros de sistema e eventos críticos de backend.
- **Spatie Activitylog (End-User/Audit):** Reservado para auditoria de negócio e rastreamento de mudanças em modelos sensíveis. Estes logs são persistidos no banco de dados (tabela `activity_log`) e destinam-se à visualização por usuários administrativos para fins de conformidade e histórico de alterações de dados.

## 7. Isolamento de Domínio (Namespace Prefixing)
Para garantir a rastreabilidade e integração contínua com o legado:
- **Prefixação:** Novas features devem usar prefixos claros (ex: `diarioOficial...` ou `diario_oficial...`) em todas as camadas (DB, Model, Controller, View).
- **Portal:** Estruturas públicas devem usar o sufixo/prefixo `Portal` (ex: `DiarioOficialPortalController`).

## 8. API e Documentação
...
- **Swagger:** O projeto utiliza `zircote/swagger-php`. A documentação da API é gerada automaticamente e fica disponível em `public/swagger.yml`.

## 8. Acessibilidade Digital
O projeto Lotep segue rigorosamente o padrão **eMAG** e **WCAG 2.1 nível AA**.
- **Instruções e Padrões:** Localizados em `@.agents/guidelines/accessibility/`. Toda interface Blade deve ser validada contra estes critérios.
- **Componentes:** O sistema integra a Barra de Acessibilidade GovBR e o VLibras.

## 📚 Documentação Adicional
- [V2 Interna - Nova Fundação Modular](v2/index.md)
- [Guia de Adição de Módulos de Pesquisa](ai-docs/20260401-Guia-Adicao-Modulos-Pesquisa.md)

---
*Este documento deve ser atualizado sempre que houver mudanças estruturais significativas no sistema.*