chronicle

GitLab Project Metadata:

• Description: Resilient, high-performance Crystal application blueprint engineered for concurrency, rootless Podman execution, and zero-defect quality.
• Topics / Tags: crystal, crystal-lang, application, cli, daemon, podman, systemd, quadlet, ameba, flaw, sphinx, crstlint, agplv3

---

Overview

Chronicle provides a robust, production-ready foundation for developing standalone Crystal applications, daemons, background workers, and CLI utilities. It encapsulates best practices for multi-threaded concurrency, strict static analysis, structured logging, graceful signal handling, and containerized deployment with Podman.

Key Highlights

1. Multi-Threaded Concurrency: Built with native execution contexts, fibers, and thread-safe synchronization.
2. Defensive Typing & Zero Suppression: Strict type flow analysis, defensive nil-handling, and zero linter warning suppression.
3. Structured Configuration: Strongly-typed environment and CLI configuration with validation.
4. Rootless Podman Containerization: Multi-stage Containerfile and systemd Quadlet integration.
5. Multi-Tier Documentation Suite: Full Sphinx technical, functional, business, ADR, and API reference documentation.

---

Quickstart

Prerequisites

• Crystal: >= 1.21.0
• Shards: Bundled with Crystal
• GNU Make & Git
• Podman (optional, for container runs)
• cRSTLint (for documentation linting)

Build and Run Locally

# 1. Clone repository
git clone https://gitlab.com/renich/chronicle.git
cd chronicle

# 2. Setup dependencies and pre-commit hooks
make setup

# 3. Build the binary
make build

# 4. Run application CLI
./bin/chronicle --help

Running with Podman

# Build container image with Podman
make containers-build

# Run containerized service
make containers-run

---

Build System Targets

The repository includes a comprehensive, standard GNUmakefile:

Target	Description
make build	Compiles debug binary in bin/chronicle
make release	Builds stripped, statically optimized production binary
make test	Executes the complete spec test suite (crystal spec)
make lint	Runs Ameba static analysis and Flaw SAST security scanner
make doc-check	Lints all reStructuredText files using crstlint and rstcheck
make check	Aggregates test, lint, and doc-check
make install	Installs binary to $(DESTDIR)$(bindir) (FHS compliant)
make install-local	Installs binary to ~/.local/bin/chronicle
make containers-build	Builds rootless container image using Podman
make clean	Cleans build artifacts in bin/
make distclean	Removes dependencies, cache directories, and build outputs

---

Documentation

Full architectural blueprints, functional specifications, and operational playbooks are maintained under docs/:

Guide	Scope & Highlights	Entry Point
Business Context & Strategy	Stakeholder requirements, ROI objectives, and user personas.	Business Specs
Functional Specifications	Requirements [FUNC-001]–[FUNC-005] and behavioral contracts.	Functional Specs
Technical Architecture	Process lifecycle, concurrency model, and threat modeling.	Technical Specs
Release Playbook	SemVer, Keep a Changelog, and GPG-signed GitLab release steps.	Release Procedure
Architecture Decisions (ADRs)	Immutable logs of architectural decisions and trade-offs.	ADR Index
Project Roadmap	Phased milestone tracking and delivery roadmaps.	Project Roadmap
Crystal API Reference	Compiler-generated API reference.	API Reference

---

Contributing & Code of Honor

All contributions must adhere to the Universal Code of Honor and Contributing Guidelines.

---

License

• Software: GNU Affero General Public License v3.0 or later (LICENSE).
• Documentation: GNU Free Documentation License v1.3 or later (LICENSE-DOCS).

Copyleft © 2026 Rénich Bon Ćirić <renich@evalinux.com>.

---

Support & Donations

If you find this project useful and wish to support its ongoing development, please consider donating: