Project Atlas AetherDev project hub
Atlas project testing

titanhst_sync

A fast, safe, and auditable commandline tool written in Rust to synchronize users from a CSV file into Titan HST. It creates and updates users, manages site role membership, removes users from sites when they no longer appear in your source, and produces humanfriendly reports (plain text, HTML, and email). It ingests Config with API key and SMTP settings; CSV input and produces Titan HST user/role updates; reports in logs/.

Type
Component
Lifecycle
Active
Last touched
2025-09-14
Visibility
Public

Purpose

A fast, safe, and auditable commandline tool written in Rust to synchronize users from a CSV file into Titan HST. It creates and updates users, manages site role membership, removes users from sites when they no longer appear in your source, and produces humanfriendly reports (plain text, HTML, and email).

Current state

Last touched: 2025-09-14. Functionality and completeness: Core sync and reporting flows are implemented; tests and CI are pending.

Next step

Add baseline automated tests to cover critical flows; Add CI pipeline for build/test/lint; Document deployment/runtime environment (or add Dockerfile); Document interfaces (CLI flags, API endpoints, file formats); Add structured logging and basic health checks.

Interfaces

Inputs
  • Config with API key and SMTP settings
  • CSV input
  • Configuration files (TOML)
  • CSV files
Outputs
  • Titan HST user/role updates
  • reports in logs/
  • HTML reports
  • Text reports

Reality to Action trace

Reality Ingestion

Contributes in this stage.

Canonical Storage

Not in scope.

Automation Engines

Not in scope.

Human Interfaces

Contributes in this stage.

Operational Adoption

Contributes in this stage.

Core workflow

TBD. Document the 5-10 steps that define the core workflow.

Artifacts

  • CSV requires external_id, first_name, last_name, email, site_name, role_names

Operational notes

Constraints and scars

  • Safety thresholds must be tuned per district size; CSV schema drift can break mapping.

Reliability posture

Failure modes and safe behavior: Guardrails abort on large deltas; dry-run for validation. Idempotency / retries / batching behavior: Re-running with same CSV results in no changes; HTTP retries not documented.

Observability

  • Logs: Rust logging framework detected (log/tracing/env_logger).
  • Metrics/health checks: None documented; use reports and logs
  • Logs: Written under logs/ with HTML/text reports per run.

Security and privacy

Keep API keys and SMTP credentials out of source control. Prefer environment overrides for secrets. Reports and logs may contain user identifying information; handle according to your policies.

Dependencies

Upstream
  • Titan HST API
  • optional SMTP relay

Ownership

Owners

Josh Barton

Users

Josh Barton (owner)

titanhst_sync

Architecture & Major Components

  • High-level diagram (text):

    • Entry/trigger -> core logic -> outputs (details per docs below)

  • Entry points: src/main.rs

  • Top-level folders: data, docs, logs, src

  • Key abstractions: Safety preflight guardrails, site/role mapping, report generation

Setup / Build / Run

  • Build system(s): Cargo.
  • Build with Cargo and provide a config.toml + CSV input file.
  • Use –dry_run to review the HTML/text report before applying changes.