renich/chronicle: Autonomous workday telemetry harvester and context engine for Linux/Wayland

Resilient, high-performance Crystal application blueprint engineered for concurrency, rootless Podman execution, and zero-defect quality.

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

Multi-Threaded Concurrency: Built with native execution contexts, fibers, and thread-safe synchronization.
Defensive Typing & Zero Suppression: Strict type flow analysis, defensive nil-handling, and zero linter warning suppression.
Structured Configuration: Strongly-typed environment and CLI configuration with validation.
Rootless Podman Containerization: Multi-stage Containerfile and systemd Quadlet integration.
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