Architecture specifications for observatory instrument control and data reduction software, maintained by the Caltech Optical Observatories (COO) Software Team.
Published documentation: https://caltechopticalobservatories.github.io/coo-software-architecture/
This repository holds specifications, not an implementation.
| Document | What it defines |
|---|---|
| Command-and-Control Design Specification | The minimum command-and-control architecture for an Instrument Control System (ICS): stateful device daemons that own hardware, a shared command contract, command and daemon lifecycles, locally enforced safety, explicit command ownership, and command/event logging. |
| Message Envelope and Payload Design | The ICS messaging protocol: a common envelope carrying protocol metadata (msg_type, trans_id, key, routing, QoS) and payload shapes for requests, acknowledgements, responses, errors, progress events, and status. |
| Data Reduction Pipeline Design Guidelines | The minimum architecture for a Data Reduction Pipeline (DRP): reductions expressed as a DAG of state-aware tasks, pure scientific primitives under thin observable task wrappers, CAL/Quicklook/Science flows joined by cross-flow caching, and a canonical data model. |
Each specification states its scope and non-goals up front, lists required components and contracts, and closes with design rules, anti-patterns, and instrument-specific expansion points.
The documentation is Sphinx with MyST Markdown and Mermaid diagrams.
python -m pip install -r docs/requirements.txt
python -m sphinx -b html docs docs/_build/html
open docs/_build/html/index.htmlThese are the same steps CI runs, so a clean local build is a good check before opening a pull request.
Pull requests are built by the Docs workflow;
merges to main are deployed to GitHub Pages.
To add a specification, create the Markdown file under docs/ and add it
to the toctree in docs/index.md — a page that is not listed
there will not appear in the published site.
Formatting is enforced by pre-commit:
python -m pip install pre-commit
pre-commit install