{"id":40608794,"url":"https://github.com/aron-alvarenga/minierp","last_synced_at":"2026-01-21T05:07:04.283Z","repository":{"id":333512152,"uuid":"1130032665","full_name":"aron-alvarenga/minierp","owner":"aron-alvarenga","description":"(🇺🇸) Modular Monolith ERP system built with Spring Boot 4.0.1 and Java 21. Demonstrates senior-level software architecture and best practices. (🇧🇷) Sistema ERP em Monólito Modular, construído com Spring Boot 4.0.1 e Java 21. Demonstra arquitetura de software e boas práticas em nível sênior.","archived":false,"fork":false,"pushed_at":"2026-01-19T15:55:09.000Z","size":57,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-19T22:02:40.346Z","etag":null,"topics":["ddd","domain-driven-design","enterprise-architecture","erp","gradle","h2-database","java","junit5","modular-monolith","portfolio","postgresql","spring-boot","spring-data-jpa","spring-framework","spring-security","testcontainers"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aron-alvarenga.png","metadata":{"files":{"readme":"README-PT-BR.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-07T23:50:59.000Z","updated_at":"2026-01-19T15:56:04.000Z","dependencies_parsed_at":"2026-01-19T22:02:57.987Z","dependency_job_id":null,"html_url":"https://github.com/aron-alvarenga/minierp","commit_stats":null,"previous_names":["aron-alvarenga/minierp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/aron-alvarenga/minierp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aron-alvarenga%2Fminierp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aron-alvarenga%2Fminierp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aron-alvarenga%2Fminierp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aron-alvarenga%2Fminierp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aron-alvarenga","download_url":"https://codeload.github.com/aron-alvarenga/minierp/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aron-alvarenga%2Fminierp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28627388,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T04:47:28.174Z","status":"ssl_error","status_checked_at":"2026-01-21T04:47:22.943Z","response_time":86,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ddd","domain-driven-design","enterprise-architecture","erp","gradle","h2-database","java","junit5","modular-monolith","portfolio","postgresql","spring-boot","spring-data-jpa","spring-framework","spring-security","testcontainers"],"created_at":"2026-01-21T05:07:01.690Z","updated_at":"2026-01-21T05:07:04.276Z","avatar_url":"https://github.com/aron-alvarenga.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mini-ERP\n\n\u003e **Monólito Modular** - Um ERP completo e profissional demonstrando arquitetura de software de nível pleno/sênior.\n\n[![Java](https://img.shields.io/badge/Java-21-orange.svg)](https://www.oracle.com/java/)\n[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-4.0.1-brightgreen.svg)](https://spring.io/projects/spring-boot)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n**🇺🇸 [Read in English](README.md)**\n\n## Sobre o Projeto\n\nO **Mini-ERP** é um sistema de gestão empresarial completo desenvolvido como **monólito modular**, onde cada módulo é isolado por pacote e se comunica através de interfaces bem definidas, sem acoplamento direto entre camadas de diferentes módulos. Este projeto demonstra maturidade arquitetural e boas práticas de engenharia de software, mantendo a simplicidade de execução local sem necessidade de infraestrutura complexa.\n\n### Objetivos\n\n- Demonstrar arquitetura **modular monolith** com boundaries claros\n- Implementar um ERP funcional com fluxos completos de negócio\n- Aplicar práticas de nível pleno/sênior (RBAC, auditoria, testes, observabilidade)\n- Servir como **portfólio técnico** demonstrando competências arquiteturais\n\n## Arquitetura\n\n### Conceito: Monólito Modular\n\nO projeto segue o padrão de **modular monolith**, onde:\n\n- Cada módulo é **isolado por pacote** com boundaries claros\n- Módulos se comunicam via **interfaces** (sem acoplamento direto)\n- **Acesso entre módulos apenas através de interfaces Facade/Port expostas no pacote `api`; todos os outros pacotes são internos**\n- Cada módulo possui sua própria estrutura interna (api, application, domain, infra, web)\n- **Sem dependências diretas** entre pacotes internos de diferentes módulos (apenas através de interfaces expostas)\n- Eventos internos para comunicação assíncrona (opcional)\n\n### Diagrama de Arquitetura Modular\n\n```mermaid\nflowchart TB\n    subgraph App[\"Mini-ERP Application\"]\n        Identity[identity]\n        Cadastro[cadastro]\n        Catalog[catalog]\n        Inventory[inventory]\n        Sales[sales]\n        Billing[billing]\n        Reporting[reporting]\n    end\n    \n    DB[(PostgreSQL)]\n    Security[Spring Security]\n    \n    %% Comunicação entre módulos via interfaces\n    Sales -.-\u003e|usa| Inventory\n    Sales -.-\u003e|usa| Catalog\n    Sales -.-\u003e|usa| Cadastro\n    Billing -.-\u003e|usa| Sales\n    Reporting -.-\u003e|usa| Sales\n    Reporting -.-\u003e|usa| Inventory\n    Reporting -.-\u003e|usa| Catalog\n    \n    %% Acesso ao banco (isolado por módulo)\n    Identity --\u003e DB\n    Cadastro --\u003e DB\n    Catalog --\u003e DB\n    Inventory --\u003e DB\n    Sales --\u003e DB\n    Billing --\u003e DB\n    Reporting --\u003e DB\n    \n    %% Security intercepta todas as requisições\n    Security -.-\u003e|protege| App\n    \n    style Identity fill:#e1f5ff\n    style Cadastro fill:#fff4e1\n    style Catalog fill:#e8f5e9\n    style Inventory fill:#f3e5f5\n    style Sales fill:#fce4ec\n    style Billing fill:#fff9c4\n    style Reporting fill:#e0f2f1\n    style DB fill:#e3f2fd\n    style Security fill:#ffebee\n```\n\n### Módulos Planejados\n\n#### 1. **identity** (Autenticação e Autorização)\n- Usuários, papéis e permissões\n- Auditoria: rastreamento de ações (quem fez o quê)\n- Spring Security + RBAC\n\n#### 2. **cadastro** (Cadastros Base)\n- Cliente (PF/PJ)\n- Fornecedor\n- Endereço e contatos\n\n#### 3. **catalog** (Produtos)\n- Produto, categoria, unidade de medida\n- Controle de custo e preço\n\n#### 4. **inventory** (Estoque)\n- Movimentações (entrada/saída/ajuste)\n- Saldo por produto com consistência\n- Controle de concorrência (optimistic locking)\n\n#### 5. **sales** (Vendas/Pedidos)\n- Pedido de venda e itens\n- Status: rascunho → aprovado → faturado/cancelado\n- Reserva e baixa no estoque\n\n#### 6. **billing** (Faturamento)\n- Geração de fatura/nota simplificada\n- Mock de pagamento\n- Idempotência (não faturar duas vezes o mesmo pedido)\n\n#### 7. **reporting** (Relatórios)\n- Top produtos vendidos\n- Curva ABC\n- Estoque abaixo do mínimo\n- Vendas por período\n\n## Stack Tecnológica\n\n### Core\n- **Java 21 LTS** - Linguagem de programação (recomendado; Spring Boot 4.0.1 requer Java 17+)\n- **Spring Boot 4.0.1** - Framework principal\n- **Spring Security** - Autenticação e autorização\n- **Spring Data JPA** - Persistência de dados\n- **Bean Validation** - Validação de dados\n\n### Banco de Dados\n- **PostgreSQL** - Banco de dados principal (via Docker Compose)\n- **H2 Database** - Banco em memória para desenvolvimento/testes rápidos\n- **Testcontainers** - Testes de integração com PostgreSQL real\n\n### Modos de Execução\n\nO projeto foi projetado para rodar **sem necessidade de infraestrutura complexa**, oferecendo três modos de execução:\n\n- **Desenvolvimento**: H2 em memória para rodar rapidamente sem configuração\n- **Testes de Integração**: Testcontainers com PostgreSQL real para garantir consistência\n- **Demo Local**: Docker Compose opcional para quem quer experimentar com PostgreSQL\n\nEsta abordagem demonstra maturidade de entrega: flexibilidade para diferentes cenários sem complexidade desnecessária.\n\n### Observabilidade\n- **Spring Boot Actuator** - Health checks, métricas e readiness\n- **Micrometer** - Métricas de aplicação (planejado)\n- **Spring AOP** - Auditoria e logs transversais\n- **Logs estruturados** - Com correlation ID para rastreabilidade\n\n### Testes\n- **JUnit 5** - Framework de testes\n- **Spring Boot Test** - Testes de integração\n- **Testcontainers** - Testes com PostgreSQL real\n- **Spring Security Test** - Testes de segurança\n\n### Ferramentas (planejadas)\n- **Flyway** - Migração de banco de dados\n- **Springdoc OpenAPI** - Documentação da API (Swagger)\n- **Lombok** - Redução de boilerplate (opcional)\n- **MapStruct** - Mapeamento DTO ↔ domínio (opcional)\n\n## Estrutura do Projeto\n\n```\nminierp/\n├── src/\n│   ├── main/\n│   │   ├── java/com/aronalvarenga/minierp/\n│   │   │   ├── identity/          # Módulo de autenticação/autorização\n│   │   │   ├── cadastro/          # Módulo de cadastros base\n│   │   │   ├── catalog/           # Módulo de produtos\n│   │   │   ├── inventory/         # Módulo de estoque\n│   │   │   ├── sales/             # Módulo de vendas\n│   │   │   ├── billing/           # Módulo de faturamento\n│   │   │   ├── reporting/         # Módulo de relatórios\n│   │   │   └── MinierpApplication.java\n│   │   └── resources/\n│   │       ├── application.properties\n│   │       └── db/migration/      # Flyway migrations (planejado)\n│   └── test/\n│       └── java/com/aronalvarenga/minierp/\n├── docker-compose.yml             # PostgreSQL local (opcional)\n├── build.gradle\n├── settings.gradle\n└── README.md\n```\n\n## Como Executar\n\n### Pré-requisitos\n\n- **Java 17+** (recomendado: **Java 21 LTS**)\n  - Spring Boot 4.0.1 requer Java 17 ou superior\n- **Gradle** (ou use o wrapper: `./gradlew`)\n- **Docker** e **Docker Compose** (para PostgreSQL - opcional, pode usar H2)\n\n### Executando Localmente\n\n1. **Clone o repositório**\n   ```bash\n   git clone https://github.com/aron-alvarenga/minierp.git\n   cd minierp\n   ```\n\n2. **Configure o banco de dados** (escolha uma opção)\n\n   **Opção A: H2 (recomendado para desenvolvimento rápido)**\n   - A aplicação usa H2 por padrão, sem necessidade de configuração adicional\n   - Ideal para desenvolvimento e testes rápidos\n   \n   **Opção B: PostgreSQL via Docker Compose (para demo local)**\n   ```bash\n   docker-compose up -d\n   ```\n   - Configure `application.properties` para usar PostgreSQL\n   - Ideal para quem quer experimentar com banco de dados real\n\n3. **Execute a aplicação**\n   ```bash\n   ./gradlew bootRun\n   ```\n   ou\n   ```bash\n   ./gradlew.bat bootRun  # Windows\n   ```\n\n4. **Acesse a aplicação**\n   - API: `http://localhost:8080`\n   - Actuator Health: `http://localhost:8080/actuator/health`\n   - Swagger UI: `http://localhost:8080/swagger-ui.html` (quando implementado)\n\n### Nota sobre Testes\n\nOs testes de integração utilizam **Testcontainers** para executar com PostgreSQL real, garantindo que os testes rodem em ambiente próximo ao de produção, mesmo que você use H2 durante o desenvolvimento.\n\n### Executando Testes\n\n```bash\n./gradlew test\n```\n\n## Fluxos Principais (MVP)\n\n### Fluxo 1: Ciclo Completo de Venda\n\n```mermaid\nflowchart LR\n    A[Cadastrar Produto\u003cbr/\u003ecatalog] --\u003e B[Entrada de Estoque\u003cbr/\u003einventory]\n    B --\u003e C[Criar Pedido\u003cbr/\u003esales]\n    C --\u003e D[Adicionar Itens\u003cbr/\u003esales + inventory]\n    D --\u003e E[Aprovar Pedido\u003cbr/\u003esales]\n    E --\u003e F[Faturar\u003cbr/\u003ebilling]\n    F --\u003e G[Baixar Estoque\u003cbr/\u003einventory]\n    G --\u003e H[Relatórios\u003cbr/\u003ereporting]\n    \n    style A fill:#e8f5e9\n    style B fill:#f3e5f5\n    style C fill:#fce4ec\n    style D fill:#fce4ec\n    style E fill:#fce4ec\n    style F fill:#fff9c4\n    style G fill:#f3e5f5\n    style H fill:#e0f2f1\n```\n\n### Detalhamento do Fluxo\n\n1. **Cadastrar Produto** → Criar produto no módulo `catalog`\n2. **Entrada de Estoque** → Registrar entrada no módulo `inventory`\n3. **Criar Pedido** → Criar pedido de venda no módulo `sales`\n4. **Aprovar Pedido** → Aprovar pedido (validações de domínio)\n5. **Faturar** → Gerar fatura no módulo `billing` (idempotente)\n6. **Baixar Estoque** → Atualizar estoque automaticamente\n7. **Relatório** → Consultar relatórios no módulo `reporting`\n\n## Segurança e Permissões\n\n### Papéis Planejados\n\n- **ADMIN** - Acesso total ao sistema\n- **VENDAS** - Gestão de pedidos e clientes\n- **ESTOQUE** - Gestão de estoque e produtos\n\n### Usuários Seed (planejado)\n\n- `admin` / `admin` - Administrador\n- `sales` / `sales` - Vendedor\n- `stock` / `stock` - Operador de estoque\n\n## Funcionalidades MVP\n\n- [x] Estrutura base do projeto\n- [ ] Autenticação e autorização (RBAC)\n- [ ] CRUD de Cliente\n- [ ] CRUD de Produto\n- [ ] Entrada manual de estoque\n- [ ] Criação e aprovação de pedido de venda\n- [ ] Geração de fatura com mock de pagamento\n- [ ] Auditoria (createdBy/updatedBy + log de eventos)\n- [ ] Relatórios: produtos mais vendidos e estoque baixo\n\n## Diferenciais Técnicos\n\n### Práticas de Nível Pleno/Sênior\n\n- **Idempotência** no faturamento\n- **Validações de domínio** robustas\n- **Controle de concorrência** (optimistic locking no estoque)\n- **Erros padronizados** (Problem Details / RFC 7807)\n- **Logs estruturados**\n- **Testes unitários** e de **integração** com Testcontainers\n- **Contratos entre módulos** testáveis\n\n## Testes\n\n### Estratégia de Testes\n\n- **Testes Unitários**: Domínio e casos de uso (regras de negócio, validações, idempotência)\n- **Testes de Integração**: Com Testcontainers (PostgreSQL real) - garantem consistência e comportamento próximo ao de produção\n- **Testes de Contrato**: Interfaces entre módulos (garantem boundaries modulares)\n- **Testes de Segurança**: Endpoints protegidos (RBAC por endpoint)\n\n**Nota**: Os testes de integração utilizam Testcontainers para executar com PostgreSQL real, mesmo que você use H2 durante o desenvolvimento. Isso garante que os testes validem o comportamento real da aplicação.\n\n### Executando Testes\n\n```bash\n# Todos os testes\n./gradlew test\n\n# Testes específicos\n./gradlew test --tests \"com.aronalvarenga.minierp.identity.*\"\n```\n\n## Documentação\n\n### Planejado\n\n- [ ] **ADRs** (Architecture Decision Records) em `docs/decision-records/`\n- [ ] **Diagramas** de arquitetura (Mermaid)\n- [ ] **Guia de contribuição**\n- [ ] **API Documentation** (Swagger/OpenAPI)\n\n## Roadmap\n\n### v1.0 - MVP (Atual)\n- Estrutura base e módulos core\n- Fluxo completo de venda\n- Autenticação e autorização\n- Relatórios básicos\n\n### v2.0 - Melhorias\n- [ ] Integração com APIs externas (CEP, CNPJ)\n- [ ] Dashboard com métricas\n- [ ] Exportação de relatórios (PDF/Excel)\n- [ ] Notificações (email)\n- [ ] Cache distribuído (Redis - opcional)\n\n### v3.0 - Expansão\n- [ ] Módulo de compras\n- [ ] Módulo financeiro (contas a pagar/receber)\n- [ ] Módulo de produção (se aplicável)\n- [ ] API GraphQL (opcional)\n\n## Contribuindo\n\nEste é um projeto de portfólio pessoal. Contribuições são bem-vindas! Sinta-se à vontade para abrir issues e pull requests.\n\n## Licença\n\nEste projeto está sob a licença MIT. Veja o arquivo [LICENSE](LICENSE) para mais detalhes.\n\n## Autor\n\n**Aron Alvarenga**\n\n- GitHub: [@aron-alvarenga](https://github.com/aron-alvarenga)\n- LinkedIn: [Aron Alvarenga](https://www.linkedin.com/in/aron-alvarenga)\n\n## Agradecimentos\n\n- Spring Framework e comunidade Spring\n- Todos os mantenedores das bibliotecas open-source utilizadas\n\n---\n\n**Nota**: Este projeto inicia com um conjunto mínimo de dependências. Outras bibliotecas são adicionadas somente quando uma necessidade arquitetural real surge, seguindo o princípio **YAGNI** (You Aren't Gonna Need It).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faron-alvarenga%2Fminierp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faron-alvarenga%2Fminierp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faron-alvarenga%2Fminierp/lists"}