Project Atlas AetherDev project hub
Atlas project production

informedk12-sync

Supports response exports (JSONL/CSV) with configurable field expansion and column selection. Data-source uploads include optional CSV header validation and a dry-run safety mode. It ingests API token (env/flag), CSV file, campaign/data-source IDs and produces JSONL/CSV export files; InformedK12 data-source updates.

Type
Field Tool
Lifecycle
Active
Last touched
2025-09-08
Visibility
Public

Purpose

Supports response exports (JSONL/CSV) with configurable field expansion and column selection. Data-source uploads include optional CSV header validation and a dry-run safety mode.

Current state

Last touched: 2025-09-08. Functionality and completeness: Core CLI functions are implemented; a full README and operational runbooks 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
  • API token (env/flag), CSV file, campaign/data-source IDs
  • InformedK12 API token
  • Campaign or data-source IDs
  • CSV files
Outputs
  • JSONL/CSV export files
  • InformedK12 data-source updates
  • CSV files

Reality to Action trace

Reality Ingestion

Contributes in this stage.

Canonical Storage

Not in scope.

Automation Engines

Contributes in this stage.

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

  • Uploads require headers when `--require-headers` is set; exports flatten nested JSON fields and allow custom column lists

Operational notes

Constraints and scars

  • API rate limits and response pagination require careful use of `page_size`, `since`, and `max_pages` to keep exports bounded.

Reliability posture

Failure modes and safe behavior: Auth or schema errors abort the run without partial writes; API errors surface with HTTP status context. Idempotency / retries / batching behavior: Retries with exponential backoff (including 429 Retry-After); uploads overwrite data source contents.

Observability

  • Logs: Tracing to stdout includes CSV summaries, page counts, and request statuses
  • Metrics/health checks: None built-in; rely on exit codes and API responses
  • Logs: tracing to stdout, including CSV header/row counts and request status summaries.

Security and privacy

Sensitive secret material detected in informedk12-sync/examples.md; ensure it is excluded from docs and CI.

Dependencies

Upstream
  • InformedK12 API (`/campaigns/{id}/responses`, `/data_sources/{id}/csv`)

Ownership

Owners

Josh Barton

Users

Josh Barton (owner)

informedk12-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: releases, src

  • Key abstractions: CLI subcommands for export and data-source upload, CSV header validation, JSON flattening for CSV, exponential backoff retries

Setup / Build / Run

  • Build system(s): Cargo.