Arquitetura e Tecnologia

🏛️

Visão Geral da Arquitetura

Design orientado a serviços, escalabilidade e separação de responsabilidades

O ALMA (Alfabetização Mobile para Adultos) é uma solução de tecnologia educacional concebida no âmbito da pesquisa científica da Universidade Estadual do Norte do Paraná (UENP). A infraestrutura adota uma arquitetura em camadas (Layered Architecture), desacoplando a camada de apresentação mobile da camada de serviços e persistência de dados.

📱 Camada do Cliente

Aplicativo Móvel Android (APK) & Interface Web adaptada.

UI acessível para adultos em letramento
Gravação/reprodução de áudio nativa
Consumo seguro de JSON via HTTPS
Cache de progresso e estado

⚡ API REST & Core

Backend em Laravel 11 com Sanctum Authentication.

Service Layer desacoplada
Pipeline de middlewares de segurança
Validação estrita de contratos de dados
Gestão de arquivos de áudio multipart

📊 Gestão & Pesquisa

Painel Administrativo Filament v3 & Persistência.

Livewire 3 + Alpine.js + Tailwind
Relatórios quantitativos em tempo real
Banco relacional com integridade estrita
Documentação viva via OpenAPI (Scribe)

Essa abordagem assegura independência tecnológica entre o aplicativo cliente e o backend, permitindo evolução contínua das interfaces sem quebrar contratos de dados pré-estabelecidos.

💻

Stack Tecnológica Completa

Ferramentas, frameworks e linguagens de última geração

Todas as tecnologias foram selecionadas visando alta performance, tipagem estrita, robustez para pesquisa longitudinal e conformidade com os mais rigorosos padrões da indústria:

Backend Core

PHP 8.3 & Laravel 11.x

O ecossistema backend emprega a versão estável mais recente do PHP com tipagem estrita, combinada com o framework Laravel 11, aproveitando o motor de injeção de dependências, migrations versionadas e ORM Eloquent.

PHP 8.3+ Laravel 11 Eloquent ORM Artisan CLI

Painel de Pesquisa

Filament Admin v3

Interface de gestão administrativa e análise de dados de pesquisa construída sobre a TALL stack (Tailwind CSS, Alpine.js, Laravel e Livewire 3), proporcionando reatividade sem necessidade de build complexo no frontend.

Filament v3 Livewire 3 Alpine.js Tailwind CSS

Segurança & Auth

Laravel Sanctum

Emissão e validação de Personal Access Tokens (Bearer Tokens) ultraleves e stateless para autenticação no aplicativo mobile, integrando sanitização via middleware dedicado e revogação imediata em logouts.

Sanctum 4.x Bearer Auth Bcrypt Hash Middleware Pipeline

Banco de Dados

Persistência Relacional

Esquema de banco de dados modelado com integridade referencial rigorosa, chaves estrangeiras com ações em cascata seguras e suporte a SQLite para ambientes rápidos e MySQL/PostgreSQL para ambientes de produção.

MySQL / PostgreSQL SQLite Dev/Test Foreign Keys Indexed Queries

API Docs

Knuckles Scribe & OpenAPI

Geração automatizada de documentação interativa de endpoints a partir do código-fonte e docblocks do Laravel, exportando especificações padronizadas compatíveis com OpenAPI 3.0 e Swagger.

Scribe 5.x OpenAPI 3.0 Interactive UI

Qualidade & TDD

Pest PHP & Laravel Pint

Suíte de testes automatizados unitários e de integração utilizando Pest PHP para validação de endpoints e fluxos educacionais, além de formatação estrita de código com Laravel Pint (PSR-12).

Pest PHP 3.x PHPUnit Laravel Pint PSR-12

📐

Padrões de Projeto (Design Patterns)

Princípios de arquitetura aplicados para manutenibilidade e isolamento

O projeto segue os princípios fundamentais de engenharia de software SOLID e aplica padrões de projeto clássicos para manter o código limpo, testável e de fácil evolução:

1. Service Layer Pattern (Camada de Serviços) Arquitetural

A lógica de negócio central não fica acoplada às rotas ou controladores HTTP. Foram criadas classes de serviço dedicadas (AuthService, LessonService, PreTestService, PostTestService, InitialInterviewService e FinalInterviewService). Isso permite reutilizar a inteligência pedagógica em testes automatizados, comandos CLI ou novas APIs sem duplicar código.

2. Active Record & Data Modeling (Eloquent ORM) Estrutural

Cada entidade pedagógica (Module, Lesson, LessonStep, PreTest, PostTestScript, InitialInterview) é representada por um modelo de domínio rico, com declaração explícita de relacionamentos (HasMany, BelongsTo), atributos tipados e métodos utilitários que evitam consultas manuais vulneráveis a SQL Injection.

3. Intercepting Filter / Middleware Pipeline Comportamental

O fluxo de requisições passa por uma cadeia de filtros configuráveis (SanctumAuthMiddleware, CORS e Rate Limiting). Requisições não autorizadas, malformadas ou expiradas são bloqueadas antes mesmo de atingirem a camada de serviços, garantindo segurança perimetral eficiente.

4. Eager Loading (Otimização de Consultas N+1) Performance

Na recuperação da árvore curricular de módulos, lições e passos, o sistema utiliza o carregamento antecipado (with('lessons.steps')). Isso reduz dezenas de consultas ao banco de dados para apenas 2 a 3 queries otimizadas, garantindo resposta instantânea em conexões 3G/4G no celular.

5. Resource Management Pattern (Filament Panels) Apresentação

A gestão administrativa segue o padrão de Resources declarativos, onde cada classe de recurso define formulários, tabelas, filtros e permissões de forma coesa, isolando regras de apresentação administrativa do restante da aplicação.

🔄

Ciclo de Aprendizagem & Fluxo de Dados

A jornada do usuário mapeada nos endpoints técnicos do sistema

O fluxo pedagógico do ALMA foi cuidadosamente desenhado para apoiar o estudante adulto desde o diagnóstico inicial até a conclusão dos módulos:

1

Entrevista Inicial Diagnóstica

Coleta dados sociodemográficos, histórico de escolarização e expectativas, fornecendo a base para o acompanhamento longitudinal.

2

Pré-Teste Avaliativo

Avaliação diagnóstica de leitura e escrita dividida em 4 eixos (palavras, subpalavras, frases e identificação visual).

3

Trilha de Lições com Retomada

Lições em passos sequenciais multimídia. O endpoint /user/progress/resume detecta exatamente onde o aluno parou.

4

Pós-Testes e Gravação de Áudio

Validação da evolução de letramento através de pós-testes somativos e gravação de áudio na entrevista final para análise fonética.

Principais Contratos da API RESTful

Método	Endpoint	Camada / Serviço	Descrição Funcional
POST	/api/login	`AuthService`	Autenticação do aluno e emissão do Bearer Token.
GET	/api/initial-interview	`InitialInterviewService`	Recupera questionário e histórico da entrevista diagnóstica.
GET	/api/pre-test	`PreTestService`	Carrega as questões do teste diagnóstico inicial.
GET	/api/modules	`LessonService`	Lista todos os módulos curriculares disponíveis.
GET	/api/user/progress/resume	`LessonService`	Identifica a última etapa concluída para retomar o estudo.
POST	/api/post-tests/submit	`PostTestService`	Submete e corrige as respostas do pós-teste somativo.
POST	/api/final-interview/{id}/audio	`FinalInterviewService`	Upload multipart do registro de voz da entrevista final.

🛡️

Segurança, Privacidade & Conformidade

Alinhamento com a LGPD e diretrizes de publicação do Google Play

Por se tratar de um projeto de pesquisa universitária com sujeitos humanos, o rigor ético e a segurança cibernética são prioritários em todos os componentes:

✔ Exclusão de Conta e Dados Pessoais (LGPD & Google Play): Sistema completo e público disponível em /delete-account, permitindo que qualquer participante solicite a revogação de consentimento e expurgo imediato de seus dados pessoais.
✔ Criptografia em Repouso e em Trânsito: Comunicação 100% sob protocolo HTTPS com TLS 1.3. Senhas armazenadas com algoritmos de derivação de chaves seguros (Bcrypt com custo computacional ajustado).
✔ Proteção contra Ameaças Comuns da Web: Proteção integrada contra ataques de CSRF (Cross-Site Request Forgery), sanitização automática contra XSS (Cross-Site Scripting) e uso exclusivo de Prepared Statements para mitigação de SQL Injection.
✔ Tratamento Ético de Áudio: Arquivos de gravação de voz enviados durante as entrevistas são armazenados em diretórios protegidos do sistema com acesso restrito aos pesquisadores cadastrados no projeto.

👁️

Acessibilidade & Usabilidade Cognitiva

Engenharia de interface desenhada para adultos em processo de letramento

O desenvolvimento de software para o público de jovens e adultos não-alfabetizados impôs desafios singulares de UX (Experiência do Usuário), superados através de diretrizes de design universal:

🔊 Feedback Multimodal (Auditivo e Visual):

Em todas as atividades, os enunciados podem ser ouvidos com um único toque, eliminando barreiras para usuários que ainda não decodificam o texto escrito.

🎨 Alto Contraste e Tipografia Acessível:

Uso da família tipográfica Outfit, desenhada com formas geométricas abertas e distinção clara entre caracteres facilmente confundidos (ex: I, l, 1). Razão de contraste em conformidade com o nível AA da WCAG.

👆 Áreas de Toque Expandidas:

Botões e elementos interativos possuem dimensões mínimas de 48x48 dp, facilitando a interação de idosos e pessoas com menor precisão motora ao manusear a tela touch.

Arquitetura & Especificação Técnica