Skip to content

Commit 6527dbb

Browse files
Abega1642Abega1642
committed
feat: add readme file
1 parent f380447 commit 6527dbb

File tree

1 file changed

+206
-0
lines changed

1 file changed

+206
-0
lines changed

‎readme.md‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
<h1 align="center">🚀 ar-infra-template</h1>
2+
3+
<p align="center">
4+
<b>Production-ready Spring Boot Infrastructure Template</b><br>
5+
Author: <a href="https://github.com/Abega1642">Abegà Razafindratelo</a><br>
6+
Repository: <a href="https://github.com/Abega1642/ar-infra-template.git">ar-infra-template</a>
7+
</p>
8+
9+
<p align="center">
10+
<img src="https://img.shields.io/github/license/Abega1642/ar-infra-template?style=for-the-badge&color=blue" alt="License"/>
11+
<img src="https://img.shields.io/github/actions/workflow/status/Abega1642/ar-infra-template/ci-build.yml?style=for-the-badge&logo=github" alt="Build Status"/>
12+
<img src="https://img.shields.io/github/actions/workflow/status/Abega1642/ar-infra-template/ci-test.yml?style=for-the-badge&logo=github&label=tests" alt="Tests"/>
13+
<img src="https://img.shields.io/github/actions/workflow/status/Abega1642/ar-infra-template/ci-codeql.yml?style=for-the-badge&logo=github&label=CodeQL" alt="CodeQL"/>
14+
<img src="https://img.shields.io/github/actions/workflow/status/Abega1642/ar-infra-template/ci-qodana.yml?style=for-the-badge&logo=jetbrains&label=Qodana" alt="Qodana"/>
15+
<img src="https://img.shields.io/github/actions/workflow/status/Abega1642/ar-infra-template/ci-semgrep.yml?style=for-the-badge&logo=semgrep&label=Semgrep" alt="Semgrep"/>
16+
</p>
17+
18+
---
19+
20+
<h2>📖 Overview</h2>
21+
22+
<p>
23+
<code>ar-infra-template</code> is a <b>production-ready Spring Boot template</b> designed to be generated via the companion CLI tool
24+
<a href="https://github.com/Abega1642/ar-infra-cli.git">ar-infra-cli</a>.
25+
</p>
26+
27+
<p>
28+
Instead of starting from scratch, developers can generate a fully configured Spring Boot project with messaging, storage, database, email, security, health checks, CI/CD, and Docker support already wired in. This ensures teams can focus on <b>business logic</b> rather than infrastructure setup.
29+
</p>
30+
31+
<p><b>⚠️ Note:</b> This repository is <i>not intended to be cloned and customized manually</i>. It serves as the <b>base template</b> for <code>ar-infra-cli</code>.</p>
32+
33+
---
34+
35+
<h2>🛠️ Features</h2>
36+
37+
<p>
38+
This template comes with everything you need to run a backend service in production:
39+
</p>
40+
41+
<ul>
42+
<li><b>Messaging</b>: RabbitMQ configured for async tasks and queues.</li>
43+
<li><b>Storage</b>: Backblaze S3-compatible bucket integration.</li>
44+
<li><b>Database</b>: PostgreSQL with Flyway migrations.</li>
45+
<li><b>Email</b>: Ready-to-use mailer service with health checks.</li>
46+
<li><b>Security</b>: Default <code>SecurityConf</code> to be customized.</li>
47+
<li><b>Health checks</b>: Endpoints for bucket, email, events, repository, and ping.</li>
48+
<li><b>Testing</b>: Unit + integration tests with Testcontainers.</li>
49+
<li><b>Documentation</b>: OpenAPI spec (<code>doc/api.yaml</code>) rendered via Swagger UI.</li>
50+
<li><b>CI/CD</b>: GitHub Actions for build, test, format, CodeQL, Qodana, Semgrep.</li>
51+
<li><b>Dockerized</b>: Multi-stage Dockerfile with health checks and non-root user.</li>
52+
</ul>
53+
54+
---
55+
56+
<h2>📂 Project Structure</h2>
57+
58+
<p>
59+
The project follows a clean architecture with clear separation of concerns. Each package has a specific responsibility:
60+
</p>
61+
62+
<table>
63+
<tr><td><b>config/</b></td><td>Spring bean configurations (BucketConf, EmailConf, RabbitConfig, SecurityConf, SwaggerDocConf, ObjectMapperConfig).</td></tr>
64+
<tr><td><b>datastructure/</b></td><td>Algorithmic utilities (e.g., ListGrouper for batch processing).</td></tr>
65+
<tr><td><b>event/</b></td><td>Messaging foundations (consumers, producers, event models). Developers add new events here.</td></tr>
66+
<tr><td><b>exception/</b></td><td>Custom exceptions for bucket, email, health, file. REST handler lives in <code>endpoint/ApiExceptionHandler</code>.</td></tr>
67+
<tr><td><b>endpoint/</b></td><td>REST API layer: controllers, health endpoints, error models, global exception handler.</td></tr>
68+
<tr><td><b>file/</b></td><td>File utilities: BucketComponent, sanitizers, converters, temp file managers.</td></tr>
69+
<tr><td><b>repository/</b></td><td>Persistence layer: JPA entities + repositories.</td></tr>
70+
<tr><td><b>mail/</b></td><td>Email infrastructure: Email + Mailer service.</td></tr>
71+
<tr><td><b>service/</b></td><td>Business logic: core services, health services, utilities.</td></tr>
72+
<tr><td><b>manager/</b></td><td>Orchestration layer: placeholder for managers coordinating multiple services.</td></tr>
73+
<tr><td><b>model/</b></td><td>Core domain models (business entities).</td></tr>
74+
<tr><td><b>mapper/</b></td><td>Mapping layer bridging DTOs, domain models, and persistence entities (Diamond Model).</td></tr>
75+
<tr><td><b>resources/db/migration/</b></td><td>Flyway migration scripts for schema evolution.</td></tr>
76+
</table>
77+
78+
---
79+
80+
<h2>🧪 Testing Philosophy</h2>
81+
82+
<p>
83+
Testing is split into two layers:
84+
</p>
85+
86+
<ul>
87+
<li><b>Unit tests</b> (<code>MyClassTest</code>): Validate isolated class logic with mocks.</li>
88+
<li><b>Integration tests</b> (<code>MyClassIT</code>): Extend <code>FacadeIT</code> to bootstrap real infrastructure via Testcontainers.</li>
89+
</ul>
90+
91+
<p>
92+
<code>FacadeIT</code> ensures containers (Postgres, RabbitMQ, S3, Email) are started once per JVM, stopped gracefully, and dynamically injected into the Spring context. This guarantees <b>end-to-end reliability</b>.
93+
</p>
94+
95+
---
96+
97+
<h2>🌍 Environment Management</h2>
98+
99+
<p>
100+
Environment variables are managed through:
101+
</p>
102+
103+
<ul>
104+
<li><b>.env.template</b>: Placeholder for production/preproduction variables (RabbitMQ, DB, S3, Mail).</li>
105+
<li><b>.env</b>: Developers fill in real values per environment.</li>
106+
<li><b>EnvConf</b>: Injects test-safe environment variables dynamically during integration tests.</li>
107+
<li><b>SecurityConf</b>: Default security setup, intended to be customized.</li>
108+
</ul>
109+
110+
---
111+
112+
<h2>📑 API Documentation</h2>
113+
114+
<p>
115+
API documentation is built-in:
116+
</p>
117+
118+
<ul>
119+
<li><b>OpenAPI spec</b>: <code>doc/api.yaml</code></li>
120+
<li><b>Swagger UI</b>: Accessible at <code>/doc</code></li>
121+
<li><b>Default endpoints</b>: <code>/ping</code>, <code>/health/bucket</code>, <code>/health/email</code>, <code>/health/message</code>, <code>/health/db</code></li>
122+
</ul>
123+
124+
<p>
125+
Developers simply edit <code>doc/api.yaml</code> to describe their APIs, and Swagger UI renders them automatically.
126+
</p>
127+
128+
---
129+
130+
<h2>🐳 Dockerization</h2>
131+
132+
<p>
133+
The template includes a multi-stage Dockerfile:
134+
</p>
135+
136+
<ul>
137+
<li>Stage 1: Gradle build (<code>bootJar</code>).</li>
138+
<li>Stage 2: Eclipse Temurin JRE runtime.</li>
139+
<li>Non-root user: <code>spring</code>.</li>
140+
<li>Healthcheck: <code>/actuator/health</code>.</li>
141+
<li>Entrypoint: <code>docker-start.sh</code>.</li>
142+
</ul>
143+
144+
---
145+
146+
<h2>🔄 CI/CD Workflows</h2>
147+
148+
<p>
149+
GitHub Actions workflows are located in <code>.github/workflows</code>:
150+
</p>
151+
152+
<ul>
153+
<li><code>ci-build.yml</code> → Docker build</li>
154+
<li><code>ci-test.yml</code> → Unit + integration tests</li>
155+
<li><code>ci-format.yml</code> → Code formatting check with Google Java Format</li>
156+
<li><code>ci-codeql.yml</code> → Security analysis with GitHub CodeQL</li>
157+
<li><code>ci-qodana.yml</code> → Static analysis with JetBrains Qodana</li>
158+
<li><code>ci-semgrep.yml</code> → Security linting with Semgrep</li>
159+
</ul>
160+
161+
<p>
162+
These workflows ensure that every commit and pull request is automatically validated for build integrity, test coverage, code formatting, and security compliance.
163+
</p>
164+
165+
---
166+
167+
<h2>📌 Related Projects</h2>
168+
169+
<ul>
170+
<li><b>ar-infra-cli</b> → <a href="https://github.com/Abega1642/ar-infra-cli.git">GitHub Repository</a><br>
171+
CLI tool that generates Spring Boot projects using this template.</li>
172+
</ul>
173+
174+
<p>
175+
The CLI is the intended way to use <code>ar-infra-template</code>. It automates project generation with commands like:
176+
</p>
177+
178+
```bash
179+
ar-infra generate --group=com.example --artifact=myapp
180+
```
181+
182+
<p>
183+
This produces a fully configured Spring Boot project with infrastructure, tests, CI/CD, and Docker support ready to run.
184+
</p>
185+
186+
---
187+
188+
<h2>📝 License</h2>
189+
190+
<p>
191+
This project is licensed under the <b>MIT License</b>.<br>
192+
© <b>Abegà Razafindratelo</b>
193+
</p>
194+
195+
---
196+
197+
<h2>🎯 Purpose</h2>
198+
199+
<p>
200+
The purpose of <code>ar-infra-template</code> is to serve as a <b>foundation for generated projects</b> via <code>ar-infra-cli</code>.
201+
While developers <i>can</i> clone and customize it manually, the intended workflow is to use the CLI for effortless generation of production-ready Spring Boot applications.
202+
</p>
203+
204+
<p>
205+
By combining infrastructure, testing, documentation, CI/CD, and Dockerization, this template ensures that every generated project starts with <b>enterprise-grade readiness</b>.
206+
</p>

0 commit comments

Comments
 (0)