Chronodash

Project Overview

Chronodash is a multi-datasource monitoring and metrics collection system built with Elixir, Phoenix, and the Ash Framework. It is designed to collect, store, and visualize time-series metrics from various providers (currently only MeteoSIX) and display them in Grafana.

Key Architecture Concepts

1. Generic Polling Engine – Orchestrates data collection from multiple sources using a standardized pipeline.
2. Standardized Data Contract – All DataSources return a unified ObservationData struct, decoupling fetching logic from persistence.
3. Ash Framework – Manages the domain logic and persistence layer with high-performance bulk operations.
4. TimescaleDB – Optimized storage for time-series observations, enabling efficient long-term data retention and fast queries.
5. Observability – Integrated with PromEx for system metrics and Grafana for business/weather metrics.

---

Project Structure

.
├── .env                        # Environment variables (API keys, DB credentials, etc.)
├── .gitignore                  # Git ignore rules
├── Makefile                    # Automation scripts (deploy, attach, db-up, etc.)
├── config/                     # Configuration files
├── docker/                     # Deployment infrastructure
├── etc/                        # Provisioning and configuration
│   ├── grafana/                # Dashboards and Datasource provisioning
│   └── prometheus/             # Scraping configuration
├── lib                         # Main Elixir source code
│   ├── chronodash/             # Core Application
│   │   ├── accounts/           # Ash Domain: User management
│   │   ├── datasource/         # High-level data orchestration
│   │   ├── metrics/            # Ash Domain: Locations and Observations
│   │   ├── models/             # Standardized DTOs and internal contracts
│   │   ├── polling/            # Generic Polling Engine (Supervisors/Workers)
│   │   └── prom_ex/            # Custom metrics plugins
│   ├── chronodash_web/         # Phoenix Web Layer
│   ├── http_client/            # Centralized HTTP client (Finch + Req)
│   └── meteosix/               # MeteoSIX API v5 Client
├── priv                        # Database and static resources
│   ├── repo/migrations/        # TimescaleDB hypertable migrations
│   └── specs/schema.dbml       # Database design documentation
└── test                        # Unit and integration tests
    ├── chronodash/             # Core logic tests
    └── support/                # Mock clients and test cases

feat/add-docs

Dependencies

This document lists all dependencies used in Chronodash, their purpose, and relevant version information.

---

Core Stack

Technology	Version	Purpose
Elixir	~> 1.15	Primary programming language
Phoenix Framework	~> 1.8.1	Web framework and API layer
PostgreSQL	latest	Primary relational database
Docker	latest	Local development environment

---

Backend Dependencies

Framework & Web

Package	Version	Purpose	License
phoenix	~> 1.8.1	Web framework — routing, controllers, endpoints	MIT
bandit	~> 1.5	HTTP server (replaces Cowboy)	MIT
phoenix_ecto	~> 4.5	Phoenix and Ecto integration	MIT
gettext	~> 0.26	Internationalization and translations	MIT

Data Layer

Package	Version	Purpose	License
ecto_sql	~> 3.13	SQL query interface for Ecto	Apache 2.0
postgrex	>= 0.0.0	PostgreSQL driver for Elixir	Apache 2.0
ash	~> 3.0	Resource-based framework for domain modeling	MIT
ash_postgres	~> 2.0	AshPostgres adapter — manages migrations and repo	MIT
ash_phoenix	~> 2.0	Integration between Ash and Phoenix	MIT

API & Documentation

Package	Version	Purpose	License
open_api_spex	~> 3.16	OpenAPI 3.0 spec generation and validation	MIT
jason	~> 1.2	Fast JSON encoding/decoding	Apache 2.0

HTTP & Networking

Package	Version	Purpose	License
req	~> 0.5	HTTP client for outgoing requests	Apache 2.0
dns_cluster	~> 0.2.0	DNS-based node clustering	Apache 2.0

Observability

Package	Version	Purpose	License
telemetry_metrics	~> 1.0	Metrics definitions and aggregation	Apache 2.0
telemetry_poller	~> 1.0	Periodic VM and application metrics	Apache 2.0
phoenix_live_dashboard	~> 0.8.3	Real-time metrics dashboard (dev/prod)	MIT

Email

Package	Version	Purpose	License
swoosh	~> 1.16	Email composition and delivery	MIT

Tooling & DX

Package	Version	Purpose	License
igniter	~> 0.3	Code generation and project automation	MIT
credo	~> 1.7	Static code analysis and style enforcement (test only)	MIT

---

Development & Infrastructure

Tool	Purpose
Docker & Docker Compose	Runs PostgreSQL locally without a manual install
.env / .env.example	Environment variable management

---

Updating Dependencies

Elixir

# Update a specific package
mix deps.update <package_name>

# Update all packages
mix deps.update --all

---

Notes

• Ash Framework: This project uses Ash (~> 3.0) as the primary domain layer. Migrations are managed by AshPostgres rather than plain Ecto — always use mix ash_postgres.generate_migrations when changing resources. =======

Getting Started

Prerequisites

• Docker & Docker Compose
• Elixir 1.15+ (for local development)

Quick Start

1. Get your MeteoSIX API Key and add it to .env.
2. Configure your DB credentials in .env.
3. Deploy the app with telemetry: make deploy_with_tel
4. Access Grafana: http://localhost:3000 (admin/admin) main

License

Chronodash is licensed under the GNU GPLv3.