Chronos-Ledger

From the README

Chronos Ledger

---

Organization Schedule & Attendance Management, self-hosted, offline-first, production-ready.

The Problem

Universities and organizations track attendance on paper, manage timetables in Excel, and learn of staff absences only when members complain. Organization networks are unreliable. Staff don't know where their colleagues are. Visitors have no formal check-in system.

Chronos Ledger solves all of this in a single, self-hosted, Docker-deployable stack that runs entirely on your organization intranet, no cloud subscription, no data leaving your network.

Key Metrics

Quick Start: One Command

# Clone, configure, and launch everything
git clone https://github.com/Life-Experimentalist/chronos-ledger.git
cd chronos-ledger
chmod +x setup.sh && ./setup.sh

setup.sh auto-detects your LAN IP, generates cryptographic secrets, and launches all services. When it finishes:

• App → http://<your-server-ip>
• API docs → http://<your-server-ip>/docs
• Login → admin@org.internal, with the password setup.sh printed (also in .env as INITIAL_ADMIN_PASSWORD)

Want to demo it to someone? ./setup.sh --build --demo boots it with sample data; docs/demo.md has the five-minute walkthrough.

Or pull a published image (no build required)

curl -fsSL https://chronos.vkrishna04.me/compose.yml \
  -o docker-compose.prod.yml

export JWT_SECRET_SIGNING_KEY=$(openssl rand -hex 32)
export DB_PASSWORD=$(openssl rand -base64 24 | tr -d '/+=' | head -c 32)
export GHCR_OWNER=Life-Experimentalist

docker compose -f docker-compose.prod.yml up -d

Pin any release: VERSION=v1.2.0 docker compose -f docker-compose.prod.yml up -d

The compose file pulls from GHCR, which does not rate-limit anonymous pulls of a public image. The same two images go to Docker Hub as well, for anyone who would rather not type a registry prefix:

docker pull vkrishna04/chronos-ledger-backend
docker pull vkrishna04/chronos-ledger-web

Or install the chronos CLI

The CLI writes the configuration, starts the stack, upgrades it with a backup first and diagnoses an install (docs/cli.md). Pick one channel:

curl -fsSL https://chronos.vkrishna04.me/install.sh | sh   # Linux, macOS
brew install life-experimentalist/tap/chronos

# From 0.18.0, also on the package registries
npm i -g chronosledger            # or: npx chronosledger@latest
uv tool install chronosledger     # or: uvx chronosledger@latest
pipx install chronosledger
cargo install --locked chronosledger   # or: cargo binstall chronosledger

npx and uvx reuse a cached copy, so add @latest to get the newest release.

Architecture

  Clients (PWA)                 Organization Server
  ┌─────────────┐              ┌────────────────────────────────────────┐
  │ Member     │              │  Docker network: chronos_net           │
  │ Staff     │──HTTPS/WSS──▶│  ┌──────────┐     ┌────────────────┐  │
  │ Admin       │              │  │  Nginx   │────▶│  FastAPI       │  │
  │ Guest Kiosk │              │  │  :80/443 │     │  :8000         │  │
  └─────────────┘              │  └──────────┘     └───────┬────────┘  │
                               │       │                   │           │
                               │  Static files         ┌───┴──────┐    │
                               │  (Next.js export)     │PostgreSQL│    │
                               │                       │ Redis    │    │
                               └───────────────────────┴──────────┴────┘

Full diagrams with Mermaid charts: docs/architecture.md

Feature Highlights

Geofenced Attendance

Members mark attendance via GPS. The server runs a Haversine distance check, plus an altitude delta (|Δalt| <= 4m) when both the device and the room report an altitude, so that somebody a floor above or below does not register. Altitude is optional on both sides: a fix without one is judged on the horizontal radius alone. The client refuses to mark at all when the reported accuracy is worse than 30m, and the server refuses a fix coarser than GEOFENCE_ACCURACY_FACTOR times the fence radius, which by default is the same 30m on a 15m fence.

4-Tier Staff Location Resolution

Always know where staff are, in priority order:

1. Override: a state_override:<id> value an integration writes to Redis. Chronos never writes one itself, and the tier is skipped when Redis is down.
2. The generated day: the room of a slot they cover, or of their own slot when nobody else covers it. OFF_SITE when that day marks them on leave.
3. Weekly timetable: the room of a slot they lead, on a date the nightly job has not generated yet.
4. Base station: OFF_SITE on a day of approved leave, otherwise their assigned base station.

The full rules are in docs/architecture.md.

Reverse RSVP Absence System

Presence is the default state. Staff file absences rather than confirming presence. Requests route to the line manager for approval. Approved absences cascade ON_LEAVE to every affected ledger entry and fire a WebSocket notification to the staff member.

Offline-First PWA

Organization Wi-Fi drops. Chronos Ledger keeps working:

• Attendance marks queue to IndexedDB and flush on reconnect (Background Sync where available, the app itself otherwise)
• Today's schedule cached locally for 12 hours
• Class reminders fire up to 20 minutes before start, even with the app closed, via periodicsync in the service worker

Real-Time WebSocket Hub

JWT-authenticated persistent connections. Guest handshake requests, absence approvals, and ledger state changes arrive in milliseconds, no polling.

CSV Bulk Import

Drop a member-centric CSV on the Admin dashboard. One upload creates/updates users, activity offerings, master timetable slots, and member registrations atomically and idempotently.

Role Dashboards

Tech Stack

Project Structure

chronos-ledger/
├── .github/
│   ├── workflows/
│   │   ├── ci.yml          # Lint, tests, type-check, build, Trivy, publish, release
│   │   ├── cd.yml          # Build & push to GHCR + Docker Hub (main + releases)
│   │   └── release.yml     # Release Please semver releases (called by ci.yml)
│   └── dependabot.yml      # Automated dep updates (pip, npm, Docker, Actions)
├── assets/
│   ├── logo.svg            # Vector wordmark
│   ├── Logo.png            # Raster logo
│   └── Icon.png            # App icon
├── backend/                # FastAPI application (uv managed)
│   ├── pyproject.toml
│   └── app/
│       ├── core/           # Config, DB, security, Redis, WebSocket manager
│       ├── models/         # SQLAlchemy ORM (9 tables)
│       ├── schemas/        # Pydantic request/response models
│       ├── api/v1/         # Route handlers per domain
│       ├── services/       # Business logic (geo-fence, RSVP, ingestion)
│       └── cron/           # Nightly ledger generator (APScheduler)
├── frontend/               # Next.js 16 PWA (npm managed)
│   ├── public/
│   │   ├── manifest.webmanifest
│   │   └── sw-custom.js    # Background sync + push + periodicsync
│   └── src/
│       ├── app/            # App Router pages per role
│       ├── components/     # Role-scoped UI components
│       ├── hooks/          # useWebSocket, useGeolocation, useAuth, useScheduleNotifications
│       ├── lib/            # Axios API client, IndexedDB helpers, auth utils
│       └── store/          # Zustand: auth + notifications
├── nginx/
│   ├── nginx.conf          # Reverse proxy + static serving + security headers
│   └── Dockerfile          # Multi-stage: Next.js build → nginx image (for GHCR)
├── docs/
│   ├── openapi.yaml        # Static OpenAPI 3.1 contract (all 30+ endpoints)
│   ├── architecture.md     # Mermaid system diagrams
│   ├── data-model.md       # Mermaid ERD (all 9 tables)
│   ├── flows.md            # Sequence diagrams (attendance, RSVP, guest, cron)
│   ├── api.md              # Human-readable API reference with examples
│   └── deployment.md       # Deployment guide with topology diagram
├── bin/
│   ├── chronos_intranet_autodiscover.sh
│   └── chronos_maintenance_vault.sh
├── docker-compose.yml      # Local dev / self-build (builds from source)
├── docker-compose.prod.yml # Production (pulls from GHCR, no build)
├── setup.sh                # One-command setup script
├── .env.example            # Environment template
└── version.txt             # Source of truth for semver (managed by Release Please)

Local Development

Backend

cd backend
uv sync                         # install deps (including dev)
uv run uvicorn app.main:app --reload --port 8000   # builds the schema on start

API: http://localhost:8000 · Swagger: http://localhost:8000/docs

Swagger and ReDoc follow DOCS_ENABLED, which is unset here, so they are on in development and off under APP_ENV=production.

Frontend

cd frontend
npm install
NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1 \
NEXT_PUBLIC_WS_URL=ws://localhost:8000/ws \
npm run dev

App: http://localhost:3000

CI/CD Pipeline

Pull Request ──▶ ci.yml ──▶ ruff format + ruff check
                       ├──▶ pytest
                       ├──▶ eslint + tsc + next build
                       ├──▶ Trivy scan (critical fails the build)
                       └──▶ Docker build check (no push)

Push to main ──▶ ci.yml (all of the above)
                       ├──▶ every gate green ──▶ cd.yml
                       │                         └──▶ Push to GHCR + Docker Hub
                       │                               (sha tag + latest)
                       └──▶ every gate green ──▶ release.yml
                                                 └──▶ Release Please opens
                                                      or updates a release PR

Merge release PR ──▶ ci.yml ──▶ release.yml ──▶ GitHub Release created
                                            ├──▶ CHANGELOG.md updated
                                            ├──▶ version.txt bumped
                                            └──▶ cd.yml (version tag) ──▶ GHCR + Docker Hub, vX.Y.Z

Published images, one build pushed to both:

Both carry the same tags: latest, main, a short commit sha, and vX.Y.Z on a release. GHCR is the one the compose file points at because it does not rate-limit anonymous pulls of a public image; Docker Hub does. A fork that sets neither DOCKERHUB_NAMESPACE nor DOCKERHUB_TOKEN publishes to GHCR alone.

Every image carries an SBOM and build provenance, plus a Sigstore-signed SLSA attestation naming the workflow and commit it was built from:

gh attestation verify oci://ghcr.io/life-experimentalist/chronos-ledger-backend:latest \
  --owner Life-Experimentalist

docs/faq.md has the Docker Hub form and the buildkit attestations that ride along inside the image itself.

Environment Reference

See .env.example for the full template.

First Boot Credentials

The schema step the server runs on start creates one organization admin. It seeds a hash of a random string it throws away, so the account exists, nothing can log into it, and this repository publishes no password for anyone to find. What the first password is comes from your .env:

setup.sh generates that password and prints it once, in its summary. It is applied on boot while the account is still waiting for a password of its own, and does nothing once you have logged in and chosen one. Until you have, the account is refused by every endpoint except the password change itself, so the first login is the only thing it can do: use Admin Portal → Profile → Change Password, or the Onboarding Wizard, which opens on its own.

Documentation

Telemetry

Telemetry is off by default, a stock build sends nothing anywhere, and the ghcr.io image is built from nginx/Dockerfile with those same defaults. Nothing in a default install reaches a host you do not run.

If you turn it on, Chronos Ledger reports anonymous, aggregate view counts to a CFlair-Counter instance, a privacy-first, self-hostable counter. No IP addresses, usernames, or session data are collected or transmitted.

What is tracked, if you opt in

Opt in

Set both at build time, either is enough to keep it off:

NEXT_PUBLIC_TELEMETRY_ENABLED=true
NEXT_PUBLIC_TELEMETRY_ENDPOINT=https://counter.example.internal   # a CFlair-Counter you run

An empty endpoint disables the pings regardless of the enabled flag.

Per-browser opt out: once enabled, Admin Dashboard → Overview → Privacy & Telemetry toggles it off for that browser. The preference is stored locally and persists across sessions.

Contributing

Contributions are welcome. Please:

1. Fork the repo and create a feature branch.
2. Follow Conventional Commits so Release Please can generate the changelog.
3. Open a PR: CI runs automatically (lint, tests, type-check, build, Trivy scan).
4. All checks must pass before merge.

Commit examples:

feat: add unit-level attendance export to CSV
fix: resolve geofence false positive on altitude boundary
perf: cache staff location resolver result in Redis
security: upgrade cryptography to 44.0.1

License

Copyright 2026 Chronos Ledger Contributors

Licensed under the Apache License, Version 2.0.