Crystallized Perl
Um stack completo e opinativo para construir serviços de internet modernos em Perl — aplicações web, APIs HTTP e workers em background — fundamentado em referências reais e decisões arquiteturais documentadas.
O que é este projeto
Crystallized Perl define um stack — não um cardápio de opções. Cada camada tecnológica está documentada em uma Architectural Decision Record (ADR) com motivação, alternativas consideradas e consequências. Cada decisão rastreia ao menos uma fonte externa autoritativa.
O projeto cobre:
- Aplicações web com HTML server-rendered e SPAs com backend Perl
- APIs HTTP: REST, GraphQL e WebSocket
- Workers em background e filas de jobs
- Autenticação, autorização e gerenciamento de sessões
- Observabilidade: logging, métricas e rastreamento distribuído
- Containerização com Docker e implantação cloud-native
- Pipelines de CI/CD e estratégia de testes
Por onde começar
Novo no stack
Siga a trilha de guias — cada um pressupõe o anterior:
| Guia | O que cobre |
|---|---|
| Guia 1 — Ambiente de Desenvolvimento | Perl 5.42, Carton, Docker Compose com PostgreSQL/RabbitMQ/Keycloak |
| Guia 2 — Estrutura Mínima de Projeto | cpanfile, .gitattributes, DEVELOPMENT.md — esqueleto da Stega |
| Guia 3 — Primeira Rota com Mojolicious | Stega.pm, controller, GET /healthz, Test::Mojo |
Referência por tecnologia
A seção Stack tem uma página por tecnologia com comandos essenciais e padrões de uso no contexto da Stega: Mojolicious · Carton · Moo · PostgreSQL · Mojo::Pg · RabbitMQ · Keycloak · Docker · Kubernetes · OpenAPI · Testes
Entenda as decisões
As primeiras quatro ADRs estabelecem o padrão de documentação e a identidade do projeto:
| ADR | Decisão |
|---|---|
| ADR-000 | Padrão de registro de decisões (este formato) |
| ADR-001 | Nome oficial: Crystallized Perl |
| ADR-002 | Mascote: Raptor Cristalizado |
| ADR-003 | Paleta de cores e tipografia |
Explore as referências
O projeto mantém uma biblioteca anotada de 36 fontes externas que fundamentam cada decisão arquitetural — livros, documentações oficiais, RFCs e referências da comunidade.
Princípios não negociáveis
- Reference-first — toda decisão cita ao menos uma fonte externa documentada
- Decision transparency — cada escolha significativa tem uma ADR com motivação e alternativas
- Stack cohesion — este projeto define um stack, não um menu de opções
- Modern Perl — Perl 5.42+ obrigatório; padrões arcaicos explicitamente proibidos
- Cloud-native first — tudo roda em containers; desenvolvimento local usa Docker Compose
Contribuindo
Leia o guia de contribuição antes de abrir um pull request. Em especial as seções sobre como propor uma nova ADR e como corrigir erros de conteúdo.